Development Experience

Local development uses two composable processes — the worker runtime and the client dev server — that run concurrently.

What runs

npm run dev

The project template runs both processes via concurrently:

1. vite dev — Client dev server with HMR. Changes to Lit components reflect instantly in the browser. Configured in vite.config.ts.
2. bkper app dev — The worker runtime:
   • Miniflare — Simulates the single Cloudflare Worker locally.
   • Cloudflare tunnel — Exposes /events via a public URL so Bkper can route webhook events to your machine.
   • File watching — Server changes trigger automatic rebuilds via esbuild.

You can also run them independently: npm run dev:client for just the UI, or npm run dev:server for the local Worker.

URLs

Endpoint	URL
Client (Vite dev server)	http://localhost:5173
Server Worker (Miniflare)	http://localhost:8787
App API routes	http://localhost:8787/api/*
App OpenAPI spec	http://localhost:8787/openapi.json
Events (via tunnel to the same Worker)	https://<random>.trycloudflare.com/events

The Vite dev server proxies /api requests to http://localhost:8787 (configured in vite.config.ts). The app OpenAPI spec is served by the Worker at http://localhost:8787/openapi.json. The tunnel URL is automatically registered as the webhookUrlDev in Bkper, so events from books where you’re the developer are routed to your local machine.

Configuration flags

There is one local Worker. Override its port when needed:

bkper app dev --sp 8787

Client configuration

The client dev server is configured in vite.config.ts at the project root. This is a standard Vite config — add plugins, adjust settings, or customize the dev server as needed.

Local development authentication

During local development, the Vite dev server runs a Bkper auth middleware plugin (createBkperAuthMiddleware() from bkper/dev). This plugin:

1. Uses your CLI credentials (from bkper auth login) to obtain and refresh OAuth tokens
2. Injects the token into your client code automatically
3. Proxies /api requests to the Miniflare worker

Before starting development, run:

bkper auth login   # one-time setup

Then npm run dev handles authentication automatically. The client calls auth.getAccessToken() and the middleware ensures the token is valid.

When your client calls an app server route under /api/*, include that token as Authorization: Bearer <token> to match production dispatch behavior. Local outbound uses your CLI credentials when the app server or event handler calls Bkper.

If you see authentication errors in the browser, verify you’re logged in:

bkper auth token   # should print a token

This is the canonical pattern for local development. Do not manually pass tokens or implement custom auth flows.

Local secrets

Environment variables for local development live in a .dev.vars file at the project root:

# .dev.vars (gitignored)
EXTERNAL_SERVICE_TOKEN=your-token-here

Copy from the provided template:

cp .dev.vars.example .dev.vars

These variables are available as c.env.SECRET_NAME in your Hono handlers during development.

KV storage

KV data persists locally in the .mf/kv/ directory during development. This means your data survives restarts — useful for testing caching and state patterns.

// Read
const value = await c.env.KV.get('my-key');

// Write with TTL
await c.env.KV.put('my-key', 'value', { expirationTtl: 3600 });

See the Cloudflare KV documentation for more usage patterns.

Type generation

The env.d.ts file provides TypeScript types for the Worker environment — KV bindings, secrets, and other platform services. It’s auto-generated based on your bkper.yaml configuration and checked into version control.

Rebuild it after changing services or secrets in bkper.yaml:

bkper app build

The development loop

1. Run npm run dev
2. Edit client code — see changes instantly via Vite HMR
3. Edit server code — auto-rebuilds and reloads via esbuild watch
4. Trigger events in Bkper — your local Worker receives them at /events via the tunnel
5. Check the activity stream in Bkper to see handler responses
6. Iterate

Debugging

• Server errors — Check the terminal output from bkper app dev. Worker runtime errors appear here.
• Event handler errors — Check the Bkper activity stream. Click on an event handler response to see the result or error, and replay failed events.
• Client errors — Use browser DevTools. The Vite dev server provides source maps.