Skip to content
Bkper
Sign In

Building & Deploying

Build locally, sync app metadata and managed source, then explicitly deploy to the Bkper Platform. Covers previews, secrets, KV storage, and deployment status.

The deployment workflow

Run the template’s deterministic checks before releasing:

npm run check

  1. Build — Compile your code

    npm run build

    This runs two build steps:

    • Client (Vite) to static assets in dist/client/
    • Server Worker bundle (esbuild) to dist/server/

    Build output includes size reporting so you can monitor bundle sizes.

  2. Sync — Update app metadata and managed source

    bkper app sync

    Syncs your bkper.yaml configuration to Bkper — name, description, menu URLs, webhook URLs, access control, and branding. For an app using Bkper-managed source, it also safely pushes the current clean, committed branch. Sync does not build or deploy the app.

  3. Deploy — Upload the local build to the platform

    bkper app deploy

    For a managed-source app, deploy safely pushes and verifies the current commit. It then uploads your existing pre-built code from dist/ to the Bkper Platform. The command does not run a build. Your app is live at https://{appId}.bkper.app.

The app template combines all three after source changes are committed:

npm run deploy

Use npm run deploy:preview for the preview environment.

See Shared App Source for managed-source setup, cloning, access, and external Git workflows.

Environments

Production

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

bkper app deploy

Production serves:

Client:       https://{appId}.bkper.app
API routes:   https://{appId}.bkper.app/api/*
OpenAPI spec: https://{appId}.bkper.app/openapi.json
Events:       https://{appId}.bkper.app/events

Preview

Deploy to a separate preview environment for testing before production:

bkper app deploy --preview

Preview URLs use a dash suffix: https://{appId}-preview.bkper.app. For example, an app with id: my-app deploys to https://my-app-preview.bkper.app.

Preview serves:

Client:       https://{appId}-preview.bkper.app
API routes:   https://{appId}-preview.bkper.app/api/*
OpenAPI spec: https://{appId}-preview.bkper.app/openapi.json
Events:       https://{appId}-preview.bkper.app/events

Preview has independent secrets and KV storage from production.

There is one app deployment per environment. /events is handled by the same Worker as the client assets and /api/* routes.

Secrets management

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

deployment:
    secrets:
        - EXTERNAL_SERVICE_TOKEN

Setting secrets

# Set for production
bkper app secrets put EXTERNAL_SERVICE_TOKEN


# Set for preview
bkper app secrets put EXTERNAL_SERVICE_TOKEN --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 EXTERNAL_SERVICE_TOKEN

Accessing in code

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

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

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 at /events, and the app’s context menu appears in the book’s UI.

Next steps