userbase/docs/content/docs/(documentation)/usage/introduction.mdx

---
title: "Introduction"
description: "Setting up bknd"
icon: Pin
tags: ["documentation"]
---

import { TypeTable } from "fumadocs-ui/components/type-table";
import { SquareMousePointer, Code, Blend } from 'lucide-react';

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

1. [Run it using the CLI](/usage/cli): That's the easiest and fastest way to get started.
2. Use a runtime like [Node](/integration/node), [Bun](/integration/bun) or
   [Cloudflare](/integration/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](/integration/nextjs),
   [Astro](/integration/astro) or [Remix](/integration/remix).

There is also a fourth option, which is running it inside a
[Docker container](/integration/docker). 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:

```typescript
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:

<Cards className="grid-cols-1 sm:grid-cols-2 md:grid-cols-3">
  <Card title="UI-only" href="/usage/introduction#ui-only-mode" icon={<SquareMousePointer className="text-fd-primary !size-6" />}>
     This is the default mode, it allows visual configuration and saves the configuration to the database. Expects you to deploy your backend separately from your frontend.
  </Card>
  <Card title="Code-only" href="/usage/introduction#code-only-mode" icon={<Code className="text-fd-primary !size-6" />}>
    This mode allows you to configure your backend programmatically, and define your data structure with a Drizzle-like API. Visual configuration controls are disabled. 
  </Card>
  <Card title={"Hybrid"} href="/usage/introduction#hybrid-mode" icon={<Blend className="text-fd-primary !size-6" />}>
    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. 
  </Card>
</Cards>

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

```typescript title="bknd.config.ts"
import type { BkndConfig } from "bknd";

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

<TypeTable type={{
  config: {
    description: "The initial configuration when `mode` is `\"db\"`, and as the produced configuration when `mode` is `\"code\"`.",
    type: "object",
    properties: {
      /* ... */
    }
  },
  ["options.mode"]: {
    description: "The options for the app.",
    type: '"db" | "code"',
    default: '"db"'
  },
  ["options.manager.secrets"]: {
    description: "The app secrets to be provided when using `\"db\"` mode. This is required since secrets are extracted and stored separately to the database.",
    type: "object",
    properties: {
      /* ... */
    }
  },
  ["options.manager.storeSecrets"]: {
    description: "Whether to store secrets in the database when using `\"db\"` mode.",
    type: "boolean",
    default: "true"
  }
}} />

### 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.

```typescript
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. 

```typescript title="bknd.config.ts"
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.

```typescript title="bknd.config.ts"
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.


| Type           | Plugin                                                                 | CLI Command                |
|----------------|-----------------------------------------------------------------------|----------------------------|
| Configuration  | [`syncConfig`](/extending/plugins/#syncconfig)                        | [`config`](/usage/cli/#getting-the-configuration-config)   |
| Secrets        | [`syncSecrets`](/extending/plugins/#syncsecrets)                      | [`secrets`](/usage/cli/#getting-the-secrets-secrets) |
| Types          | [`syncTypes`](/extending/plugins/#synctypes)                          | [`types`](/usage/cli/#generating-types-types)     |