BTC Map Web App

Getting started

1. git clone
   to clone the repo and cd into the directory
2. Install pnpm ≥ 10 (if needed)
   If pnpm is not found — or pnpm --version reports < 10 — run mise install (see note below) or use one of the standalone installation methods
3. pnpm install
   to install the packages
4. pnpm dev
   will open the app on: http://localhost:5000

Check your changes before commit/pushing

• pnpm run format:fix
• pnpm run lint
• pnpm run check
• pnpm run typecheck
• pnpm run test --run

Local API development

To test the frontend against a local btcmap-api instance:

1. Start the API: cd btcmap-api && cargo run (binds to 127.0.0.1:8000)
2. Add to your .env — pick one:
   • VITE_API_BASE_URL=/btcmap-api-proxy — routes through the Vite dev proxy (avoids CORS; works for client-side calls and SSR load functions that use SvelteKit's event.fetch)
   • VITE_API_BASE_URL=http://127.0.0.1:8000 — direct; works everywhere including SSR axios calls, but requires the API to send CORS headers
3. Start the frontend: pnpm dev

Remove or comment out the env var to switch back to the production API.

Note: The add-location form submits through /api/submit-place, which calls btcmap-api's submit_place RPC and needs BTCMAP_IMPORT_TOKEN. The RPC target follows VITE_API_BASE_URL (the endpoint uses SvelteKit's event fetch, so the dev-proxy path works server-side too).

Build project

1. Create .env
   Copy .env.example and save as .env
2. pnpm build

NOTE: BTC Map requires Node.js ≥ 24 (Node 24 LTS). If you have mise, run mise install in the repo root to get the correct Node and pnpm versions. Any pnpm ≥ 10 works: pnpm reads the packageManager pin in package.json and switches to that exact version automatically, so Corepack is not needed locally (pnpm no longer recommends it). Netlify builds are the exception: Netlify still provisions pnpm via Corepack from that same packageManager field — so keep the field pinned to an exact version, and see the comment in netlify.toml for the Node-version floor this implies.

Icons

• Iconify: for general material/fontawesome icons via Icon.svelte
• Custom icons (socials, apps, mobile-nav): imported as raw SVGs in src/lib/icons/ via wrapper components (IconSocials.svelte, IconApps.svelte, IconMobileNav.svelte)
• Offline icon bundle: Iconify icons are served from the committed src/lib/icons/generated/iconData.json rather than fetched at runtime (the live API is only a fallback). After adding an <Icon icon="…"> usage, changing the note picker's icons (NOTE_ICONS in src/lib/noteIcons.ts) or bumping an @iconify-json/* package, run pnpm icons:generate and commit the result: the format-and-lint CI job fails on a stale bundle. When the places API gains a new tag or category, run pnpm icons:refresh first to update the pin vocabulary (scripts/pin-icons.json). Never hand-edit the generated file

E2E tests

Install

  pnpm playwright install

.env.example ships SERVER_CRYPTO_KEY and SERVER_INIT_VECTOR empty, which leaves /captcha broken and every captcha-gated form control disabled — specs that interact with those controls fail. Generate throwaway keys once (this is what CI does):

  echo "SERVER_CRYPTO_KEY=$(openssl rand -hex 32)" >> .env
  echo "SERVER_INIT_VECTOR=$(openssl rand -hex 16)" >> .env

Run tests

  pnpm playwright test
    Runs the end-to-end tests.

  pnpm playwright test --ui
    Starts the interactive UI mode.

  pnpm playwright test --project=chromium
    Runs the tests only on Desktop Chrome.

  pnpm playwright test example
    Runs the tests in a specific file.

  pnpm playwright test --debug
    Runs the tests in debug mode.

PWA

This website is a progressive web app, meaning you can install it on your mobile device and use it like a native application. Just look for the Add to home screen or Install option in your browser while visiting btcmap.org.

Embedding

For information on how to embed the BTC Map web map onto your own website or application please reference our Wiki.

---

Attributions

Thanks to:

Base map tiles

• OpenFreeMap
• OpenStreetMap

Icons

Tagger profile badges by AndrejCibik

Satoshi nakamoto icons created by Vitaly Gorbachev - Flaticon

---