Skip to content
Bkper
app.header.homeapp.header.docsapp.header.apps

Your First App

Scaffold, run, and deploy a Bkper platform app in minutes. This is a thin walkthrough — deep reference for each topic lives in the other App docs.

This tutorial walks you through building and deploying a Bkper app from scratch. For the deep reference on any topic — architecture, configuration, development, events, or deployment — follow the links in each step.

Prerequisites

Development Setup — the CLI installed and authenticated.

Walkthrough

  1. Scaffold from the template

    Terminal window
    bkper app init my-app
    cd my-app

    The CLI sets your app ID, package name, URLs, and event-handler loop guards automatically. See App Configuration for the full bkper.yaml reference.

  2. Start developing

    Terminal window
    npm run dev

    This runs the Vite client dev server and the local worker runtime with automatic webhook tunneling. See Development Experience for details.

  3. Open the app

    Visit http://localhost:5173. Select a book to see account balances. No OAuth setup required — the platform handles authentication.

  4. Trigger an event

    Go to any Bkper book and check (reconcile) a transaction. Your local event handler receives the webhook via the tunnel and creates a 20% draft transaction. See Event Handlers for the full event model.

  5. Make a change

    Edit the handler in packages/events/src/handlers/transaction-checked.ts and save. The worker reloads automatically. Check another transaction to see your change.

  6. Customize your listing

    Update bkper.yaml with your app’s description, owner details, and repository URL. Replace the placeholder logos in packages/web/client/public/images/. See App Listing for publishing details.

  7. Update the README

    Edit README.md for end users — what the app does and how to use it. Keep developer docs in AGENTS.md.

  8. Deploy

    Terminal window
    npm run build
    bkper app sync
    bkper app deploy

    Your app is live at https://my-app.bkper.app. See Building & Deploying for preview environments, secrets, and KV.

What you built

You wrotePlatform handled
~30 lines of UIOAuth, consent screen, token refresh
~40 lines of event logicHosting, SSL, edge routing
bkper.yamlWebhook tunnels, KV, type generation

Next steps