| name | portaljs-add-geo |
| description | Auto-ingest a geospatial file (GeoJSON, Shapefile, GeoPackage, KML/KMZ, FlatGeobuf, CSV-with-geometry) into a PortalJS portal on the user's own machine, with no server. Normalizes CRS to EPSG:4326, derives a PMTiles render tier and a GeoParquet query tier, pushes all three artifacts to Cloudflare R2 via Git LFS, and appends one dual-tier datasets.json entry the showcase auto-renders. Use when the source is a vector geo format that needs a map or spatial-query view. |
| allowed-tools | Read, Write, Edit, Bash(ogr2ogr:*), Bash(ogrinfo:*), Bash(tippecanoe:*), Bash(duckdb:*), Bash(git:*), Bash(curl:*), Bash(npx:*), Bash(node:*), Bash(mkdir:*), Bash(cp:*), Bash(wc:*), Bash(command:*), WebFetch |
| version | 1.0.0 |
| author | Datopian <hello@datopian.com> |
| license | MIT |
| compatibility | Claude Code with PortalJS portals (Next.js 14, React 18/19, Node 18+). Requires native GDAL, tippecanoe, and duckdb on the user's machine (macOS or Linux/WSL). Runs from any project via the plugin, a personal ~/.claude/commands install, or a portaljs clone. |
| tags | ["portaljs","data-portal","geospatial","pmtiles","geoparquet","duckdb"] |
PortalJS — Add Geo
Overview
Turn one geospatial upload into a dual-tier PortalJS dataset entirely on the user's
machine — no server-side container compute, keeping the zero-backend bet end-to-end.
From a single source the skill derives two serverless tiers plus the preserved original:
- PMTiles (render tier) — a vector-tile archive
<MapPreview> renders with MapLibre GL
over HTTP range requests; any dataset size pans and zooms with no tile server.
- GeoParquet (query tier) — a GeoParquet 1.1 file (covering
bbox column, Hilbert-sorted)
<GeoQuery> runs spatial SQL over in place via DuckDB-Wasm.
- Original — the untouched upload in its native CRS, kept downloadable.
All three land on Cloudflare R2 (Git LFS → Giftless), and the skill appends one
datasets.json entry whose resources[] match the shape the showcase auto-renders (the
@reference/world-boundaries demo, PR #1647): pmtiles → <MapPreview>, geoparquet →
<GeoQuery>, original → download. No page edits are needed. It automates the manual
tippecanoe/duckdb recipes in the template README.
Prerequisites
- A scaffolded
portaljs-catalog portal whose template ships components/MapPreview.tsx and
components/GeoQuery.tsx (PR #1647 or later).
- Native CLIs on the user's machine: GDAL (
ogr2ogr, ogrinfo), tippecanoe, and
duckdb (with the spatial extension). macOS: brew install gdal tippecanoe duckdb;
Debian/Ubuntu: apt-get install gdal-bin duckdb + tippecanoe (apt or build from source);
Windows: use WSL. The skill hard-stops with the install hint if any is missing.
- Arc credentials for the Git-LFS → R2 push (the same token
portaljs-deploy resolves), or
an OSS self-hosted Giftless.
Instructions
The canonical, full step-by-step workflow is
.claude/commands/portaljs-add-geo.md
— the single source of truth. Read and follow it when executing. Summary:
