SkillAgentSearch skills...

portaljs-deploy

Deploy a PortalJS portal to PortalJS Arc — Datopian-managed static hosting on Cloudflare. Builds a static export, uploads it, and returns a live <slug>.arc.portaljs.com URL. One command, one target.

Install / Use

npx skills add datopian/portaljs

Installs into whichever agent you are using.

About this skill
⚡

Claude Commands

Claude Code slash commands

Quality Score

94/100

Category

Operations

Supported Platforms

Claude Code

Our assessment of portaljs-deploy

portaljs-deploy scores 94/100 on our quality scale, 132nd of 745 Operations skills we index (top 18%).

Its Claude Commands is 17 KB long, well organised into 19 sections with 9 code examples: a thorough specification that gives an agent plenty to work with.

With 2,356 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
14/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so portaljs-deploy is actively maintained.
  • Our last check on 2026-11-16 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-09-29. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

portaljs-deploy compared with similar skills

All 4 of these similar skills score higher than portaljs-deploy; compare them before choosing.

SkillScoreStarsUpdatedFormat
portaljs-deploy (this skill)by datopian942.4k2mo agoClaude Commands
claude-memby thedotmack100117.6ktodayCLAUDE.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
Understand-Anythingby Egonex-AI10092.8k1d agoCLAUDE.md

Frequently asked questions

How do I install portaljs-deploy?
Run npx skills add datopian/portaljs. The install tabs above show the steps for each supported agent.
Which AI agents does portaljs-deploy work with?
It is written for Claude Code, as a Claude Commands file. Other agents that read the same format can often use it too.
Is portaljs-deploy safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is portaljs-deploy still maintained?
The repository was last updated about 2 months ago, so portaljs-deploy is actively maintained.

description: Deploy a PortalJS portal to PortalJS Arc — Datopian-managed static hosting on Cloudflare. Builds a static export, uploads it, and returns a live <slug>.arc.portaljs.com URL. One command, one target. allowed-tools: Read, Write, Edit, Bash

/portaljs-deploy

Publish an existing PortalJS portal to PortalJS Arc — Datopian's managed static hosting. The skill builds a static export of the portal, uploads it to the Arc API, and prints a live https://<slug>.arc.portaljs.com URL. Re-running redeploys the same portal (idempotent on the slug).

This is a single-target skill: it deploys to PortalJS Arc only. If you'd rather host the portal yourself, it's a standard static Next.js export — run npm run build and upload out/ to any static host (Vercel, your own Cloudflare, Netlify, S3, …); you don't need this skill for that.

Static only (for now). Arc serves static exports — the catalog template, /portaljs-add-dataset, /portaljs-migrate, and /portaljs-connect-ckan (SSG) all export cleanly. SSR isn't hosted on Arc yet.

Required input — ask, don't error

  • Portal directory (optional) — the portal project (default: current directory). Must be a Next.js portal (package.json with a next dependency).
  • Slug (optional) — the subdomain to publish under (<slug>.arc.portaljs.com). Default: the project's package.json name (or the directory name), slugified. Override with --slug <name>.
  • Auth — a PortalJS Arc token. Read from PORTALJS_TOKEN, else ~/.portaljs/credentials ({ "token": "…" }). If neither is present, sign in on demand (one browser click — device flow, see step 2) to obtain and store one, then continue. Auth is never a separate step the user runs; /portaljs-deploy handles it. Don't ask the user to copy a token by hand.

Steps

1. Gather input + validate the portal

Extract from $ARGUMENTS:

  • PORTAL_DIR (default .), SLUG (default from package.json name / dir, slugified to a DNS label: lowercase, [a-z0-9-], ≤63 chars).

Confirm PORTAL_DIR/package.json exists and lists next. If not:

ERROR: [deploy] NOT_A_PORTAL No Next.js project in <dir> — run from a portal directory.

Reserved slugs (www, api, admin, staging, arc) are not allowed — if the derived slug is reserved or invalid, ask for a --slug.

2. Resolve the Arc token (sign in on demand)

TOKEN="${PORTALJS_TOKEN:-}"
# Read the credentials file as JSON (never require() it — that executes it as JS
# and an extensionless file won't parse the documented {"token":"…"} shape).
if [ -z "$TOKEN" ] && [ -f "$HOME/.portaljs/credentials" ]; then
  TOKEN=$(node -e "const fs=require('fs');try{process.stdout.write(JSON.parse(fs.readFileSync(process.env.HOME+'/.portaljs/credentials','utf8')).token||'')}catch{}")
fi

If TOKEN is empty, sign in inline with the device-authorization flow (the gh auth login / wrangler login model — one browser click, no token copying). Run the self-contained Node script below (Node ≥18; uses global fetch): it requests a device code, opens the browser, polls until you approve, then writes ~/.portaljs/credentials (mode 0600). After it succeeds, re-read TOKEN with the snippet above and continue.

AUTH="${PORTALJS_ARC_AUTH:-https://arc.portaljs.com}"
API="${PORTALJS_ARC_API:-https://api.arc.portaljs.com}"

cat > /tmp/arc-login.mjs <<'EOF'
import { writeFileSync, mkdirSync, chmodSync } from 'node:fs'
import { join } from 'node:path'
import { homedir, hostname } from 'node:os'
import { spawn } from 'node:child_process'

const AUTH = process.env.PORTALJS_ARC_AUTH || 'https://arc.portaljs.com'
const API = process.env.PORTALJS_ARC_API || 'https://api.arc.portaljs.com'
const sleep = (ms) => new Promise((r) => setTimeout(r, ms))

// Best-effort browser open; harmless/no-op in headless/agent sessions.
function openBrowser(url) {
  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open'
  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url]
  try { spawn(cmd, args, { stdio: 'ignore', detached: true }).unref() } catch {}
}

async function main() {
  const start = await fetch(`${AUTH}/device/code`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ label: hostname() }),
  })
  if (!start.ok) throw new Error(`device/code failed: HTTP ${start.status}`)
  const { device_code, user_code, verification_uri, verification_uri_complete, interval, expires_in } = await start.json()

  console.log('\n  Opening your browser… sign in with GitHub, then click "Authorize this device".')
  console.log(`  Didn't get a browser? Open ${verification_uri} and enter: ${user_code}\n`)
  openBrowser(verification_uri_complete || verification_uri)

  const deadline = Date.now() + (expires_in || 900) * 1000
  let wait = (interval || 5) * 1000
  for (;;) {
    if (Date.now() > deadline) throw new Error('Timed out waiting for authorization. Re-run /portaljs-deploy.')
    await sleep(wait)
    const poll = await fetch(`${AUTH}/device/token`, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ device_code }),
    })
    if (poll.status === 200) {
      const { token } = await poll.json()
      const dir = join(homedir(), '.portaljs')
      mkdirSync(dir, { recursive: true })
      const file = join(dir, 'credentials')
      writeFileSync(file, JSON.stringify({ token, api: API }) + '\n', { mode: 0o600 })
      chmodSync(file, 0o600)
      // Confirm + greet by login name.
      let who = ''
      try {
        const me = await fetch(`${API}/v1/whoami`, { headers: { authorization: `Bearer ${token}` } })
        if (me.ok) who = (await me.json()).login
      } catch {}
      console.log(`✓ Logged in${who ? ` as @${who}` : ''}. Credentials saved to ${file}`)
      return
    }
    if (poll.status === 428) continue // authorization_pending
    const body = await poll.json().catch(() => ({}))
    if (poll.status === 400 && body.error === 'expired_token') throw new Error('Code expired. Re-run /portaljs-deploy.')
    throw new Error(`Authorization failed: HTTP ${poll.status} ${body.error || ''}`)
  }
}
main().catch((e) => { console.error(`✖ ${e.message}`); process.exit(1) })
EOF

PORTALJS_ARC_AUTH="$AUTH" PORTALJS_ARC_API="$API" node /tmp/arc-login.mjs
rm -f /tmp/arc-login.mjs

After the flow completes, re-read TOKEN from ~/.portaljs/credentials (snippet above) and continue to step 3. Non-interactive/CI: skip the browser flow by setting PORTALJS_TOKEN (mint a token in the dashboard at https://arc.portaljs.com) — it takes precedence over the file. If the device flow can't run at all (no Node, fully offline), fall back to telling the user:

To deploy to PortalJS Arc you need a token. Sign in at https://arc.portaljs.com and either:
  export PORTALJS_TOKEN=<token>
or save it to ~/.portaljs/credentials as {"token":"<token>"}.
Then re-run /portaljs-deploy.

(The API base URL defaults to https://api.arc.portaljs.com; override with PORTALJS_ARC_API for staging. The auth worker defaults to https://arc.portaljs.com; override with PORTALJS_ARC_AUTH.)

3. Build a static export

Ensure PORTAL_DIR/next.config.js enables static export — it must set output: 'export' and images: { unoptimized: true } (the image optimizer needs a server). If those are missing, add them (preserve the rest of the config), and tell the user you did.

Set shell variables to the values resolved in step 1, then build (these bash blocks are self-contained — set the variables in each block, since shell state doesn't persist):

PORTAL_DIR="."          # ← the portal directory from step 1
cd "$PORTAL_DIR"
npm run build > /tmp/arc-build.log 2>&1
BUILD_EXIT=$?
tail -30 /tmp/arc-build.log

If BUILD_EXIT is non-zero, print the log and fix the error before continuing — never deploy a failing build. Confirm the export landed: PORTAL_DIR/out/index.html must exist.

Static export pre-renders every page at build time. A CKAN/getStaticPaths portal must use fallback: false (the templates do). If the build complains about a dynamic route, that's the cause.

Large data stays in R2 — do not pull it into the export. If the portal uses Git LFS for data (.lfsconfig present, or git lfs ls-files returns entries — epic po-g9y), do not run git lfs pull before building. The deployed portal serves large data straight from Cloudflare R2: each big dataset's resource.path (or file) in datasets.json is an absolute R2 URL, which resourceUrl() passes through unchanged, so the bytes are fetched in the browser from R2 and never copied into out/. Pulling LFS bytes into the working tree would inline them into the static export (bloat); leaving them as pointers would ship broken 130-byte stubs. Either way the next step catches it. A large dataset still referenced by a relative public/data/... path is a misconfiguration for deploy — re-add it with /portaljs-add-dataset (which writes the absolute R2 URL) or, for an OSS self-host without R2, keep it genuinely inline (small).

Pushing new LFS data needs an LFS token, not the deploy token directly. Deploy only reads pointers, so it never needs LFS credentials. When you add data (/portaljs-add-dataset), the same Arc token resolved in step 2 mints a scoped Git LFS token from POST $PORTALJS_ARC_API/v1/repos/<slug>/lfs-token (the arc-api issuer, po-g9y.13) — the RS256 signer stays server-side as a Worker secret. See /portaljs-add-dataset → "Authenticate git-lfs".

4. Verify the export serves data from R2 (no bloat)

A deployed portal must carry zero dataset bytes — large data is served from R2, not the export. Gate the upload on the export-hygiene check, which fails on (1) Git LFS pointer leaks (an LFS-tracked file exported as its stub) and (2) data files at/over the size budget (bytes that should live in R2). Framework chunks under _next/ (incl. duckdb-wasm) are exempt.

PORTAL_DIR="."          # ← the portal directory from step 1
cd "$PORTAL_DIR"
# Prefer the portal's own script (template ships scripts/check-export.mjs); fall back to a
# direct node invocation if an older portal doesn't have the npm script wired.
if npm run | grep -q '^  check-export'; then
  npm run check-export
else
  node scripts/check-export.mjs out 2>/dev/null || true
fi
CHECK_EXIT=$?

If the check fails (non-zero), stop — do not upload. Surface its message: it names the offending files and the fix (reference large data by its absolute R2 URL in datasets.json via /portaljs-add-dataset; don't git lfs pull into the export). Re-run from step 3 once fixed. If a flagged file is a legitimately large app asset (not data), raise the budget: MAX_FILE_MB=<n> npm run check-export. Portals scaffolded before this check shipped won't have the script — skip the gate (the || true above) rather than blocking the deploy.

5. Package + upload

Tar the export (gzip; exclude macOS AppleDouble files) and POST it to the Arc API:

PORTAL_DIR="."          # ← portal directory (step 1)
SLUG="my-portal"        # ← validated slug (step 1)
API="${PORTALJS_ARC_API:-https://api.arc.portaljs.com}"

# Re-resolve the token (self-contained block; see step 2 for the missing-token path).
TOKEN="${PORTALJS_TOKEN:-}"
if [ -z "$TOKEN" ] && [ -f "$HOME/.portaljs/credentials" ]; then
  TOKEN=$(node -e "const fs=require('fs');try{process.stdout.write(JSON.parse(fs.readFileSync(process.env.HOME+'/.portaljs/credentials','utf8')).token||'')}catch{}")
fi
[ -z "$TOKEN" ] && { echo "No Arc token — see step 2."; exit 1; }

cd "$PORTAL_DIR"
COPYFILE_DISABLE=1 tar czf /tmp/arc-deploy.tgz -C out .

# Pass the bearer token via a 0600 curl config file, not argv — so it doesn't leak
# through the process list on shared/CI machines. Remove it right after.
HDR=$(mktemp); chmo

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars2.4k
CategoryOperations
Updated2mo ago
Forks335

Languages

TypeScript

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions