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.
| 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.
| 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 |
- Create store via
@mapsight/uiInstance(or lower-levelcreate()) on a route-mounted container ref. - Load config from route params, static JSON, or fetched at runtime — unlike CMS embeds, config often lives in TS modules.
- Style pipeline — run
vector-style-compilerand copy traffic-style icons as part ofnpm run build(see starterpackage.jsonscripts). - Assets — copy
@mapsight/traffic-styleimage dirs topublic/img/for map icons (mapsight-icons*). UI chrome icons (mapsight-ui/*) resolve from@mapsight/uithrough SCSS ($ms3-iconPath: "~@mapsight/ui/dist/img/") and are emitted as bundler assets — seeapps/demos/src/msui.scss. Set$ms3-future-v8-themedIcons: trueto 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.
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.
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.
Private host apps may use TanStack Router instead of React Router. Integration rules:
- Mount embed or full Mapsight route component on leaf routes
- Call
resetMapsightCorewhen 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.
Copy-out (outside monorepo):
cd mapsight-vite-spa-starter
npm install
npm run dev
npm run buildInside 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 buildRun typecheck/lint via turbo from root: pnpm typecheck, pnpm lint.