BitDevs Map

An interactive world map of cities with an active BitDevs group — Socratic seminars where developers gather to discuss changes to the Bitcoin protocol and the technologies around it.

The map renders a dotted landmass on a canvas, drops a marker on every city, and keeps a searchable city index in sync with it. All city data comes from a single JSON file, so adding a community is a one-line change.

Tech stack

• React + TypeScript
• Vite for dev server and bundling
• Tailwind CSS v4 for styling (brand tokens in @theme)
• Bun as the package manager and runtime
• d3-geo (Natural Earth projection) + topojson-client + world-atlas for the map
• vite-plugin-pwa (Workbox) for the web app manifest and the service worker

Getting started

Requires Bun (>= 1.3). Clone the repo and install dependencies:

bun install

Scripts

bun run dev      # start the dev server (http://localhost:5173)
bun run build    # type-check and build for production into dist/
bun run preview  # serve the production build locally

Progressive Web App

The production build ships a web app manifest and a service worker, so the site can be installed to a home screen and keeps working without a connection:

• The app shell (markup, styles, bundle and the world topology) is precached at install time.
• The git-scraped topics.json and events.json are served from cache and refreshed in the background (stale-while-revalidate). If they were never fetched, the app still falls back to the snapshots bundled in src/data.
• A new deploy replaces the cached shell automatically on the next visit.

Service workers only run over HTTPS (or localhost) and are not registered by the dev server, so use bun run build && bun run preview to exercise them.

Fedi mini app

The same build runs as a mini app inside Fedi's in-app browser, so a Fedi community can open the map from its home screen. docs/fedi-mini-app.md has the entry a federation adds to its meta config, and what the app changes when it detects the webview.

Add your city

There are two ways to get a city onto the map. Pick whichever you are comfortable with — both end up in the same place.

Option A — Open an issue (no coding required)

If you don't want to touch the code, just open a "New city" issue with your city, country and the group's link. A maintainer will add it for you. If you don't know the exact coordinates, leave them blank — we'll fill them in.

Option B — Open a pull request

City data lives in src/data/bitdevs.json. Add an object to the array and open a PR:

{
  "city": "Buenos Aires",
  "country": "Argentina",
  "lat": -34.6037,
  "lng": -58.3816,
  "url": "https://www.bitdevsba.org/"
}

The marker and the city card are generated automatically from each entry — no other changes are needed.

Field reference

Field	Type	Description
city	string	City name shown on the marker and in the index.
country	string	Country, shown as the marker subtitle.
lat	number	Decimal-degree latitude of the city center.
lng	number	Decimal-degree longitude of the city center.
url	string	Public link to the group (website, Meetup, X or GitHub).

Guidelines

• Keep the list alphabetical by city so diffs stay clean.
• Use the city center coordinates in decimal degrees. You can grab them from Google Maps (right-click a location to copy lat, lng) or latlong.net.
• Make sure the group is active and the link works.
• Run bun run build before opening the PR to confirm everything still compiles.

Project structure

.github/
  ISSUE_TEMPLATE/add-city.yml   Guided form for the "add a city" issue
  pull_request_template.md      Checklist shown when opening a PR
docs/
  BitDevs Map.html              Original Claude Design reference (static HTML)
  fedi-mini-app.md              Running the site as a mini app inside Fedi
public/
  favicon.svg                   Brand favicon
  pwa-*.png, maskable-*.png     Installable app icons
  apple-touch-icon.png          Home-screen icon on iOS
  og-image.png                  Social card (Open Graph / Twitter)
src/
  data/bitdevs.json             City data — edit this to add a city
  components/                   TopBar, Hero, WorldMap, CityIndex, Footer
  types.ts                      The BitDev type
  fedi.ts                       Detection of Fedi's mini app webview
  index.css                     Tailwind theme tokens + map component styles
  App.tsx, main.tsx             App entry points

Contributing

1. Fork the repository and create a branch (git checkout -b add-my-city).
2. Make your change (for a new city, edit src/data/bitdevs.json).
3. Run bun run build to verify it compiles.
4. Commit, push, and open a pull request.

License

MIT © Kyra Labs