Skip to content

Latest commit

 

History

History
117 lines (82 loc) · 4.8 KB

REACT_SPA.md

File metadata and controls

117 lines (82 loc) · 4.8 KB

React SPA integration

Copy-out template: starters/mapsight-vite-spa-starter — minimal Vite + React Router SPA with one map route and semver @mapsight/* pins.

Feature demo: apps/demos — richer UI surface (icon catalog, count-aggregator, TanStack Query) for contributors exploring package capabilities.

Use this when Mapsight is the primary frontend (demo apps, internal tools, standalone dashboards) rather than a CMS HTML snippet.


When to use an SPA vs CMS embed

CMS embed React SPA
Editorial paste-in placements Developer-owned routes and layout
Shared lib build + inline config Single app bundle or code-split routes
Host CMS owns chrome App owns chrome (nav, footer)
Primary municipal communicative maps Demo apps, count-aggregator lab

Many production communicative maps use CMS embeds; SPAs prove package integration and support contributor development.


Stack

Piece Choice in vite-spa starter Demos extras
Bundler Vite Same
Routing React Router 7 Same
Map runtime @mapsight/core + OpenLayers Same
UI @mapsight/ui Instance + App Additional demo pages
Async data Static GeoJSON URL in config TanStack Query (count-aggregator demo)
Styling Mapsight SCSS (no Tailwind) Tailwind v4 + Mapsight SCSS/CSS

Integration pattern

  1. Create store via @mapsight/ui Instance (or lower-level create()) on a route-mounted container ref.
  2. Load config from route params, static JSON, or fetched at runtime — unlike CMS embeds, config often lives in TS modules.
  3. Style pipeline — run vector-style-compiler and copy traffic-style icons as part of npm run build (see starter package.json scripts).
  4. Assets — copy @mapsight/traffic-style image dirs to public/img/ for map icons (mapsight-icons*). UI chrome icons (mapsight-ui/*) resolve from @mapsight/ui through SCSS ($ms3-iconPath: "~@mapsight/ui/dist/img/") and are emitted as bundler assets — see apps/demos/src/msui.scss. Set $ms3-future-v8-themedIcons: true to colour them from the --ms3-* tokens (themed chrome icons).

The vite-spa starter mounts the map only on /. Navigating to /about unmounts Instance and tears down its store. If you keep Instance at a layout level across routes, call resetMapsightCore when leaving map modules — see the starter README.


Heading hierarchy

For host-owned heading sections, enable future.v8_automaticHeadings on the instance and use HeadingLevel inside it to establish the first rank beneath each host heading. See Heading hierarchy.

Count Aggregator demo

The demo app includes a count-aggregator page wired to a local mock API (vite.count-aggregator-mock.ts) so contributors can exercise @mapsight/count-aggregator-ui without a live platform. Replace mock base URL with host platform public API in production apps.

See DATA_BACKEND.md for the optional platform pattern.


TanStack Router (pattern only)

Private host apps may use TanStack Router instead of React Router. Integration rules:

  • Mount embed or full Mapsight route component on leaf routes
  • Call resetMapsightCore when leaving map routes to avoid stale global store state
  • Use path-scoped containers — one store per mount unless intentionally sharing via mergeAll

No TanStack Router reference app ships in the public monorepo; follow the vite-spa starter embed lifecycle with router lifecycle hooks.


Development commands

Copy-out (outside monorepo):

cd mapsight-vite-spa-starter
npm install
npm run dev
npm run build

Inside Mapsight monorepo:

pnpm --filter mapsight-vite-spa-starter dev
pnpm --filter mapsight-vite-spa-starter build
pnpm --filter @mapsight/demos dev
pnpm --filter @mapsight/demos build

Run typecheck/lint via turbo from root: pnpm typecheck, pnpm lint.


Related