PortalJS
The AI-native framework for building data portals.
Describe the portal you want — your agent helps you choose an architecture, scaffolds it, and loads your data.
Docs
·
Discussions
·
Report a bug
Quickstart
Create a portal — one command, nothing to install beyond Node 18+:
npm create portaljs@latest my-portal
cd my-portal
npm run dev # → http://localhost:3000
You get the three surfaces — Home, a Catalog (/search), and a dataset Showcase
(/@<namespace>/<slug>) — over sample data. Plain, editable Next.js, no lock-in. Add your
own CSV/JSON to datasets.json and it renders automatically.
Build it with your AI assistant — PortalJS ships Claude Code
skills that do the assembly. Install them once (into ~/.claude/commands):
curl -fsSL https://raw.githubusercontent.com/datopian/portaljs/main/scripts/install-portaljs-skills.sh | bash
Then, in a Claude Code session from any directory:
/portaljs-architect not sure what stack you need? start here
/portaljs-new-portal "Auckland Council open data portal"
/portaljs-add-dataset ./data/air-quality.csv
/portaljs-new-portal scaffolds the three surfaces; /portaljs-add-dataset (or /portaljs-add-resource) loads data;
/portaljs-connect-ckan points it at a CKAN backend; /portaljs-deploy ships it. (All skills + install →)
Prefer the bare template — plain Next.js, no AI, no lock-in:
npx tiged datopian/portaljs/examples/portaljs-catalog my-portal
cd my-portal && npm install && npm run dev # → http://localhost:3000
You get Home, a Catalog (/search), and a dataset Showcase (/@<namespace>/<slug>) over
sample data. Add your own CSV/JSON to datasets.json and it renders automatically.
⭐ If it's useful, a star helps others find it.
Why PortalJS
Building a data portal has always meant more than a website. You have to decide where
the data lives, how it's versioned, how people search it, how it's served, and how it's
governed — and then wire a frontend on top. Teams either over-build on a heavy data
warehouse they don't need, or under-build on a pile of scripts that doesn't scale.
PortalJS is an open-source, agentic skills framework that helps data teams build,
develop, and ship data portals — and the data infrastructure underneath them. It isn't
only a frontend. The skills do two jobs:
- Advise — given what you're building, what your data is, and what it's for,
they recommend an architecture: storage, compute, catalog, access, hosting, metadata.
- Build — they scaffold that stack as plain, editable Next.js code with no lock-in.
It is opinionated but open: the recommended modern path is git + object storage
(Cloudflare R2) + Parquet + DuckLake + DuckDB — an open
lakehouse instead of a classic warehouse — but a traditional datastore (CKAN, a
warehouse) stays a first-class option when you need it. You always own plain code.
Built and maintained in the open by Datopian and the
PortalJS community.
Architecture at a glance
🧑 you describe what you want to build
│
▼
╭─ 🤖 AGENTIC SKILLS ────────────────────────────────── decide + build
│ /portaljs-architect · /portaljs-new-portal · /portaljs-add-dataset · /portaljs-add-chart · /portaljs-add-map …
╰─ generates plain, editable Next.js code — no lock-in
│
▼
╭─ 🖥️ SURFACES ──────────────────────────────────────── what users see
│ 🏠 Home / 🔎 Catalog /search 📊 Showcase /@ns/slug
╰─ read data through one DataProvider contract
│
▼
╭─ 🔌 PROVIDERS ─────────────────────────────────────── pluggable backends
│ 📁 static·git 🐘 CKAN 🔭 OpenMetadata 🗂️ git-LFS + R2
╰─ swap the source without touching a page
│
▼
📦 STORAGE + COMPUTE — choose your point on the spectrum:
flat files ─▶ Git-LFS + R2 ─▶ Parquet + DuckLake + 🦆 DuckDB ─▶ warehouse / CKAN
simplest ⭐ open lakehouse (default) heaviest
☁️ Substrate — Cloudflare R2 (storage) · Workers (runtime) · D1 (catalog) · Pages (static)
object storage stays S3-compatible — R2 is the default, never a lock-in
