Getting started

Requirements

Install Bun 1.4.2. The GeoNames data importer also calls the system unzip and sqlite3 commands, so both must be available on your PATH before importing data.

From the repository root, install the workspace dependencies:

bun install

Run the demo and docs

From the repository root, start both apps:

bun run dev

The deployed demo is geonames-global-demo.vimaksh.workers.dev and the deployed docs are geonames-docs.pages.dev. Those links are distinct from local development: bun run dev serves the demo on port 3000 and docs on port 4321. Open the local URLs printed by the command for local work. The demo starts the GeoNames service as an auxiliary Worker through a local Service Binding; you do not need to start the service separately. Its D1 database is stored under apps/service/.wrangler/global-state/ and is local development state, not a dataset checked into Git.

The demo’s Countries catalog shows worldwide country/territory references and the fixed seven continents. Select a tab and click Fetch to request that list. Local development serves it at /countries on the demo URL printed by the command; the hosted route requires deploying the updated service and demo. The API reference explains the browser routes and their provider RPC methods.

Integrate another Worker

The demo’s HTTP routes are on geonames-global-demo; they are not routes on the RPC provider. A Worker consumer in the same Cloudflare account binds as GEONAMES to service geonames-global-service in its Wrangler services array, with no D1 database ID, D1 binding, or KV binding. The provider’s fetch() returns 404 by design; call typed methods such as env.GEONAMES.searchPage(query, limit, offset, options) through RPC. Start from the copyable WorkerEntrypoint, service type, and binding configuration.

For local/demo search behavior, defaults and strict geographic filters, see search scopes and pagination. The admin settings API persists default country, default-scope enablement, and global fallback in D1; its schema migration must be applied before deploying the service version that reads it.

To apply the settings schema to the local D1 database before running the updated service, use bun run --cwd apps/service db:migrations:local from the repository root. It uses the same .wrangler/global-state persistence path as the Vite development server. For the remote migration and deployment sequence, see the repository-root MANUAL_VERIFICATION.md.

If you have not imported the GeoNames inputs into local D1, follow Import the local GeoNames data first. A previously populated local D1 can be opened directly by starting the demo; importing is not part of the demo startup command. Stop the demo before running local database imports.

The service config uses preview_database_id to keep the local D1 identity stable while database_id points at the remote database. Changing the preview ID or persistState path can make the existing local data appear missing without deleting it. Restart the Vite dev server after changing a Wrangler binding if it does not reload the config automatically.

A separate Git worktree starts without the primary checkout’s ignored D1 dataset. Run documentation-only commands below when reviewing docs; do not change the preview ID or start a new import merely because a fresh worktree has no search data. Each demo checkout resolves its persistence path relative to that checkout.

Run only the documentation site

To start just the docs from the repository root:

bun run --filter geonames-docs dev

Or run it from apps/docs:

bun run dev

Open the local URL printed by Astro.

Deployed demo

The deployed demo is geonames-global-demo.vimaksh.workers.dev. The five-source local and remote rebuilds passed parity verification. The service owns shared KV search caching; consumers need only a Service Binding. The geographic-scope and ranking release uses search:v6, with environment-specific lifetimes documented under Worldwide search. Local bun run dev uses local development state and does not create remote resources. Remote imports and deployments require explicit approval and the intended Cloudflare account. Before deploying a changed web Worker, run bun run build in apps/web: the Cloudflare Vite plugin generates a redirected Wrangler config under dist/, and deployment uses its generated bindings rather than reading only the source wrangler.jsonc.