PortalJS — New Portal

Overview

Scaffold a production-ready PortalJS data portal from a brief. The skill is interactive: if the brief is thin it interviews the user in three short rounds (mapped to the template's three surfaces — Home, Catalog, Showcase), echoes a brief back for confirmation, then copies examples/portaljs-catalog (locally or via a remote tiged fetch), substitutes placeholder tokens, sets the namespace mode, seeds any datasets named in the interview, installs dependencies, and verifies the scaffold with a type check.

Prerequisites

• Node.js >=22 and npm available on PATH.
• Network access, unless a current local checkout of the portaljs repo is available (the resolver defaults to a remote fetch of the template).
• A destination directory name that does not already contain files (or user consent to overwrite one that does).

Instructions

The canonical, full step-by-step workflow is .claude/commands/portaljs-new-portal.md — the single source of truth. Read and follow it when executing. Summary:

1. Interview the user in up to three rounds — Home/basics, Catalog & discovery (datasets, namespace mode theme vs owner), Showcase/views — skipping any round already answered by the input brief. Accept "use defaults" at any point.
2. Confirm a short brief (name, slug, description, namespace, datasets, views) before building.
3. Resolve the template source: prefer a remote tiged fetch of examples/portaljs-catalog at main (or PORTALJS_TEMPLATE_REF); use a local checkout only when it is current (has pages/[owner]/[slug].tsx) and the destination is outside that repo.
4. Materialize the template into ./PROJECT_SLUG, asking first if the destination already exists and is non-empty.
5. Substitute __PROJECT_NAME__, __PROJECT_SLUG__, __DESCRIPTION__ tokens across all files with perl -pi, escaping /, \, and & in the values.
6. Set NAMESPACE_TYPE ('theme' or 'owner') in lib/datasets.ts per the interview.
7. Seed datasets captured in Round 2 (via /portaljs-add-dataset or by hand), or clear datasets.json to [] if none were named.
8. Run npm install inside the scaffolded portal.
9. Verify with npx tsc --noEmit (never next build here — it would corrupt a running dev server's .next/ directory).
10. Report the scaffolded routes, namespace mode, and next steps.

Output

• Created: a new directory ./PROJECT_SLUG/ containing the full examples/portaljs-catalog template with tokens substituted.
• Modified: lib/datasets.ts (NAMESPACE_TYPE); datasets.json (seeded datasets or cleared to []).
• Verified: npx tsc --noEmit passes inside the scaffolded portal.
• Result: a runnable portal at ./PROJECT_SLUG with Home (/), Catalog (/search), and Showcase (/@<namespace>/<slug>) surfaces wired up.

Error Handling

Symptom	Cause	Fix
DIR_EXISTS	./PROJECT_SLUG already exists and is non-empty	Ask the user for a different name or consent to remove it; then proceed.
Remote fetch fails	Bad PORTALJS_TEMPLATE_REF, network outage, or tiged unavailable	Tell the user plainly and ask to retry, use a different ref, or check network.
Stale local scaffold (pages/datasets/[slug].tsx)	Old local clone missing pages/[owner]/[slug].tsx	Resolver already falls back to remote in this case — do not force local mode.
npm install fails	Node <22 or no network	Report the error and ask the user to check Node version and connectivity.
tsc --noEmit fails	Token substitution or manifest error	Print the log and fix before reporting success — never report success with a failing type check.

Examples

Example 1 — Full brief up front

/portaljs-new-portal Auckland Open Data Portal — datasets published by several council
departments (multiple publishers). Start with ./data/parks.csv and ./data/budget.csv.

Infers name + description, picks NAMESPACE_TYPE = 'owner', asks for namespace values (e.g. parks-dept, finance), confirms the brief, scaffolds the template, and seeds both datasets at /@parks-dept/parks and /@finance/budget.

Example 2 — No arguments, full interview

/portaljs-new-portal

Runs all three interview rounds from scratch, accepting "use defaults" for any round, then confirms the brief before scaffolding.

Example 3 — Single-publisher portal with no datasets yet

/portaljs-new-portal Reference Data Hub — a single-team reference catalog, no data yet.

Picks NAMESPACE_TYPE = 'theme' with namespace reference, clears datasets.json to [], and reports /portaljs-add-dataset as the next step.

Resources

• Full workflow: .claude/commands/portaljs-new-portal.md
• Template and token reference: references/reference.md
• Related skills: portaljs-add-dataset, portaljs-add-chart, portaljs-add-map, portaljs-connect-ckan
• PortalJS documentation: https://portaljs.org