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
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
│ /architect · /new-portal · /add-dataset · /add-chart · /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
Three surfaces. Every data portal is built from three: a Home page that explains
it and offers search, a Catalog (/search) to discover datasets, and a Showcase
(/@<namespace>/<slug>) to explore one dataset — metadata, preview, download/API, and
charts/maps. (Core concepts →)
One seam. The surfaces read data only through a DataProvider, so the source — static
files today, a CKAN or lakehouse backend tomorrow — can change without touching a page.
See ROADMAP.md for the full model and the
architecture decision framework
for how /architect turns your needs into a stack.
Build a portal with your AI assistant
PortalJS ships Claude Code skills that turn a brief into
a working portal.
Setup
The skills live in this repo under .claude/commands/. The quickest
way to try them is from a clone:
git clone https://github.com/datopian/portaljs
cd portaljs
claude
Claude Code auto-discovers the slash commands from .claude/commands/ — no install step.
Type / in the session to see them.
Install anywhere: the skills and template are also packaged as a Claude Code plugin
and can be installed into ~/.claude/commands/ so you can run them from any project. See
.claude/INSTALL.md.
Use
If you're not sure how to set up your portal, start with the advisor, then build:
