App Configuration

Reference for bkper.yaml — the single file that declares your app's identity, menu integration, event subscriptions, deployment targets, secrets, and KV storage. Synced to Bkper via bkper app sync or bkper app deploy.

The bkper.yaml file is the single configuration file for your Bkper app. It defines the app’s identity, access control, menu integration, event handling, and deployment settings.

It lives in the root of your project and is synced to Bkper via bkper app sync or bkper app deploy.

Minimal example

id: my-app
name: My App
description: A Bkper app that does something useful
developers: myuser

Full example

From the app template:

id: my-app
name: My App
description: A Bkper app that does something useful

logoUrl: https://my-app.bkper.app/images/logo-light.svg
logoUrlDark: https://my-app.bkper.app/images/logo-dark.svg

website: https://bkper.com/apps/bkper-cli
ownerName: Bkper
ownerLogoUrl: https://avatars.githubusercontent.com/u/11943086?v=4
ownerWebsite: https://bkper.com

repoUrl: https://github.com/bkper/bkper-app-template
repoPrivate: true

developers: someuser *@yoursite.com
users: someuser *@yoursite.com

menuUrl: https://my-app.bkper.app?bookId=${book.id}
menuUrlDev: http://localhost:8787?bookId=${book.id}
menuPopupWidth: 500
menuPopupHeight: 300

webhookUrl: https://my-app.bkper.app/events
apiVersion: v5
events:
    - TRANSACTION_CHECKED

deployment:
    web:
        main: packages/web/server/src/index.ts
        client: packages/web/client
    events:
        main: packages/events/src/index.ts
    services:
        - KV
    secrets:
        - BKPER_API_KEY
    compatibility_date: '2026-01-28'

Field reference

App identity

Field	Description
`id`	Permanent app identifier. Lowercase letters, numbers, and hyphens only. Cannot be changed after creation.
`name`	Display name shown in the Bkper UI.
`description`	Brief description of what the app does.

Branding

Field	Description
`logoUrl`	App logo for light mode (SVG recommended).
`logoUrlDark`	App logo for dark mode.
`website`	App website or documentation URL.

Ownership

Field	Description
`ownerName`	Developer or company name.
`ownerLogoUrl`	Owner’s logo/avatar URL.
`ownerWebsite`	Owner’s website.
`repoUrl`	Source code repository URL.
`repoPrivate`	Whether the repository is private.
`deprecated`	Hides from app listings; existing installs continue working.

Access control

Field	Description
`developers`	Who can update the app and deploy new versions. Comma-separated Bkper usernames. Supports domain wildcards: `*@yoursite.com`.
`users`	Who can install and use the app. Same format as developers. Leave empty for public apps.

Field	Description
`menuUrl`	Production menu URL. Supports variable substitution.
`menuUrlDev`	Development menu URL (used when the developer clicks the menu).
`menuText`	Custom menu text (defaults to app name).
`menuPopupWidth`	Popup width in pixels.
`menuPopupHeight`	Popup height in pixels.

See Context Menu for details on building menu integrations.

The following variables can be used in menuUrl and menuUrlDev:

Variable	Description
`${book.id}`	Current book ID
`${book.properties.xxx}`	Book property value
`${account.id}`	Selected account ID
`${account.name}`	Selected account name
`${account.properties.xxx}`	Account property value
`${group.id}`	Selected group ID
`${group.name}`	Selected group name
`${group.properties.xxx}`	Group property value
`${transactions.ids}`	Comma-separated selected transaction IDs
`${transactions.query}`	Current search query

Event handling

Field	Description
`webhookUrl`	Production webhook URL for receiving events.
`webhookUrlDev`	Development webhook URL (auto-updated by `bkper app dev`).
`apiVersion`	API version for event payloads (currently `v5`).
`events`	List of event types to subscribe to.

See Event Handlers for details on handling events.

File patterns

Field	Description
`filePatterns`	List of glob patterns (e.g., `.ofx`, `.csv`). When a matching file is uploaded, a `FILE_CREATED` event is triggered.

Properties schema

The propertiesSchema field defines autocomplete suggestions for custom properties in the Bkper UI, helping users discover the correct property keys and values for your app:

propertiesSchema:
    book:
        keys:
            - my_app_enabled
        values:
            - 'true'
            - 'false'
    group:
        keys:
            - my_app_category
    account:
        keys:
            - my_app_sync_id
    transaction:
        keys:
            - my_app_reference

Deployment

For apps deployed to the Bkper Platform:

Field	Description
`deployment.web.main`	Entry point for the web handler (serves UI and API).
`deployment.web.client`	Directory for static client assets.
`deployment.events.main`	Entry point for the events handler (processes webhooks).
`deployment.services`	Platform services to provision. Currently: `KV` (key-value storage).
`deployment.secrets`	Secret names used by the app. Managed via `bkper app secrets`.
`deployment.compatibility_date`	Cloudflare Workers compatibility date.

See Building & Deploying for the full deployment workflow.