jeremylongshore/tons-of-skills-marketplace / plugins/community/portaljs/skills/portaljs-deploy
portaljs-deploy
VerifiedDeploy 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.3 KB |
| references/reference.md | markdown | 4.2 KB |
SKILL.md
View on GitHub---
name: portaljs-deploy
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. Use when a portal is ready to publish or redeploy to a live URL.
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(npx:*), Bash(curl:*)
version: 1.0.0
author: Datopian <hello@datopian.com>
license: MIT
compatibility: Claude Code with PortalJS portals (Next.js 14, React 18, Node 18+). Runs from any project via the plugin, a personal ~/.claude/commands install, or a portaljs clone.
tags:
- portaljs
- data-portal
- deploy
- hosting
- cloudflare
- static
---
# 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`](https://github.com/datopian/portaljs/blob/main/.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`).
2. Resolve the Arc token: read `PORTALJS_TOKEN`, else `~/.portaljs/credentials`; if
missing, run the device-authorization sign-in flow and save the returned token.
3. Ensure `next.config.js` sets `output: 'export'` and `images: { unoptimized: true }`,
then run `npm run build`; stop if the build fails.
4. 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.
5. 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.
6. 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
```bash
export PORTALJS_TOKEN=arc_live_xxxxxxxx
/portaljs-deploy ./portals/city-budget --slug city-budget
```
## Resources
- Full workflow: [`.claude/commands/portaljs-deploy.md`](https://github.com/datopian/portaljs/blob/main/.claude/commands/portaljs-deploy.md)
- Deploy internals reference: [`references/reference.md`](references/reference.md)
- Related skills: `portaljs-new-portal`, `portaljs-add-dataset`, `portaljs-connect-ckan`
- PortalJS Arc dashboard (sign in, manage tokens): <https://arc.portaljs.com>
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |