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:
- 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.
- Confirm a short brief (name, slug, description, namespace, datasets, views) before
building.
- 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.
- Materialize the template into
./PROJECT_SLUG, asking first if the destination
already exists and is non-empty.
- Substitute
__PROJECT_NAME__, __PROJECT_SLUG__, __DESCRIPTION__ tokens
across all files with perl -pi, escaping /, \, and & in the values.
- Set
NAMESPACE_TYPE ('theme' or 'owner') in lib/datasets.ts per the
interview.
- Seed datasets captured in Round 2 (via
/portaljs-add-dataset or by hand), or
clear datasets.json to [] if none were named.
- Run
npm install inside the scaffolded portal.
- Verify with
npx tsc --noEmit (never next build here — it would corrupt a
running dev server's .next/ directory).
- 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
Source: jeremylongshore/claude-code-plugins-plus-skills → plugins/community/portaljs/skills/portaljs-new-portal/SKILL.md
1---2name: portaljs-new-portal3description: "Scaffold a new PortalJS data portal from a brief. Copies the canonical template from examples/portaljs-catalog and substitutes project tokens. Use when starting a brand-new data portal project from scratch."4allowed-tools: "Read, Write, Edit, Bash(npm:*), Bash(npx:*), Bash(cp:*), Bash(mkdir:*), Bash(git:*)"5category: marketing-and-growth6source_repo: jeremylongshore/claude-code-plugins-plus-skills7source_path: "plugins/community/portaljs/skills/portaljs-new-portal/SKILL.md"8source_url: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/plugins/community/portaljs/skills/portaljs-new-portal/SKILL.md9---101112# PortalJS — New Portal1314## Overview1516Scaffold a production-ready PortalJS data portal from a brief. The skill is17**interactive**: if the brief is thin it interviews the user in three short rounds18(mapped to the template's three surfaces — Home, Catalog, Showcase), echoes a brief19back for confirmation, then copies `examples/portaljs-catalog` (locally or via a20remote `tiged` fetch), substitutes placeholder tokens, sets the namespace mode, seeds21any datasets named in the interview, installs dependencies, and verifies the scaffold22with a type check.2324## Prerequisites2526- Node.js >=22 and npm available on `PATH`.27- Network access, unless a current local checkout of the portaljs repo is available28 (the resolver defaults to a remote fetch of the template).29- A destination directory name that does not already contain files (or user consent30 to overwrite one that does).3132## Instructions3334The canonical, full step-by-step workflow is35[`.claude/commands/portaljs-new-portal.md`](https://github.com/datopian/portaljs/blob/main/.claude/commands/portaljs-new-portal.md) —36the single source of truth. Read and follow it when executing. Summary:37381. Interview the user in up to three rounds — Home/basics, Catalog & discovery39 (datasets, namespace mode `theme` vs `owner`), Showcase/views — skipping any round40 already answered by the input brief. Accept "use defaults" at any point.412. Confirm a short brief (name, slug, description, namespace, datasets, views) before42 building.433. Resolve the template source: prefer a remote `tiged` fetch of44 `examples/portaljs-catalog` at `main` (or `PORTALJS_TEMPLATE_REF`); use a local45 checkout only when it is current (has `pages/[owner]/[slug].tsx`) and the46 destination is outside that repo.474. Materialize the template into `./PROJECT_SLUG`, asking first if the destination48 already exists and is non-empty.495. Substitute `__PROJECT_NAME__`, `__PROJECT_SLUG__`, `__DESCRIPTION__` tokens50 across all files with `perl -pi`, escaping `/`, `\`, and `&` in the values.516. Set `NAMESPACE_TYPE` (`'theme'` or `'owner'`) in `lib/datasets.ts` per the52 interview.537. Seed datasets captured in Round 2 (via `/portaljs-add-dataset` or by hand), or54 clear `datasets.json` to `[]` if none were named.558. Run `npm install` inside the scaffolded portal.569. Verify with `npx tsc --noEmit` (never `next build` here — it would corrupt a57 running dev server's `.next/` directory).5810. Report the scaffolded routes, namespace mode, and next steps.5960## Output6162- **Created:** a new directory `./PROJECT_SLUG/` containing the full63 `examples/portaljs-catalog` template with tokens substituted.64- **Modified:** `lib/datasets.ts` (`NAMESPACE_TYPE`); `datasets.json` (seeded65 datasets or cleared to `[]`).66- **Verified:** `npx tsc --noEmit` passes inside the scaffolded portal.67- **Result:** a runnable portal at `./PROJECT_SLUG` with Home (`/`), Catalog68 (`/search`), and Showcase (`/@<namespace>/<slug>`) surfaces wired up.6970## Error Handling7172| Symptom | Cause | Fix |73| --- | --- | --- |74| `DIR_EXISTS` | `./PROJECT_SLUG` already exists and is non-empty | Ask the user for a different name or consent to remove it; then proceed. |75| 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. |76| 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. |77| `npm install` fails | Node <22 or no network | Report the error and ask the user to check Node version and connectivity. |78| `tsc --noEmit` fails | Token substitution or manifest error | Print the log and fix before reporting success — never report success with a failing type check. |7980## Examples8182### Example 1 — Full brief up front8384```85/portaljs-new-portal Auckland Open Data Portal — datasets published by several council86departments (multiple publishers). Start with ./data/parks.csv and ./data/budget.csv.87```88Infers name + description, picks `NAMESPACE_TYPE = 'owner'`, asks for namespace89values (e.g. `parks-dept`, `finance`), confirms the brief, scaffolds the template, and90seeds both datasets at `/@parks-dept/parks` and `/@finance/budget`.9192### Example 2 — No arguments, full interview9394```95/portaljs-new-portal96```97Runs all three interview rounds from scratch, accepting "use defaults" for any round,98then confirms the brief before scaffolding.99100### Example 3 — Single-publisher portal with no datasets yet101102```103/portaljs-new-portal Reference Data Hub — a single-team reference catalog, no data yet.104```105Picks `NAMESPACE_TYPE = 'theme'` with namespace `reference`, clears `datasets.json` to106`[]`, and reports `/portaljs-add-dataset` as the next step.107108## Resources109110- Full workflow: [`.claude/commands/portaljs-new-portal.md`](https://github.com/datopian/portaljs/blob/main/.claude/commands/portaljs-new-portal.md)111- Template and token reference: [`references/reference.md`](references/reference.md)112- Related skills: `portaljs-add-dataset`, `portaljs-add-chart`, `portaljs-add-map`, `portaljs-connect-ckan`113- PortalJS documentation: <https://portaljs.org>114115---116117**Source:** [`jeremylongshore/claude-code-plugins-plus-skills`](https://github.com/jeremylongshore/claude-code-plugins-plus-skills) → `plugins/community/portaljs/skills/portaljs-new-portal/SKILL.md`
jeremylongshore