ArcGIS Hub → PortalJS

Overview

Migrate an entire ArcGIS Hub open-data site into a PortalJS Arc portal in one pass.

Every Hub site is machine-readable — a DCAT-US catalog at /data.json, with every dataset

backed by an ArcGIS REST FeatureService — so migration is a **harvest → export → convert →

publish → verify** pipeline that runs almost fully automated on the operator's machine, no

server-side compute. The tooling is the reusable arcgis-to-portaljs migrator: input is one

Hub URL, output is a ready-to-deploy PortalJS catalog plus a parity report.

The skill is an orchestrator: it reuses the DCAT-US harvest from portaljs-migrate, the

ogr2ogr/tippecanoe/duckdb dual-tier conversion from portaljs-add-geo, and the bulk

Git-LFS → R2 push from portaljs-migrate. Its novel parts are the FeatureService REST export

loop (paged features, not just a link) and the source-vs-derived parity report.

Prerequisites

• A scaffolded PortalJS portal whose template ships components/MapPreview.tsx and

components/GeoQuery.tsx (PR #1647 or later). Run portaljs-new-portal first if none.

• Native CLIs: GDAL (ogr2ogr, ogrinfo), tippecanoe, duckdb (with spatial),

and jq. macOS: brew install gdal tippecanoe duckdb jq; Debian/Ubuntu:

apt-get install gdal-bin duckdb jq plus tippecanoe (apt or build from source); Windows via

WSL. The skill hard-stops with the install hint if any is missing.

• Arc credentials for the Git-LFS → R2 push (the token portaljs-deploy resolves), or an OSS

self-hosted Giftless.

Instructions

The canonical, full step-by-step workflow is

.claude/commands/arcgis-to-portaljs.md

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

1. Gather input — Hub URL, portal directory, project slug, optional flags (--limit,

--only, --dry-run, --namespace-mode). Interview if missing; never dead-end.

1. Check native tools (ogr2ogr, tippecanoe, duckdb + spatial, jq). Any missing →

print the per-OS install and stop.

1. Validate the portal directory and confirm the geo showcase components exist.
2. Harvest the Hub /data.json (reuse the portaljs-migrate DCAT-US map) and classify each

item: vector (FeatureSe

PortalJS — Add Chart

Overview

Add a visualization to a dataset's showcase in a PortalJS portal. The skill installs

recharts (added directly — never @portaljs/components), writes a reusable client-side

Chart component into components/, and renders a into the Views section

of the showcase route pages/[owner]/[slug].tsx for one chosen dataset. The chart reads the

same /public/data/ the showcase

Five chart types are supported: line, bar, area, pie, and scatter.

Prerequisites

• A scaffolded PortalJS portal (see portaljs-new-portal).
• The target dataset already registered in datasets.json (see portaljs-add-dataset).
• components/ui/parseCsv.ts present (ships with the template).
• Node 18+ and npm available in the portal directory.

Instructions

The canonical, full step-by-step workflow is

.claude/commands/portaljs-add-chart.md —

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

1. Gather input — dataset slug, X column, Y column(s), chart type (default line), portal

directory. If any is missing, interview the user; never dead-end on a missing value.

1. Resolve the dataset from datasets.json (namespace, file, format).
2. Validate that the X and every Y column exist in the data file's header; warn on

non-numeric Y columns (values are coerced with Number()).

1. Install the chart library: npm install recharts@^2.15.0.
2. Write components/Chart.tsx (idempotent — do not overwrite a customized component).
3. Render into the Views section, gated on the dataset's (namespace, slug) so

other showcases are unaffected. Extend an existing view-dispatch block, do not overwrite.

1. Verify with npx tsc --noEmit.
2. Report the component, route, and dependency added.

Output

• Created: components/Chart.tsx (recharts wrapper, if absent).
• Modified: pages/[owner]/[slug].tsx (import + gated in Views);

package.json (recharts@^2.15.0).

• Verified: npx tsc --noEmit passes.
• Result: the chart renders at /@/ under a "Views" heading.

Error Handling<

portaljs-add-dataset View full skill →

Add a dataset (CSV, TSV, JSON, or GeoJSON) to an existing PortalJS portal.

ReadWriteEditBash(npm:*)Bash(npx:*)Bash(git:*)Bash(curl:*)Bash(mkdir:*)Bash(cp:*)WebFetch

PortalJS — Add Dataset

Overview

Register a dataset in a PortalJS (portaljs-catalog) portal. The skill appends one entry to

datasets.json — the single source of truth for the catalog — and routes the underlying

bytes by source first, then size: a local file defaults to R2 via Git LFS, a remote URL

defaults to passthrough (no copy). No per-dataset page is created; the catalog at /search

lists the new entry and the dynamic showcase route pages/[owner]/[slug].tsx renders it

automatically at /@/. Supported formats for the showcase preview: CSV,

TSV, JSON (array), and GeoJSON.

Prerequisites

• A scaffolded PortalJS portal (see portaljs-new-portal) with datasets.json,

package.json, and pages/[owner]/[slug].tsx present.

• The source data: a local file path or a publicly reachable URL.
• For the R2/Git LFS default route: git and git-lfs installed, and an Arc account token

(or an OSS Giftless key) to mint a push-scoped LFS credential.

• Node 18+ and npm available in the portal directory.

Instructions

The canonical, full step-by-step workflow is

.claude/commands/portaljs-add-dataset.md —

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

1. Gather input from $ARGUMENTS — source (file path or URL), portal directory (default

.), dataset name/slug, description, namespace. If the source is missing, interview the

user; never dead-end.

1. Validate the portal directory: confirm datasets.json, package.json, and

pages/[owner]/[slug].tsx exist.

1. Detect the format from the file extension, URL extension, or Content-Type header

(CSV, TSV, JSON array, or GeoJSON); reject anything else and ask for a conversion.

1. Route the data by source: remote URL → passthrough (default) or adopt into R2 (opt-in);

local file → R2 via Git LFS (default) or inline into public/data/ (fenced exception for

bundled samples or an OSS-no-R2 fallback).

1. Append one entry to datasets.json — slug, namespace, name, description, file

(the routed path/URL), format — keeping (namespace, slug) unique.

1. Verify the build with npx next build; fix errors (commonly malformed JSON) before

reporting success.

1. Report the route taken, the manifest change,

portaljs-add-dcat View full skill →

Make a PortalJS portal harvestable by national/EU/US open-data portals — emit standards-compliant DCAT catalog feeds (DCAT 2/3, DCAT-AP, DCAT-US, national profiles) in JSON-LD, Turtle, and RDF/XML at build, with autodiscovery and per-profile conformance checking.

ReadWriteEditBash(npm:*)Bash(npx:*)Bash(node:*)WebFetch

PortalJS — Add DCAT

Overview

Turn an existing PortalJS (portaljs-catalog) portal into a harvestable data catalog.

PortalJS is Frictionless-native — a dataset is a Data Package (see

portaljs-define-schema) — and DCAT is the serialization + harvest layer on top

(lib/metadata/dcat.ts + lib/metadata/dcat-profiles.ts). This skill selects one or

more DCAT application profiles, maps every dataset's metadata to them, and writes

static feed files at build time — JSON-LD, Turtle, and RDF/XML — so external catalogs

(data.europa.eu, data.gov, national portals) can harvest the datasets automatically,

on any static host, with no runtime.

Prerequisites

• A scaffolded PortalJS portal with datasets.json, package.json, and

lib/metadata/ (the metadata-profile contract) present.

• lib/metadata/dcat.ts (the DCAT-3 core) already in place — profiles augment it.
• Node 18+ and npm available in the portal directory.
• For DCAT-AP / DCAT-US: a publishing organization (name + homepage) and a contact

(name + email) — both profiles require dct:publisher and dcat:contactPoint.

• Optional but recommended: network access to run SHACL conformance checks against the

official EU ITB validator or pyshacl.

Instructions

The canonical, full step-by-step workflow is

.claude/commands/portaljs-add-dcat.md —

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

1. Gather input from $ARGUMENTS (interview if thin): portal directory (default .),

profiles (default ["dcat-3"]), site URL, publisher, contact, license, themes,

languages, access level.

1. Validate the portal directory: confirm datasets.json, package.json, and

lib/metadata/ exist; stop with an ERROR: if the metadata contract is missing.

1. Ensure the DCAT profile layer is present — dcat-profiles.ts, dcat-rdf.ts,

dcat-validate.ts — copying canonical versions from examples/portaljs-catalog if

the portal predates this skill.

1. Ensure scripts/generate-dcat.ts is wired to predev/prebuild and emits

per-profile x serialization feeds from dcat.config.json.

1. Write dcat.config.json with the gathered profiles, publisher, contact, license,

themes, and access level.

1. Add feed autodiscovery: a
   portaljs-add-geo View full skill →

   Auto-ingest a geospatial file (GeoJSON, Shapefile, GeoPackage, KML/KMZ, FlatGeobuf, CSV-with-geometry) into a PortalJS portal on the user's own machine, with no server.

   ReadWriteEditBash(ogr2ogr:*)Bash(ogrinfo:*)Bash(tippecanoe:*)Bash(duckdb:*)Bash(git:*)Bash(curl:*)Bash(npx:*)Bash(node:*)Bash(mkdir:*)Bash(cp:*)Bash(wc:*)Bash(command:*)WebFetch

   PortalJS — Add Geo

   Overview

   Turn one geospatial upload into a dual-tier PortalJS dataset entirely on the user's

   machine — no server-side container compute, keeping the zero-backend bet end-to-end.

   From a single source the skill derives two serverless tiers plus the preserved original:

   • PMTiles (render tier) — a vector-tile archive renders with MapLibre GL

   over HTTP range requests; any dataset size pans and zooms with no tile server.

   • GeoParquet (query tier) — a GeoParquet 1.1 file (covering bbox column, Hilbert-sorted)

   runs spatial SQL over in place via DuckDB-Wasm.

   • Original — the untouched upload in its native CRS, kept downloadable.

   All three land on Cloudflare R2 (Git LFS → Giftless), and the skill appends one

   datasets.json entry whose resources[] match the shape the showcase auto-renders (the

   @reference/world-boundaries demo, PR #1647): pmtiles → , geoparquet →

   , original → download. No page edits are needed. It automates the manual

   tippecanoe/duckdb recipes in the template README.

   Prerequisites

   • A scaffolded portaljs-catalog portal whose template ships components/MapPreview.tsx and

   components/GeoQuery.tsx (PR #1647 or later).

   • Native CLIs on the user's machine: GDAL (ogr2ogr, ogrinfo), tippecanoe, and

   duckdb (with the spatial extension). macOS: brew install gdal tippecanoe duckdb;

   Debian/Ubuntu: apt-get install gdal-bin duckdb + tippecanoe (apt or build from source);

   Windows: use WSL. The skill hard-stops with the install hint if any is missing.

   • Arc credentials for the Git-LFS → R2 push (the same token portaljs-deploy resolves), or

   an OSS self-hosted Giftless.

   Instructions

   The canonical, full step-by-step workflow is

   .claude/commands/portaljs-add-geo.md

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

   1. Gather input — source (geo file path or URL), portal directory, namespace. Interview if

   missing; never dead-end.

   1. Detect the native tools (ogr2ogr, tippecanoe, duckdb + spatial). Any missing →

   print the per-OS install and stop.

   1. Validate the portal directory and co

portaljs-add-map View full skill →

Render a GeoJSON dataset on an interactive Leaflet map in the Views section of a dataset's showcase.

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

PortalJS — Add Map

Overview

Add an interactive Leaflet map as a view on a dataset's showcase in a

portaljs-catalog portal. The skill installs react-leaflet/leaflet (added directly —

never @portaljs/components), writes a reusable Map component split across

MapView.tsx (the Leaflet code) and Map.tsx (a dynamic(..., { ssr: false }) wrapper,

since Leaflet touches window at module load), and renders into the Views

section of the showcase route pages/[owner]/[slug].tsx for one chosen GeoJSON dataset.

The dataset should already carry format: "geojson" in datasets.json; if it doesn't

exist yet, the skill can copy the file and register it first.

Prerequisites

• A scaffolded PortalJS portal (see portaljs-new-portal).
• The target dataset registered in datasets.json with format: "geojson" (see

portaljs-add-dataset), or a GeoJSON source file/URL to register.

• Node 18+ and npm available in the portal directory.

Instructions

The canonical, full step-by-step workflow is

.claude/commands/portaljs-add-map.md — the

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

1. Gather input — dataset slug (or a GeoJSON source to register), portal directory. If any

is missing, interview the user; never dead-end on a missing value.

1. Validate the portal directory (datasets.json, package.json,

pages/[owner]/[slug].tsx must exist).

1. Resolve the dataset from datasets.json, or validate and register a new GeoJSON

source (copy to /public/data/, append a manifest entry).

1. Install map dependencies: npm install react-leaflet@^5 leaflet@^1.9 and

npm install -D @types/leaflet (skip if already present).

1. Write components/MapView.tsx and components/Map.tsx (idempotent — skip if

Map.tsx already exists).

1. Render into the Views section, gated on the dataset's (namespace, slug) so

other showcases are unaffected. Extend an existing view-dispatch block, do not

overwrite it.

1. Verify with npx tsc --noEmit (never next build against a live dev server).
2. Report the component, route, and dependency added.

Output

• Created: components/MapView.tsx

portaljs-add-resource View full skill →

Add another file (resource) to an EXISTING dataset in a PortalJS portal — a data dictionary, methodology, or an additional data file.

ReadWriteEditBash(npm:*)Bash(curl:*)Bash(mkdir:*)Bash(cp:*)WebFetch

PortalJS — Add Resource

Overview

Add a resource — an additional file — to a dataset that already exists in a

portaljs-catalog portal. Where /portaljs-add-dataset creates a new dataset

(one file), this skill adds a file to an existing one: a data dictionary, a

methodology document, or another data file (e.g. a second year's figures).

Mirrors the Frictionless Data Package model: a dataset holds a resources[] array,

and the showcase at /@/ renders one section per resource (preview,

schema, download). A single-file dataset migrates to resources[] automatically the

first time a second file is added — no data is lost.

Prerequisites

• An existing PortalJS portal (portaljs-catalog template) with datasets.json,

package.json, and pages/[owner]/[slug].tsx present.

• The target dataset already registered in datasets.json.
• The new resource's source: a local file path or a public URL, in CSV, TSV, JSON

(array), or GeoJSON format.

• Node 18+ installed to run npx next build for verification.

Instructions

The canonical, full step-by-step workflow lives in

.claude/commands/portaljs-add-resource.md

in this repository — that file is the single source of truth. Read and follow it. Summary:

1. Gather input (interview if thin): DATASET (slug or namespace/slug), SOURCE

(path or URL), PORTALDIR (default .), RESOURCENAME, RESOURCE_TITLE,

DESCRIPTION. If DATASET or SOURCE is missing, list datasets from

datasets.json and ask.

1. Validate the portal and locate the dataset entry by slug (and namespace, if

given). If the dataset does not exist, offer /portaljs-add-dataset instead.

1. Detect the format from extension/Content-Type, fetch (check HTTP status) or

confirm the local path exists, then copy into PORTAL_DIR/public/data/ under a

non-colliding filename.

1. Update datasets.json: if the dataset has no resources yet, migrate its

top-level file/format/schema into the first resource (lossless), then

append the new resource; if resources already exists, just append, keeping

name unique within the array.

1. Verify the build with npx next build, capturing output to a log file; f

portaljs-architect View full skill →

Recommend a data-portal architecture (storage, compute, catalog, access, hosting, metadata) from stated needs, then hand off to the build skills.

ReadWriteBash(du:*)Bash(wc:*)Bash(ls:*)Bash(head:*)

PortalJS — Architect

Overview

The advisory entry point for a PortalJS project. Before anything gets scaffolded, this

skill works out what to build: given the kind of portal, the shape of the data, and its

purpose, it fills six architecture slots (storage, catalog, compute, access, hosting,

metadata), resolves two build-time knobs (per-dataset data tier and the portal-wide

DATA_QUERY mode), and hands off to the concrete build skills. It decides; it does not

build. When the brief is thin it interviews in short rounds and never dead-ends — every

question has a sensible default, reachable by replying "use defaults."

Prerequisites

• A rough idea of the portal's purpose and data (exact numbers are not required — the

interview supplies defaults for anything missing).

• Optional: local files or a directory of sample data to inspect for size and shape.
• No PortalJS project needs to exist yet; this skill runs before scaffolding.

Instructions

The canonical, full step-by-step workflow lives in

.claude/commands/portaljs-architect.md —

that file is the single source of truth. Follow it when executing this skill:

1. Parse $ARGUMENTS for anything already specified, then interview for what's

missing, one round at a time: (1) what's being built, (2) what the data is,

(3) what it's for, (4) constraints. Accept "use defaults" at any point. Inspect

named files/directories with du -sh and line counts to ground size guesses.

1. Derive the recommendation by matching the answers against the decision tables —

Storage/Catalog/Compute by data volume and query needs, Access/Hosting by public

vs. private, Metadata by standards-compliance needs — then resolve the two

build-time knobs: per-dataset data tier (inline | LFS | external) and the

portal-wide DATA_QUERY mode (flat | duckdb).

1. Echo the architecture brief (stack, reasoning per slot, deviations from default,

deferred items) and wait for confirmation ("go") or corrections.

1. On confirmation, persist the brief to ./ARCHITECTURE.md in the working directory.
2. Hand off to the build skills — /portaljs-new-portal, /portaljs-add-dataset,

/portaljs-connect-ckan, /portaljs-define-schema, /portaljs-deploy — mapped

from the brief, and offer to run the first one.

Output

• Created: ./ARCHITECTURE.md documenting the six slots, the two build-time

knobs, the reasoning, and anything

portaljs-check-data-quality View full skill →

Audit a local or remote tabular file (CSV/TSV) for common data quality issues — schema, nulls, types, duplicates.

Bash(curl:*)Bash(awk:*)Bash(sort:*)Bash(head:*)Bash(wc:*)

PortalJS — Check Data Quality

Overview

Run a read-only quality audit of one CSV or TSV file, local or remote, and return a

structured JSON report. The audit profiles every column — null/blank counts, inferred

value types, numeric ranges, likely year/date fields — and flags duplicate rows,

duplicate values in identifier-like columns, ambiguous overlapping year columns (e.g.

calendar year vs fiscal year), and mixed-type columns. It never edits the source

file, datasets.json, or any other project file; it only reads the target file (a

remote URL is downloaded to a temp file that is deleted before the run ends) and

prints a report. Use it before publishing a dataset with portaljs-add-dataset, or to

diagnose why a showcase renders wrong.

Prerequisites

• python3 on PATH — the audit logic runs as an embedded Python script; nothing is

installed.

• One CSV or TSV file, given as a local path or an http/https URL. Only one file

per run.

Instructions

The canonical, full step-by-step workflow is

.claude/commands/portaljs-check-data-quality.md —

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

1. Gather input — the file path or URL to audit. If missing, ask for it; never dead-end.
2. Resolve the source: if it's an http/https URL, download it to a temp file first;

otherwise use the local path as given.

1. Validate the extension is .csv or .tsv. If not, or the file is missing, or the

header row is empty, stop and surface the error JSON as-is — do not guess a fix.

1. Profile every column: null/blank counts, distinct values, sample values, inferred

per-value type (boolean/integer/float/date/string), numeric min/max, and year

range for columns whose name looks year-like.

1. Derive findings from the profiles — duplicate rows, missing-value ratios, invalid

year values, mixed types, suspect negative values, duplicate identifier values, and

ambiguous overlapping year columns — each tagged critical, warning, or info.

1. Assemble the JSON report (status, file metadata, findings, recommendations,

column_profiles), print it, and clean up the temp file if one was created.

1. Relay the report to the user as-is; do not modify the source file, datasets.json,

or any other project file based on the findings — that's a separate, explicit step.

Output<

portaljs-connect-ckan View full skill →

Wire a scaffolded PortalJS portal to a CKAN backend over its API.

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

PortalJS — Connect CKAN

Overview

Connect an existing portaljs-catalog portal to a live CKAN backend for the "decoupled /

any backend" path. The portal stops reading the static datasets.json manifest (and files

in /public/data/) and instead feeds its two data surfaces — the /search catalog and

the /@namespace/slug showcases — straight from a CKAN instance's REST API

(packagesearch / packageshow) through a generated fetch client. Output is plain,

editable Next.js code with no runtime dependency — never @portaljs/ckan, whose bundle

wires React UI components to React 18 internals and crashes at import under the template's

React 19. Pages fetch CKAN server-side in getStaticProps/getStaticPaths, so the catalog

is pre-rendered at build time and the site can still be statically deployed. Run this right

after portaljs-new-portal to swap a freshly scaffolded portal's sample data over to CKAN.

Prerequisites

• A scaffolded PortalJS portal (see portaljs-new-portal) with package.json, pages/,

datasets.json, pages/search.tsx, and pages/[owner]/[slug].tsx present.

• A CKAN base URL that is publicly reachable, e.g. https://demo.dev.datopian.com.
• Node 18+ and npm available in the portal directory (no new packages are installed).

Instructions

The canonical, full step-by-step workflow is

.claude/commands/portaljs-connect-ckan.md —

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

1. Gather input from $ARGUMENTS — CKAN base URL (required), org filter (optional), group

filter (optional), portal directory (default .). If the URL is missing, interview the

user; never dead-end with a missing-input error.

1. Validate the target directory is a portaljs-catalog portal; if not, suggest

portaljs-new-portal instead of failing silently.

1. Verify the CKAN backend is reachable via package_search?rows=1, and validate each org

filter via organization_show; on failure, explain and re-prompt rather than dead-ending.

1. Generate lib/ckan.ts — a self-contained server-side fetch client wrapping

packagesearch and packageshow, with DMS, ORGFILTER, GROUPFILTER, and

MAX_DATASETS as editable constants.

portaljs-define-schema View full skill →

Define a dataset's metadata profile — infer a Frictionless Table Schema from its data, add Data Package metadata (license, sources, keywords), and write it into datasets.

ReadWriteEditBash(npx:*)Bash(node:*)Bash(head:*)

PortalJS — Define Schema

Overview

Define a dataset's metadata profile — the authoring skill for the metadata-profile

contract (lib/metadata). Where portaljs-add-dataset registers that a dataset exists,

this skill describes what its data means: infer a Frictionless Table Schema (fields,

types, constraints) from sampled data, add the Data Package fields a catalog surfaces

(title, licenses, sources, keywords), and write them onto the dataset's entry in

datasets.json. The showcase at /@/ then renders a typed field table

instead of a bare preview. The model is Frictionless-native; DCAT is a serialization layer

built on top later, not authored here.

The skill runs on a profile ladder — reach for higher levels only when needed: