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.json with format: "geojson" (see

portaljs-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:

1. 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.

1. Validate the portal directory (datasets.json, package.json,

pages/[owner]/[slug].tsx must exist).

1. Resolve the dataset from datasets.json, or validate and register a new GeoJSON

source (copy to /public/data/, append a manifest entry).

1. Install map dependencies: npm install react-leaflet@^5 leaflet@^1.9 and

npm install -D @types/leaflet (skip if already present).

1. Write components/MapView.tsx and components/Map.tsx (idempotent — skip if

Map.tsx already exists).

1. 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.

1. Verify with npx tsc --noEmit (never next build against a live dev server).
2. Report the component, route, and dependency added.

Output

• Created: components/MapView.tsx and components/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 --noEmit passes.
• 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/>