Start with a working map, then copy the source into your project. These are runnable versions of the API examples, templates, and UI blocks in Unmap's docs.
Complete catalog · Get a browser key · SDK source · Full Maps app · Agent prompt
Have Git, Node.js 24+, and a browser key ready. Allow http://localhost:3003 on the key in the dashboard. You can try a map, search, and directions without installing any dependencies:
git clone --depth 1 https://github.com/unmap-dev/examples.git
cd examples
node scripts/serve.mjs quickstart 3003Open localhost:3003/basic-map.html, paste your browser key, and click Run example. You should see Calgary. The key stays in page memory and is not saved. Edit quickstart/example.js, refresh, and make it yours. Ctrl+C stops the server.
The 60-second target assumes these prerequisites and a key are ready. The first map needs an internet connection to the SDK CDN and API. Framework installs download more dependencies; install only the lane you need below.
Use pnpm 10.29.3 for the framework starters. Enable your installed Corepack with corepack enable, or install that version using your normal Node setup. Run the following commands from the repository root.
| Starter | What's included | Install only this lane | Start | URL |
|---|---|---|---|---|
| Plain TypeScript / Vite | 25 API examples | pnpm --filter unmap-examples-sdk install --frozen-lockfile |
pnpm dev:sdk |
http://localhost:3002 |
| Next.js / React | 12 map examples, 4 templates, 9 page blocks | pnpm --filter unmap-examples-next install --frozen-lockfile |
pnpm dev:next |
http://localhost:3000 |
| Nuxt / Vue | 9 page blocks | pnpm --filter unmap-examples-nuxt install --frozen-lockfile |
pnpm dev:nuxt |
http://localhost:3001 |
| HTML + GeoJSON | 3 downloadable templates, English and French | No install | node scripts/serve.mjs html 3003 |
http://localhost:3003 |
Each framework opens a catalog linking its examples. Allow the exact origin for your chosen starter on your browser key.
pnpm --filter unmap-examples-sdk install --frozen-lockfile
pnpm dev:sdkOpen Display a map, paste your key in the page, and press Run example. No environment file is needed. Edit sdk/examples/display-a-map/main.ts; Vite reloads it automatically. Each example's directory includes the original docs and its printed snippet.
For a key shared across examples, copy sdk/.env.example to sdk/.env.local, set VITE_UNMAP_KEY, and restart. A configured environment key takes precedence over the page input.
pnpm --filter unmap-examples-next install --frozen-lockfile
cp next/.env.example next/.env.localSet NEXT_PUBLIC_UNMAP_KEY in next/.env.local, then run pnpm dev:next. Open Store locator or Markers. The page entry is next/app/store-locator/page.tsx; its block is next/components/ui/store-locator.tsx.
pnpm --filter unmap-examples-nuxt install --frozen-lockfile
cp nuxt/.env.example nuxt/.envSet NUXT_PUBLIC_UNMAP_KEY in nuxt/.env, then run pnpm dev:nuxt. Open Store locator. Start editing nuxt/app/pages/store-locator.vue, or the block in nuxt/app/components/ui/store-locator.
Serve html/ with the command in the table. The files are the docs' actual downloads, with no framework dependencies. Replace YOUR_UNMAP_API_KEY locally in the chosen HTML file before refreshing. Keep your configured copy outside Git or revert the key before committing. For a demo that accepts the key in the page instead, use quickstart/.
Each template has en.html, fr.html, and matching GeoJSON under html/<template>/. Edit the data embedded in the HTML when changing the rendered locations; the GeoJSON file is a matching download for use in other projects.
| You want to… | Start here |
|---|---|
| Put a map on a page | sdk/examples/display-a-map |
| Search Canadian places | sdk/examples/search-for-a-place |
| Calculate directions | sdk/examples/get-directions |
| Plot your own GeoJSON | next/app/map-geojson/page.tsx |
| Build a branch finder | next/app/store-locator/page.tsx / nuxt/app/pages/store-locator.vue |
| Publish a local guide | next/app/local-guide/page.tsx / html/local-guide |
| Tell a geographic story | next/app/map-story/page.tsx |
| Explore every example | CATALOG.md, with source and guide links |
- Choose the closest entry in CATALOG.md and open its guide.
- Copy the page and its imported map components,
libhelpers, and sample data. The repository includes those dependencies so you can edit them. - Install the
@unmap/*packages used by that example. Use the same MapLibre version for the renderer and worker; copy the lane's worker setup if your app does not already have it. - Import MapLibre CSS once and preserve the registry CSS required by the copied components. Give the map a height and use [longitude, latitude] coordinates.
- Replace demonstration data with your own data, preserve applicable attribution, and use your app's browser key configuration.
For an existing shadcn project, the registry installation guide can install components and their dependencies directly. Sample data attribution is in DATA.md; copied UI license notices are in THIRD_PARTY.md.
Gallery components accept lang="fr"; HTML templates include separate French downloads. Some Legal Land and Energy examples need add-ons. Check the linked guide before choosing them as a first example. The map story may request routes or travel-time areas as chapters open.
Paste this into your clone, fork, or existing app:
Use https://github.com/unmap-dev/examples to build [describe my use case].
Read README.md, AGENTS.md, and CATALOG.md. Choose the nearest example for my
existing framework; install only that lane. Reuse its components and helpers,
keep attribution, and replace sample data only as needed. Keep my browser key
in ignored environment configuration or the demo's page input. Configure
MapLibre CSS, its matching worker, map height, and lifecycle cleanup. Run the
chosen lane's checks, start the app, and report the URL and setup steps.
AGENT_PROMPT.md includes a more detailed prompt and completion criteria. AGENTS.md provides repository instructions for compatible agents.
For one starter, use its focused check:
pnpm --dir sdk check # TypeScript + production build
pnpm --dir next check # TypeScript + static Next.js build
pnpm --dir nuxt check # Vue types + static Nuxt buildTo work on all starters, install the whole workspace with pnpm install --frozen-lockfile, then run pnpm check. This also verifies catalog and source integrity. Checks require no API key; live maps and requests do. The full workspace workflow is separate from the quickstart.
| Symptom | Fix |
|---|---|
| Framework catalog loads, map does not | Set the key in that lane's file above and restart; plain TypeScript also accepts a page input. |
| Key / origin rejected | Allow the exact http://localhost:<port> origin. 127.0.0.1 needs a separate allowed origin. |
| Blank map / controls misplaced | Give the map a height and import MapLibre CSS. |
| Worker 404 | Start with the supplied dev script so the matching worker is copied to public/maplibre/. |
| Layer denied | Enable the required add-on on your key, or choose a basic example. |
| pnpm / dev command missing | Use pnpm 10.29.3 in the repo root and install the selected lane first. |
| Port already used | Stop the other process or change the lane's port; update your allowed origin too. |
The basemap is worldwide; search and routing cover Canada. Browser environment variables are visible in the delivered app; use origin restrictions and keep server credentials server-side.
Issues and pull requests are welcome; see CONTRIBUTING.md. These verified snapshots come from the product repository's docs and registry. Maintainers backport accepted upstream changes there before the next sync. Your own fork can be customized normally.
Source is MIT. Sample data and dependencies retain their own attribution and licenses. Hosted API use requires a key and follows its service terms and quotas.