datopian PortalJS — Add Map
Overview
Add an interactive Leaflet map as a view on a dataset's showcase in a
portaljs-catalog portal. The skill installs react-leaflet/leaflet (added directly —
never @portaljs/components), writes a reusable Map component split across
MapView.tsx (the Leaflet code) and Map.tsx (a dynamic(..., { ssr: false }) wrapper,
since Leaflet touches window at module load), and renders <Map /> into the Views
section of the showcase route pages/[owner]/[slug].tsx for one chosen GeoJSON dataset.
The dataset should already carry format: "geojson" in datasets.json; if it doesn't
exist yet, the skill can copy the file and register it first.
Prerequisites
- A scaffolded PortalJS portal (see
portaljs-new-portal). - The target dataset registered in
datasets.jsonwithformat: "geojson"(seeportaljs-add-dataset), or a GeoJSON source file/URL to register. - Node 18+ and npm available in the portal directory.
Instructions
The canonical, full step-by-step workflow is
.claude/commands/portaljs-add-map.md — the
single source of truth. Read and follow it when executing. Summary:
- Gather input — dataset slug (or a GeoJSON source to register), portal directory. If any is missing, interview the user; never dead-end on a missing value.
- Validate the portal directory (
datasets.json,package.json,pages/[owner]/[slug].tsxmust exist). - Resolve the dataset from
datasets.json, or validate and register a new GeoJSON source (copy to/public/data/, append a manifest entry). - Install map dependencies:
npm install react-leaflet@^5 leaflet@^1.9andnpm install -D @types/leaflet(skip if already present). - Write
components/MapView.tsxandcomponents/Map.tsx(idempotent — skip ifMap.tsxalready exists). - Render
<Map />into the Views section, gated on the dataset's(namespace, slug)so other showcases are unaffected. Extend an existing view-dispatch block, do not overwrite it. - Verify with
npx tsc --noEmit(nevernext buildagainst a live dev server). - Report the component, route, and dependency added.
Output
- Created:
components/MapView.tsxandcomponents/Map.tsx(Leaflet wrapper, if absent);public/data/<slug>.geojson(only when registering a new dataset). - Modified:
pages/[owner]/[slug].tsx(import + gated<Map />in Views);datasets.json(only when registering a new dataset);package.json(react-leaflet,leaflet,@types/leaflet). - Verified:
npx tsc --noEmitpasses. - Result: the map renders at
/@<namespace>/<slug>under a "Views" heading.
Error Handling
| Symptom | Cause | Fix |
|---|---|---|
| Dataset not found or not GeoJSON | Slug missing from datasets.json or format is tabular |
List GeoJSON datasets and re-prompt; suggest portaljs-add-chart for tabular data. |
| Source fetch/copy fails | URL returns non-200 or local path missing | Report the HTTP status or missing path; ask for a corrected source. |
| "Not valid GeoJSON" | Parsed JSON type isn't a Feature/geometry type |
Tell the user and point to portaljs-add-dataset for tabular data. |
tsc failure |
Bad import path or gating condition | Fix the first reported error before reporting success. |
| Map appears on every dataset | View not gated on (namespace, slug) |
Wrap the <Map /> render in the dataset check shown in the Instructions. |
| Features render in the wrong place | Data isn't WGS84 (EPSG:4326) lon/lat | Reproject the source data to WGS84 before adding. |
| Slow render | Thousands of features in one file (>5MB) | Simplify geometries (e.g. mapshaper) before adding. |
Examples
Example 1 — Map an already-registered dataset
/portaljs-add-map dataset=park-boundaries
Example 2 — Register a local GeoJSON file and map it
/portaljs-add-map source=./data/bike-routes.geojson slug=bike-routes name="Bike Routes"
Example 3 — Register a remote GeoJSON URL and map it
/portaljs-add-map source=https://example.com/districts.geojson slug=districts namespace=reference
Resources
- Full workflow:
.claude/commands/portaljs-add-map.md - Map props and troubleshooting reference:
references/reference.md - Related skills:
portaljs-add-dataset,portaljs-add-chart,portaljs-define-schema - react-leaflet documentation: https://react-leaflet.js.org/