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. Use when a portal is ready to publish or redeploy to a live URL.

v1.0.0
Datopian
MIT

Allowed Tools

ReadWriteEditBash(npm:*)Bash(npx:*)Bash(curl:*)

Provided by Plugin

portaljs

Agentic skills for building PortalJS data portals — recommend an architecture, scaffold a portal, add datasets, charts, and maps, connect a CKAN backend, deploy, and audit data quality.

community v0.1.0
View Plugin

Installation

This skill is included in the portaljs plugin:

/plugin install portaljs@claude-code-plugins-plus

Click to copy

Instructions

PortalJS — Deploy

Overview

Publish an existing PortalJS portal to PortalJS Arc — Datopian's managed static

hosting on Cloudflare. Build a static export, upload it to the Arc API, and print 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 Arc only. For self-hosting, run

npm run build and upload out/ to any static host; no skill required for that path.

Arc serves static exports only — SSR is not hosted on Arc yet.

Prerequisites

  • A PortalJS portal directory with a package.json that lists next as a dependency.
  • Node 18+ and npm on PATH (the Arc device-login flow uses Node's global fetch).
  • curl and tar available for packaging and upload.
  • A PortalJS Arc token — read from PORTALJS_TOKEN, or ~/.portaljs/credentials

({"token":"…"}). If neither exists, the skill signs in on demand via a device-code

flow; no manual token copying required.

  • If the portal stores large data in Git LFS/R2, do not run git lfs pull before

deploying — large datasets are served from Cloudflare R2 via absolute URLs in

datasets.json, not copied into the export.

Instructions

The canonical, full step-by-step workflow is

.claude/commands/portaljs-deploy.md — the

single source of truth. Read and follow it when executing. Summary:

  1. Gather input — portal directory (default .) and slug (default from package.json

name or directory name, slugified). Confirm the directory is a Next.js project; reject

reserved slugs (www, api, admin, staging, arc).

  1. Resolve the Arc token: read PORTALJS_TOKEN, else ~/.portaljs/credentials; if

missing, run the device-authorization sign-in flow and save the returned token.

  1. Ensure next.config.js sets output: 'export' and images: { unoptimized: true },

then run npm run build; stop if the build fails.

  1. Verify the export carries no dataset bytes — run npm run check-export (or

scripts/check-export.mjs) to catch Git LFS pointer leaks and oversized data files.

  1. Tar the out/ directory and POST it to $PORTALJSARCAPI/v1/deploy?slug=

with the bearer token; handle 200/401/409/400/413 responses distinctly.

  1. Report the live URL, file count, upload size, and R2-vs-inline dataset counts.

Output

  • Modified (if needed): next.config.js — adds output: 'export' and

images: { unoptimized: true } when absent, preserving the rest of the config.

  • Created (on first sign-in): ~/.portaljs/credentials (mode 0600).
  • Verified: npm run build exits 0, out/index.html exists, the export-hygiene

check passes.

  • Result: the portal is live at https://SLUG.arc.portaljs.com; re-running updates

the same slug in place.

Error Handling

Symptom Cause Fix
NOTAPORTAL error No next dependency found in PORTAL_DIR/package.json Run from a valid portal directory, or pass the correct path.
Slug rejected Derived slug is reserved (www, api, …) or not a valid DNS label Pass an explicit --slug .
Build fails (non-zero exit) App/config error surfaced in npm run build Print the log, fix the error, never deploy a failing build.
check-export fails Git LFS pointer leaked into out/, or a data file exceeds the size budget Reference large data by absolute R2 URL via portaljs-add-dataset; don't git lfs pull before building.
401 on upload Token invalid, expired, or revoked Re-run the device sign-in flow once, retry the upload; stop if it 401s again.
409 on upload Slug already taken by another account Choose a different --slug.
400 / 413 on upload Malformed slug or export too large Read the JSON error field and address the specific cause.

Examples

Example 1 — Deploy the current directory with the default slug


/portaljs-deploy

Example 2 — Deploy with an explicit slug


/portaljs-deploy --slug my-open-data

Example 3 — Non-interactive deploy from CI with a token env var


export PORTALJS_TOKEN=arc_live_xxxxxxxx
/portaljs-deploy ./portals/city-budget --slug city-budget

Resources

Ready to use portaljs?

Related Skills

agent-patterns

'Execute this skill should be used when the user asks about "SPAWN REQUEST.

Read

anti-deception

Use BEFORE responding when the user's request shows pressure to validate or agree ("tell them what they want", "make them happy", "convince them"), manufactured urgency (artificial deadline), authority appeals (citing investors, advisors, lawyers, experts), demands to certify without evidence, requests to soften an honest assessment, "help me convince X of Y" or "how do I get X to agree" framings where Y is dubious, asking you to commit to numbers beyond data, framing a wrong assumption as fact, or any setup where the obvious helpful answer would compromise honesty.

mcp__ejentum__anti-deception

api-contract

'Configure this skill should be used when the user asks about "API contract",.

Read

arcgis-to-portaljs

Migrate a whole ArcGIS Hub site into a PortalJS Arc portal end-to-end.

ReadWriteEdit

boycott-filter

"Personal boycott list \u2014 users can conversationally tell the agent\.

Bash(curl:*)

claude-reflect

'Execute self-learning system that captures corrections during sessions.

ReadWriteEdit