datopian/portaljs

PortalJS – an AI‑native framework for data portals

What it is – PortalJS is an open‑source, MIT‑licensed toolkit that lets data teams create full‑featured open‑data portals with just a few commands. It ships a set of Claude Code “skills” (slash‑commands) that act as an AI assistant: they interview you, recommend an architecture, scaffold a Next.js codebase, and add datasets, charts, maps, or metadata automatically. The generated portal is plain, editable Next.js – no vendor lock‑in.

Why it matters – Building a data portal normally requires deciding on storage, catalog, search, hosting, and then wiring a UI. PortalJS bundles that decision‑making (the advisor skill) with code generation, letting non‑engineers describe what they need in natural language and get a working portal instantly. It also supports modern “lakehouse” stacks (Git + Cloudflare R2 + Parquet + DuckDB) while still allowing classic back‑ends like CKAN.

Key pieces

• Agentic Skills – a collection of Claude Code slash commands (/portaljs-architect, /portaljs-new-portal, /portaljs-add-dataset, etc.) that recommend architecture, scaffold code, ingest data, generate charts/maps, emit DCAT feeds, and deploy.
• Three‑surface UI – a Home page, a Catalog (/search) for dataset discovery, and a Showcase (/@<namespace>/<slug>) that displays metadata, previews, downloads, and visualisations.
• DataProvider contract – all UI components read data through a single provider interface, making the backend pluggable (static files, Git‑LFS + R2, CKAN, OpenMetadata, etc.).
• Storage & compute options – from simple flat files to a full lakehouse (Parquet on R2 queried with DuckDB) or a traditional warehouse/CKAN.
• Cloudflare‑first substrate – default deployment uses Cloudflare R2, Workers, D1, and Pages, but storage remains S3‑compatible.

Getting started

# one‑liner creates a portal with sample data
npm create portaljs@latest my-portal
cd my-portal
npm run dev   # http://localhost:3000

To use the AI assistant, install the Claude skills once:

curl -fsSL https://raw.githubusercontent.com/datopian/portaljs/main/scripts/install-portaljs-skills.sh | bash

Then in any Claude Code session you can run commands like:

/portaljs-architect  we have 200 CSVs, need DCAT‑AP compliance
/portaljs-new-portal  "City Open Data Portal"
/portaljs-add-dataset  ./data/air-quality.csv

The skills will generate the Next.js project, update datasets.json, push large files to R2 via Git‑LFS, and create the appropriate UI pages.

Ecosystem & extensibility

• Packages – @portaljs/ckan (CKAN UI components) and @portaljs/ckan-api-client-js for API access.
• Examples – the canonical template lives in examples/portaljs-catalog; a production‑grade portal (OpenSpending) is built on top of PortalJS.
• Community – Discord, GitHub Discussions, and an issue tracker for support and contributions.
• Roadmap – adds more metadata schemas, additional back‑ends, a DuckDB query layer in the browser, and fine‑grained access control.

Who should use it – data teams, municipal open‑data programs, NGOs, or anyone who needs to publish datasets quickly without committing to a heavyweight data warehouse, and who wants AI‑assisted guidance on architecture.

License – MIT (full source available on GitHub).