Introduction

There are several methods to get bknd up and running. You can choose between these options:

1. Run it using the CLI: That's the easiest and fastest way to get started.
2. Use a runtime like Node, Bun or Cloudflare (workerd). This will run the API and UI in the runtime's native server and serves the UI assets statically from node_modules.
3. Run it inside your React framework of choice like Next.js, Astro or Remix.

There is also a fourth option, which is running it inside a Docker container. This is essentially a wrapper around the CLI.

Basic setup

Regardless of the method you choose, at the end all adapters come down to the actual instantiation of the App, which in raw looks like this:

import { createApp, type BkndConfig } from "bknd";

// create the app
const config = {
  /* ... */
} satisfies BkndConfig;
const app = createApp(config);

// build the app
await app.build();

// export for Web API compliant envs
export default app;

In Web API compliant environments, all you have to do is to default exporting the app, as it implements the Fetch API.

Modes

Main project goal is to provide a backend that can be configured visually with the built-in Admin UI. However, you may instead want to configure your backend programmatically, and define your data structure with a Drizzle-like API:

In the following sections, we'll cover the different modes in more detail. The configuration properties involved are the following:

import type { BkndConfig } from "bknd";

export default {
  config: { /* ... */ }
  options: {
    mode: "db", // or "code"
    manager: {
      secrets: { /* ... */ },
      storeSecrets: true,
    },
  }
} satisfies BkndConfig;

UI-only mode

This mode is the default mode. It allows you to configure your backend visually with the built-in Admin UI. It expects that you deploy your backend separately from your frontend, and make changes there. No configuration is needed, however, if you want to provide an initial configuration, you can do so by passing a config object.

import type { BkndConfig } from "bknd";

export default {
  // this will only be applied if the database is empty
  config: { /* ... */ },
} satisfies BkndConfig;

Code-only mode

This mode allows you to configure your backend programmatically, and define your data structure with a Drizzle-like API. Visual configuration controls are disabled.

import { type BkndConfig, em, entity, text, boolean } from "bknd";
import { secureRandomString } from "bknd/utils";

const schema = em({
  todos: entity("todos", {
    title: text(),
    done: boolean(),
  }),
});

export default {
  // example configuration
  config: {
    data: schema.toJSON(),
    auth: {
      enabled: true,
      jwt: {
        secret: secureRandomString(64),
      },
    }
  },
  options: {
    // this ensures that the provided configuration is always used
    mode: "code",
  },
} satisfies BkndConfig;

Hybrid mode

This mode allows you to configure your backend visually while in development, and uses the produced configuration in a code-only mode for maximum performance. It gives you the best of both worlds.

While in development, we set the mode to "db" where the configuration is stored in the database. When it's time to deploy, we export the configuration, and set the mode to "code". While in "db" mode, the config property interprets the value as an initial configuration to use when the database is empty.

import type { BkndConfig } from "bknd";

// import your produced configuration
import appConfig from "./appconfig.json" with { type: "json" };

export default {
  config: appConfig,
  options: {
    mode: process.env.NODE_ENV === "development" ? "db" : "code",
    manager: {
      secrets: process.env
    }
  },
} satisfies BkndConfig;

To keep your config, secrets and types in sync, you can either use the CLI or the plugins.