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:
- 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).
- Resolve the Arc token: read
PORTALJS_TOKEN, else ~/.portaljs/credentials; if
missing, run the device-authorization sign-in flow and save the returned token.
- Ensure
next.config.js sets output: 'export' and images: { unoptimized: true },
then run npm run build; stop if the build fails.
- 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.
- Tar the
out/ directory and POST it to $PORTALJS_ARC_API/v1/deploy?slug=<slug>
with the bearer token; handle 200/401/409/400/413 responses distinctly.
- 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 |
NOT_A_PORTAL 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 <name>. |
| 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
Source: jeremylongshore/claude-code-plugins-plus-skills → plugins/community/portaljs/skills/portaljs-deploy/SKILL.md
1---
2name: portaljs-deploy
3description: "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."
4allowed-tools: "Read, Write, Edit, Bash(npm:*), Bash(npx:*), Bash(curl:*)"
5category: devops-and-infra
6source_repo: jeremylongshore/claude-code-plugins-plus-skills
7source_path: "plugins/community/portaljs/skills/portaljs-deploy/SKILL.md"
8source_url: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/plugins/community/portaljs/skills/portaljs-deploy/SKILL.md
9---
10
11
12# PortalJS — Deploy
13
14## Overview
15
16Publish an existing PortalJS portal to **PortalJS Arc** — Datopian's managed static
17hosting on Cloudflare. Build a static export, upload it to the Arc API, and print a live
18`https://SLUG.arc.portaljs.com` URL. Re-running redeploys the same portal (idempotent on
19the slug). This is a single-target skill — it deploys to Arc only. For self-hosting, run
20`npm run build` and upload `out/` to any static host; no skill required for that path.
21Arc serves static exports only — SSR is not hosted on Arc yet.
22
23## Prerequisites
24
25- A PortalJS portal directory with a `package.json` that lists `next` as a dependency.
26- Node 18+ and npm on PATH (the Arc device-login flow uses Node's global `fetch`).
27- `curl` and `tar` available for packaging and upload.
28- A PortalJS Arc token — read from `PORTALJS_TOKEN`, or `~/.portaljs/credentials`
29 (`{"token":"…"}`). If neither exists, the skill signs in on demand via a device-code
30 flow; no manual token copying required.
31- If the portal stores large data in Git LFS/R2, do not run `git lfs pull` before
32 deploying — large datasets are served from Cloudflare R2 via absolute URLs in
33 `datasets.json`, not copied into the export.
34
35## Instructions
36
37The canonical, full step-by-step workflow is
38[`.claude/commands/portaljs-deploy.md`](https://github.com/datopian/portaljs/blob/main/.claude/commands/portaljs-deploy.md) — the
39single source of truth. Read and follow it when executing. Summary:
40
411. Gather input — portal directory (default `.`) and slug (default from `package.json`
42 name or directory name, slugified). Confirm the directory is a Next.js project; reject
43 reserved slugs (`www`, `api`, `admin`, `staging`, `arc`).
442. Resolve the Arc token: read `PORTALJS_TOKEN`, else `~/.portaljs/credentials`; if
45 missing, run the device-authorization sign-in flow and save the returned token.
463. Ensure `next.config.js` sets `output: 'export'` and `images: { unoptimized: true }`,
47 then run `npm run build`; stop if the build fails.
484. Verify the export carries no dataset bytes — run `npm run check-export` (or
49 `scripts/check-export.mjs`) to catch Git LFS pointer leaks and oversized data files.
505. Tar the `out/` directory and `POST` it to `$PORTALJS_ARC_API/v1/deploy?slug=<slug>`
51 with the bearer token; handle 200/401/409/400/413 responses distinctly.
526. Report the live URL, file count, upload size, and R2-vs-inline dataset counts.
53
54## Output
55
56- **Modified (if needed):** `next.config.js` — adds `output: 'export'` and
57 `images: { unoptimized: true }` when absent, preserving the rest of the config.
58- **Created (on first sign-in):** `~/.portaljs/credentials` (mode `0600`).
59- **Verified:** `npm run build` exits 0, `out/index.html` exists, the export-hygiene
60 check passes.
61- **Result:** the portal is live at `https://SLUG.arc.portaljs.com`; re-running updates
62 the same slug in place.
63
64## Error Handling
65
66| Symptom | Cause | Fix |
67| --- | --- | --- |
68| `NOT_A_PORTAL` error | No `next` dependency found in `PORTAL_DIR/package.json` | Run from a valid portal directory, or pass the correct path. |
69| Slug rejected | Derived slug is reserved (`www`, `api`, …) or not a valid DNS label | Pass an explicit `--slug <name>`. |
70| Build fails (non-zero exit) | App/config error surfaced in `npm run build` | Print the log, fix the error, never deploy a failing build. |
71| `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. |
72| `401` on upload | Token invalid, expired, or revoked | Re-run the device sign-in flow once, retry the upload; stop if it 401s again. |
73| `409` on upload | Slug already taken by another account | Choose a different `--slug`. |
74| `400` / `413` on upload | Malformed slug or export too large | Read the JSON `error` field and address the specific cause. |
75
76## Examples
77
78### Example 1 — Deploy the current directory with the default slug
79
80```
81/portaljs-deploy
82```
83
84### Example 2 — Deploy with an explicit slug
85
86```
87/portaljs-deploy --slug my-open-data
88```
89
90### Example 3 — Non-interactive deploy from CI with a token env var
91
92```bash
93export PORTALJS_TOKEN=arc_live_xxxxxxxx
94/portaljs-deploy ./portals/city-budget --slug city-budget
95```
96
97## Resources
98
99- Full workflow: [`.claude/commands/portaljs-deploy.md`](https://github.com/datopian/portaljs/blob/main/.claude/commands/portaljs-deploy.md)
100- Deploy internals reference: [`references/reference.md`](references/reference.md)
101- Related skills: `portaljs-new-portal`, `portaljs-add-dataset`, `portaljs-connect-ckan`
102- PortalJS Arc dashboard (sign in, manage tokens): <https://arc.portaljs.com>
103
104---
105
106**Source:** [`jeremylongshore/claude-code-plugins-plus-skills`](https://github.com/jeremylongshore/claude-code-plugins-plus-skills) → `plugins/community/portaljs/skills/portaljs-deploy/SKILL.md`
jeremylongshore