bknd Documentation

bknd supports three distinct modes of operation depending on how you want to manage configuration and data:

• UI-only mode: Configure your backend and manage data visually using the built-in Admin UI.
• Code-only mode: Configure your backend programmatically using a Drizzle-like API, while still using the Admin UI for data management.
• Hybrid mode: Configure your backend visually during development, but use a read-only configuration in production environments.

bknd is designed to avoid vendor lock-in by focusing on portability across databases and environments:

• Database Portability: bknd treats the database (targeting SQLite as the baseline) primarily as a data store and query interface. Schema enforcement and validation logic are moved to the application layer using TypeScript. This allows the same validation logic to run on both client and server and enables compatibility with other SQL or NewSQL systems (like PlanetScale).
• Environment Portability: bknd avoids Node-specific APIs in favor of Web APIs, ensuring it can run in any JavaScript environment (including workerd for Cloudflare Workers). It can be integrated directly into a JavaScript framework for single-deployment apps, or run standalone via CLI or Docker.

bknd supports integration via several frameworks and runtimes.

Supported Frameworks:

• NextJS
• React Router
• Astro
• SvelteKit
• Tanstack Start

Supported Runtimes:

• NodeJS
• Bun
• Cloudflare
• Deno
• AWS Lambda
• Vite
• Docker

Serving the backend as an API within a framework allows you to deploy your frontend and backend bundled together and add custom logic via standard routing.

You can quickly spin up a local bknd instance using the CLI. This will create a local data.db SQLite database and start the web server at http://localhost:1337.

Note: By default, the admin dashboard is open and not guarded to allow for rapid prototyping.

npx bknd run

To associate media (like a cover image or a gallery) with an entity when media is enabled, follow these three steps:

1. Add a virtual field to your entity using medium() (for a single item) or media() (for multiple items).
2. Add the media system entity to your schema using systemEntity("media", ...).
3. Define the relation in the em callback using polyToOne or polyToMany, specifying the mappedBy option to link the virtual field.

Note: Relations to the media entity are polymorphic.

If you cannot use local files or raw imports, you can point bknd to a remote URL containing the static assets using the adminOptions.assetsPath property within createRuntimeApp.

import { createRuntimeApp } from "bknd/adapter";

const app = await createRuntimeApp({
   connection: {
      url: "file:data.db",
   },
   adminOptions: {
      assetsPath: "https://...",
   },
});

export default {
   fetch: app.fetch,
};

You can set up bknd for AWS Lambda using either a CLI starter or a manual installation.

CLI Starter

To create a new Bun CLI starter project pre-configured for AWS, run:

npx bknd create -i aws

Manual Installation

If you already have an AWS Lambda project, install bknd as a dependency using your preferred package manager:

npm install bknd
# or
pnpm install bknd
# or
yarn add bknd
# or
bun add bknd

The SvelteKit adapter uses SvelteKit's hooks mechanism to handle API requests. Create a src/hooks.server.ts file and use the serve function from bknd/adapter/sveltekit. The adapter uses $env/dynamic/private to access environment variables, making it compatible with various deployment targets like Node.js, Bun, or Cloudflare.

import type { Handle } from "@sveltejs/kit";
import { serve } from "bknd/adapter/sveltekit";
import { env } from "$env/dynamic/private";
import config from "../bknd.config";

const bkndHandler = serve(config, env);

export const handle: Handle = async ({ event, resolve }) => {
  // handle bknd API requests
  const pathname = event.url.pathname;
  if (pathname.startsWith("/api/")) {
    const res = await bkndHandler(event);
    if (res.status !== 404) {
      return res;
    }
  }

  return resolve(event);
};

Use the following commands from the project root to manage your local development and production builds:

• npm install: Installs all necessary dependencies.
• npm run dev: Starts the local development server at http://localhost:3000.
• npm run dev:turbo: Starts a local Turso development server.
• npm run build: Builds the project for production.

If your application does not use the default /src/main.tsx entry point, you can specify a custom path using adminOptions.forceDev.mainPath in your server.ts file.

import { serve } from "bknd/adapter/vite";
import config from "./bknd.config";

export default serve({
  ...config,
  adminOptions: {
    forceDev: {
      mainPath: "/src/special.tsx",
    },
  },
});