Skip to content
Bkper
app.header.homeapp.header.docs

Development Experience

bkper app dev starts the full local development environment in one command: Vite HMR for the UI, Miniflare for the Workers runtime, and an automatic Cloudflare tunnel so Bkper routes webhook events to your laptop.

The bkper app dev command starts your entire development environment with a single command.

What it starts

Terminal window
bkper app dev

This orchestrates:

  1. Vite dev server — HMR for the client UI. Changes to Lit components reflect instantly in the browser.
  2. Miniflare — Simulates the Cloudflare Workers runtime locally for the web server and events handler.
  3. Cloudflare tunnel — Exposes the events handler via a public URL so Bkper can route webhook events to your machine.
  4. File watching — Server and shared package changes trigger automatic rebuilds.

URLs

HandlerURL
Web (client + server)http://localhost:8787
Events (via tunnel)https://<random>.trycloudflare.com/events

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

You can run specific handlers independently:

Terminal window
# Start only the web handler
bkper app dev --web


# Start only the events handler
bkper app dev --events


# Override default ports
bkper app dev --cp 5173 --sp 8787 --ep 8791


# Don't open the browser automatically
bkper app dev --no-open

Local secrets

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

Terminal window
# .dev.vars (gitignored)
BKPER_API_KEY=your-api-key-here

Copy from the provided template:

Terminal window
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:

Terminal window
bkper app build

The development loop

  1. Run bkper app dev
  2. Edit client code — see changes instantly via HMR
  3. Edit server code — auto-rebuilds and reloads
  4. Trigger events in Bkper — your local handler receives them 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.