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:
- 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].tsx must 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.9 and
npm install -D @types/leaflet (skip if already present).
- Write
components/MapView.tsx and components/Map.tsx (idempotent — skip if
Map.tsx already 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 (never next build against a live dev server).
- 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
Source: jeremylongshore/claude-code-plugins-plus-skills → plugins/community/portaljs/skills/portaljs-add-map/SKILL.md
1---2name: portaljs-add-map3description: "Render a GeoJSON dataset on an interactive Leaflet map in the Views section of a dataset's showcase. Installs react-leaflet and a Map component, then renders the map for the chosen dataset. Use when a dataset's data is geographic and a map view is needed alongside the showcase's default metadata and download."4allowed-tools: "Read, Write, Edit, Bash(npm:*), Bash(npx:*), WebFetch"5category: frontend-and-design6source_repo: jeremylongshore/claude-code-plugins-plus-skills7source_path: "plugins/community/portaljs/skills/portaljs-add-map/SKILL.md"8source_url: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/plugins/community/portaljs/skills/portaljs-add-map/SKILL.md9---101112# PortalJS — Add Map1314## Overview1516Add an interactive Leaflet map as a view on a dataset's **showcase** in a17`portaljs-catalog` portal. The skill installs `react-leaflet`/`leaflet` (added directly —18never `@portaljs/components`), writes a reusable `Map` component split across19`MapView.tsx` (the Leaflet code) and `Map.tsx` (a `dynamic(..., { ssr: false })` wrapper,20since Leaflet touches `window` at module load), and renders `<Map />` into the **Views**21section of the showcase route `pages/[owner]/[slug].tsx` for one chosen GeoJSON dataset.22The dataset should already carry `format: "geojson"` in `datasets.json`; if it doesn't23exist yet, the skill can copy the file and register it first.2425## Prerequisites2627- A scaffolded PortalJS portal (see `portaljs-new-portal`).28- The target dataset registered in `datasets.json` with `format: "geojson"` (see29 `portaljs-add-dataset`), or a GeoJSON source file/URL to register.30- Node 18+ and npm available in the portal directory.3132## Instructions3334The canonical, full step-by-step workflow is35[`.claude/commands/portaljs-add-map.md`](https://github.com/datopian/portaljs/blob/main/.claude/commands/portaljs-add-map.md) — the36single source of truth. Read and follow it when executing. Summary:37381. Gather input — dataset slug (or a GeoJSON source to register), portal directory. If any39 is missing, interview the user; never dead-end on a missing value.402. Validate the portal directory (`datasets.json`, `package.json`,41 `pages/[owner]/[slug].tsx` must exist).423. Resolve the dataset from `datasets.json`, or validate and register a new GeoJSON43 source (copy to `/public/data/`, append a manifest entry).444. Install map dependencies: `npm install react-leaflet@^5 leaflet@^1.9` and45 `npm install -D @types/leaflet` (skip if already present).465. Write `components/MapView.tsx` and `components/Map.tsx` (idempotent — skip if47 `Map.tsx` already exists).486. Render `<Map />` into the Views section, gated on the dataset's `(namespace, slug)` so49 other showcases are unaffected. Extend an existing view-dispatch block, do not50 overwrite it.517. Verify with `npx tsc --noEmit` (never `next build` against a live dev server).528. Report the component, route, and dependency added.5354## Output5556- **Created:** `components/MapView.tsx` and `components/Map.tsx` (Leaflet wrapper, if57 absent); `public/data/<slug>.geojson` (only when registering a new dataset).58- **Modified:** `pages/[owner]/[slug].tsx` (import + gated `<Map />` in Views);59 `datasets.json` (only when registering a new dataset); `package.json`60 (`react-leaflet`, `leaflet`, `@types/leaflet`).61- **Verified:** `npx tsc --noEmit` passes.62- **Result:** the map renders at `/@<namespace>/<slug>` under a "Views" heading.6364## Error Handling6566| Symptom | Cause | Fix |67| --- | --- | --- |68| 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. |69| Source fetch/copy fails | URL returns non-200 or local path missing | Report the HTTP status or missing path; ask for a corrected source. |70| "Not valid GeoJSON" | Parsed JSON `type` isn't a Feature/geometry type | Tell the user and point to `portaljs-add-dataset` for tabular data. |71| `tsc` failure | Bad import path or gating condition | Fix the first reported error before reporting success. |72| Map appears on every dataset | View not gated on `(namespace, slug)` | Wrap the `<Map />` render in the dataset check shown in the Instructions. |73| Features render in the wrong place | Data isn't WGS84 (EPSG:4326) lon/lat | Reproject the source data to WGS84 before adding. |74| Slow render | Thousands of features in one file (>5MB) | Simplify geometries (e.g. `mapshaper`) before adding. |7576## Examples7778### Example 1 — Map an already-registered dataset7980```81/portaljs-add-map dataset=park-boundaries82```8384### Example 2 — Register a local GeoJSON file and map it8586```87/portaljs-add-map source=./data/bike-routes.geojson slug=bike-routes name="Bike Routes"88```8990### Example 3 — Register a remote GeoJSON URL and map it9192```93/portaljs-add-map source=https://example.com/districts.geojson slug=districts namespace=reference94```9596## Resources9798- Full workflow: [`.claude/commands/portaljs-add-map.md`](https://github.com/datopian/portaljs/blob/main/.claude/commands/portaljs-add-map.md)99- Map props and troubleshooting reference: [`references/reference.md`](references/reference.md)100- Related skills: `portaljs-add-dataset`, `portaljs-add-chart`, `portaljs-define-schema`101- react-leaflet documentation: <https://react-leaflet.js.org/>102103---104105**Source:** [`jeremylongshore/claude-code-plugins-plus-skills`](https://github.com/jeremylongshore/claude-code-plugins-plus-skills) → `plugins/community/portaljs/skills/portaljs-add-map/SKILL.md`
jeremylongshore