| name | portaljs-add-dataset |
| description | Add a dataset (CSV, TSV, JSON, or GeoJSON) to an existing PortalJS portal. Appends an entry to datasets.json so the catalog and showcase render it automatically; routes the data by source (local file vs remote URL) — R2 via Git LFS by default, remote URLs by passthrough. Use when registering a new dataset in a scaffolded portal. |
| allowed-tools | Read, Write, Edit, Bash(npm:*), Bash(npx:*), Bash(git:*), Bash(curl:*), Bash(mkdir:*), Bash(cp:*), WebFetch |
| 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","dataset","csv","geojson","catalog"] |
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 /@<namespace>/<slug>. 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:
- 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.
- Validate the portal directory: confirm
datasets.json, package.json, and
pages/[owner]/[slug].tsx exist.
- 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.
- 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).
- Append one entry to
datasets.json — slug, namespace, name, description,
(the routed path/URL), — keeping unique.
