PortalJS: AI-native open-source framework for building data portals

PortalJS is an open-source framework built and maintained by Datopian and its community for teams that need to build, develop, and ship data portals alongside the infrastructure beneath them. The core insight is that a data portal is more than a website: teams must decide where data lives, how it's versioned, how people search it, how it's served, how it's governed, and then wire a frontend on top.

The framework ships two capabilities. First, it advises: given what you're building, your data, and what it's for, the /portaljs-architect skill recommends an architecture (storage, compute, catalog, access, hosting, metadata). Second, it builds: the skills scaffold that stack as plain, editable Next.js code with no lock-in. The recommended modern path is git + Cloudflare R2 object storage + Parquet, queried with DuckDB—an open lakehouse instead of a classic warehouse. For living, incremental tables you can layer on DuckLake, and a traditional datastore (CKAN or warehouse) remains a first-class option when you need it.

PortalJS provides three user-facing surfaces that every data portal needs: a Home page that explains the portal and offers search; a Catalog (/search) to discover datasets; and a Showcase (/@<namespace>/<slug>) to explore one dataset, showing metadata, preview, download/API, and charts/maps. All three surfaces read data through a single DataProvider contract, so the source—static files, CKAN, Socrata, ArcGIS, OpenMetadata, or any custom backend—can change without touching a page.

To use the framework, you install Claude Code skills once into your personal scope (curl -fsSL https://raw.githubusercontent.com/datopian/portaljs/main/scripts/install-portaljs-skills.sh | bash), then type / in any Claude Code session to see them. If you're unsure how to set up your portal, you start with /portaljs-architect (turn your needs into a recommended architecture), then /portaljs-new-portal (scaffold a portal from a brief), and /portaljs-add-dataset to load your CSV, JSON, or GeoJSON. The skills are interactive: if your brief is thin, they interview you in short rounds rather than erroring. Alternatively, you can scaffold a working portal with one command (npm create portaljs@latest my-portal) and npm run dev launches it at http://localhost:3000.

The framework ships 15+ skills: /portaljs-architect for advisory, /portaljs-new-portal to scaffold Home + Catalog + Showcase, /portaljs-add-dataset to register and render a dataset, /portaljs-add-resource to attach metadata or extra files, /portaljs-add-chart and /portaljs-add-map to add visualizations, /portaljs-add-geo to auto-ingest geospatial files (GeoJSON, Shapefile, GeoPackage, KML/KMZ, FlatGeobuf, CSV-with-geometry) and derive query tiers, /portaljs-define-schema to infer a Frictionless Table Schema and add metadata, /portaljs-add-dcat to emit standards-compliant DCAT feeds in JSON-LD, Turtle, and RDF/XML for harvesting by national and EU open-data portals, /portaljs-connect-ckan to wire the portal to a CKAN backend, /portaljs-check-data-quality to validate datasets against their schema, /portaljs-migrate to harvest whole catalogs from CKAN, Socrata, OpenDataSoft, ArcGIS, or DCAT-US, and /arcgis-to-portaljs to migrate an entire ArcGIS Hub site. A /portaljs-deploy skill builds a static export and publishes to PortalJS Arc (Datopian-managed hosting on Cloudflare) with a live <slug>.arc.portaljs.com URL.

The code lives in a public GitHub repository under MIT license. The repo includes .claude/commands/ (the agentic skills), examples/ (reference portals, with portaljs-catalog as the canonical template), packages/ (core UI components, CKAN client, and supporting libraries), and site/ (portaljs.com documentation). What distinguishes PortalJS is its combination of three design choices: it is open-source MIT with no lock-in; it provides advisory not just generative scaffolding; it defaults to an open lakehouse (git + R2 + Parquet + DuckDB) over a heavy warehouse; and it uses Cloudflare (R2, Workers, D1, Pages) as the default substrate while keeping object storage S3-compatible. The framework is designed to be adopted as a template or for skills and the three-surface model to be lifted into an existing app, and it welcomes contributions of new skills, examples, docs, and fixes through its Discord, GitHub Discussions, and issue tracker.

PortalJS addresses a long-standing pain point in data infrastructure: most teams building data portals face a false choice between expensive, over-engineered data warehouses and fragile, unmaintainable script collections. The framework sidesteps this by recommending and automating a modern "open lakehouse" architecture (git for version control, Cloudflare R2 for object storage, Parquet files for columnar data, and DuckDB for serverless querying) that is simpler and cheaper than traditional warehouses while remaining scalable and maintainable.

The key innovation is pairing an agentic advisor (/portaljs-architect) with automated scaffolding skills. Rather than generating UI code alone, the framework first helps teams think through their infrastructure needs—data volume, update frequency, governance requirements, and standards compliance—and recommends an appropriate stack before writing any code. This advisory layer addresses a critical gap: many teams build portals without clear thinking about data architecture, leading to misaligned choices downstream.

By emitting plain Next.js code with no lock-in, PortalJS avoids the trap of proprietary portal platforms that become hard to customize or exit. The open-source MIT license and the decoupled DataProvider contract (allowing swaps from static files to CKAN to custom backends without touching UI code) reinforce this philosophy. The 15+ Claude Code skills—handling everything from architecture to dataset ingestion, geospatial data, schema inference, DCAT publishing for standards compliance, and migrations from ArcGIS or Socrata—indicate that the project is designed to be extended rather than rigid.

No comments yet. Be the first to share your thoughts!