Building & Deploying

The three-step deployment workflow — build your code, sync app metadata from bkper.yaml, and deploy to the Bkper Platform. Covers preview environments, secrets management, and KV storage.

The deployment workflow

Build — Compile your code
Terminal window
```
bkper app build
```
This builds all configured handlers:
- Web client (Vite) to static assets
- Web server (esbuild) to a Workers bundle
- Events handler (esbuild) to a Workers bundle
Build output includes size reporting so you can monitor bundle sizes.
Sync — Update app metadata
Terminal window
```
bkper app sync
```
Syncs your bkper.yaml configuration to Bkper — name, description, menu URLs, webhook URLs, access control, and branding. Run this whenever you change app settings.
Deploy — Upload code to the platform
Terminal window
```
bkper app deploy
```
Deploys your built code to the Bkper Platform. Your app is live at https://{appId}.bkper.app.

The typical workflow combines sync and deploy:

bkper app sync && bkper app deploy

Environments

Production

The default deployment target. Your app runs at https://{appId}.bkper.app.

bkper app deploy

Preview

Deploy to a separate preview environment for testing before production:

bkper app deploy --preview

Preview has independent secrets and KV storage from production.

Independent handler deployment

Deploy only the events handler:

bkper app deploy --events

Useful when you’ve only changed the events handler and want a faster deployment. Web is deployed by default.

Secrets management

Secrets are environment variables stored securely on the platform. Declare them in bkper.yaml:

deployment:
    secrets:
        - BKPER_API_KEY
        - EXTERNAL_SERVICE_TOKEN

Setting secrets

# Set for production
bkper app secrets put BKPER_API_KEY

# Set for preview
bkper app secrets put BKPER_API_KEY --preview

You’ll be prompted to enter the value.

Listing and deleting

# List all secrets
bkper app secrets list

# Delete a secret
bkper app secrets delete BKPER_API_KEY

Accessing in code

Secrets are available as c.env.SECRET_NAME in your Hono handlers:

app.get('/api/data', async (c) => {
    const apiKey = c.env.BKPER_API_KEY;
    // use apiKey
});

During local development, use the .dev.vars file instead. See Development Experience.

Services

KV storage

Declare KV in bkper.yaml:

deployment:
    services:
        - KV

The platform provisions a KV namespace for your app. Access it via c.env.KV:

await c.env.KV.put('key', 'value', { expirationTtl: 3600 });
const value = await c.env.KV.get('key');

KV storage is separate between production and preview environments.

Deployment status

Check the current state of your deployment:

bkper app status

Installing on books

After deploying, install the app on specific books to activate it:

# Install on a book
bkper app install <appId> -b <bookId>

# Uninstall from a book
bkper app uninstall <appId> -b <bookId>

Once installed, the app’s event handlers receive events from that book, and the app’s context menu appears in the book’s UI.