shishantbiswas/bknd
1
0
Fork 0
mirror of https://github.com/shishantbiswas/bknd.git synced 2026-03-16 04:27:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: added docs about how to use bknd.config.ts

Browse Source
This commit is contained in:
dswbx
2025-06-05 17:11:50 +02:00
parent 7b128c9701
commit 3e77982996
11 changed files with 566 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

153
docs/extending/config.mdx Normal file
View File

@@ -0,0 +1,153 @@
---
title: bknd.config.ts
---
The central configuration file to extend bknd should be placed in the root of your project, so that the [CLI](/usage/cli#using-configuration-file-bknd-config) can automatically pick it up. It allows to:
* define your database connection centrally
* pass in initial configuration or data seeds when booting the first time
* add plugins to the app
* hook into system events
* define custom routes and endpoints
A simple example of a `bknd.config.ts` file:
```typescript bknd.config.ts
import type { BkndConfig } from "bknd/adapter";
export default {
connection: {
url: "file:data.db",
}
} satisfies BkndConfig;
```
## Overview
The `BkndConfig` extends the [`CreateAppConfig`](/usage/introduction#configuration-createappconfig) type with the following properties:
```typescript
export type BkndConfig = CreateAppConfig & {
// return the app configuration as object or from a function
app?: CreateAppConfig | ((args: Args) => CreateAppConfig);
// called before the app is built
beforeBuild?: (app: App) => Promise<void>;
// called after the app has been built
onBuilt?: (app: App) => Promise<void>;
// passed as the first argument to the `App.build` method
buildConfig?: Parameters<App["build"]>[0];
// force the app to be recreated
force?: boolean;
// the id of the app, defaults to `app`
id?: string;
}
```
The supported configuration file extensions are `js`, `ts`, `mjs`, `cjs` and `json`. Throughout the documentation, we'll use `ts` for the file extension.
### `app` (CreateAppConfig)
The `app` property is a function that returns a `CreateAppConfig` object. It allows to pass in the environment variables to the configuration object.
```typescript
import type { BkndConfig } from "bknd/adapter";
export default {
app: ({ env }) => ({
connection: {
url: env.DB_URL,
}
})
} satisfies BkndConfig;
```
See [Database](/usage/database) for more information on how to configure the database connection.
### `beforeBuild`
The `beforeBuild` property is an async function that is called before the app is built. It allows to modify the app instance that may influence the build process.
```typescript
import type { BkndConfig } from "bknd/adapter";
export default {
beforeBuild: async (app: App) => {
// do something that has to happen before the app is built
}
}
```
### `onBuilt`
The `onBuilt` property is an async function that is called after the app has been built. It allows to hook into the app after it has been built. This is useful for defining event listeners or register custom routes, as both the event manager and the server are recreated during the build process.
```typescript
import { type App, AppEvents } from "bknd";
import type { BkndConfig } from "bknd/adapter";
export default {
onBuilt: async (app: App) => {
console.log("App built", app.version());
// registering an event listener
app.emgr.onEvent(AppEvents.AppRequest, (event) => {
console.log("Request received", event.request.url);
})
// registering a custom route
app.server.get("/hello", (c) => c.text("Hello World"));
}
}
```
### `force` & `id`
The `force` property is a boolean that forces the app to be recreated. This is mainly useful for serverless environments where the execution environment is re-used, and you may or may not want to recreate the app on every request.
The `id` property is the reference in a cache map. You may create multiple instances of apps in the same process by using different ids (e.g. multi tenant applications).
## Framework & Runtime configuration
Depending on which framework or runtime you're using to run bknd, the configuration object will extend the `BkndConfig` type with additional properties.
### `RuntimeBkndConfig`
[Runtime adapters](/integration/runtime) need additional configuration to serve static assets for the admin UI.
```typescript
export type RuntimeBkndConfig<Args = any> = BkndConfig<Args> & {
// the path to the dist folder to serve static assets for the admin UI
distPath?: string;
// custom middleware to serve static assets for the admin UI
serveStatic?: MiddlewareHandler | [string, MiddlewareHandler];
// options for the admin UI
adminOptions?: AdminControllerOptions | false;
};
```
### `FrameworkBkndConfig`
[Framework adapters](/integration/framework) may need additional configuration based on the framework's requirements. For example, the `NextjsBkndConfig` type extends the `BkndConfig` type with the following additional properties:
```typescript
type NextjsEnv = NextApiRequest["env"];
export type NextjsBkndConfig<Env = NextjsEnv> = FrameworkBkndConfig<Env> & {
cleanRequest?: { searchParams?: string[] };
};
```
Next.js adds the mounted path to the request object, so that the `cleanRequest` property can be used to remove the mounted path from the request URL. See other frameworks for more information on how to configure them.
## Using the configuration file
The configuration file is automatically picked up if you're using the [CLI](/usage/cli). This allows interacting with your application using the `bknd` command. For example, you can run the following command in the root of your project to start an instance:
```bash
npx bknd run
```
When serving your application, you need to make sure to import the contents of your configuration file. If you're using Next.js for example, it's recommended to follow these steps:
1. create a `bknd.config.ts` file in the root of your project which defines the connection to the database, adds event listeners and custom routes.
2. create a `bknd.ts` file inside your app folder which exports helper functions to instantiate the bknd instance and retrieve the API.
3. create a catch-all route file at `src/api/[[...bknd]]/route.ts` which serves the bknd API.
This way, your application and the CLI are using the same configuration.

127
docs/extending/events.mdx Normal file
View File

@@ -0,0 +1,127 @@
---
title: Events & Hooks
---
bknd comes with a powerful built-in event system that allows you to hook into the app lifecycle and extend its functionality. You can hook into these events in two ways:
- `async`: Your listener is not blocking the main execution flow. E.g. on Cloudflare Workers, by default, the `ExecutionContext`'s `waitUntil` method is used so that the listeners runs after the response is sent.
- `sync`: Your listener is blocking the main execution flow. This allows to abort the request in your custom conditions. Some events also allow to return a modified event payload.
<Note>
Don't mistake `async` with JavaScript's `async` keyword. The `async` keyword is used to indicate that the listener is not blocking the main execution flow.
</Note>
## Overview
### Listening to events
You can listen to events by using the `EventManager` exposed at `app.emgr`. To register a listener, you can use either of these methods:
- `onEvent`: Register a listener for a specific event with a typed event.
- `on`: Register a listener for an event by its slug.
- `onAny`: Register a listener for all events.
```typescript
import { createApp, AppEvents } from "bknd";
const app = createApp();
app.emgr.onEvent(AppEvents.AppRequest, async (event) => {
// ^? AppRequest
console.log("Request received", event.request.url);
});
app.emgr.on("app-request", async (event) => {
console.log("Request received", event.request.url);
});
app.emgr.onAny(async (event) => {
console.log("Event received", event.slug);
});
```
You may want to register your listeners inside [`bknd.config.ts`](/extending/config) to make sure they are registered before the app is built:
```typescript bknd.config.ts
import { AppEvents } from "bknd";
export default {
onBuilt: (app) => {
app.emgr.onEvent(AppEvents.AppRequest, async (event) => {
console.log("Request received", event.request.url);
});
}
}
```
### Setting a mode
By default, listeners are registered as `async` listeners, meaning that the listener is not blocking the main execution flow. You can change this by passing the mode as the third argument:
```typescript
app.emgr.onEvent(AppEvents.AppRequest, async (event) => {
console.log("Request received", event.request.url);
}, { mode: "sync" });
```
This works for all three methods.
## App Events
These events are emitted by the `App` class and are available on the `AppEvents` object.
```typescript
import { AppEvents } from "bknd";
```
Available events:
| Event | Params | Description |
|:------|:--------|:------------|
| `AppConfigUpdatedEvent` | `{ app: App }` | Emitted when the app configuration is updated |
| `AppBuiltEvent` | `{ app: App }` | Emitted when the app is built |
| `AppFirstBoot` | `{ app: App }` | Emitted when the app is first booted |
| `AppRequest` | `{ app: App, request: Request }` | Emitted when a request is received |
| `AppBeforeResponse` | `{ app: App, request: Request, response: Response }` | Emitted before a response is sent |
## Database Events
These events are emitted by the `Database` class and are available on the `DatabaseEvents` object. These are divided by events triggered by the `Mutator` and `Repository` classes.
```typescript
import { DatabaseEvents } from "bknd/data";
```
### Mutator Events
These events are emitted during database mutations (insert, update, delete operations).
| Event | Params | Description |
|:------|:--------|:------------|
| `MutatorInsertBefore` | `{ entity: Entity, data: EntityData }` | Emitted before inserting a new record. Can modify the data. |
| `MutatorInsertAfter` | `{ entity: Entity, data: EntityData, changed: EntityData }` | Emitted after inserting a new record. |
| `MutatorUpdateBefore` | `{ entity: Entity, entityId: PrimaryFieldType, data: EntityData }` | Emitted before updating a record. Can modify the data. |
| `MutatorUpdateAfter` | `{ entity: Entity, entityId: PrimaryFieldType, data: EntityData, changed: EntityData }` | Emitted after updating a record. |
| `MutatorDeleteBefore` | `{ entity: Entity, entityId: PrimaryFieldType }` | Emitted before deleting a record. |
| `MutatorDeleteAfter` | `{ entity: Entity, entityId: PrimaryFieldType, data: EntityData }` | Emitted after deleting a record. |
### Repository Events
These events are emitted during database queries (find operations).
| Event | Params | Description |
|:------|:--------|:------------|
| `RepositoryFindOneBefore` | `{ entity: Entity, options: RepoQuery }` | Emitted before finding a single record. |
| `RepositoryFindOneAfter` | `{ entity: Entity, options: RepoQuery, data: EntityData }` | Emitted after finding a single record. |
| `RepositoryFindManyBefore` | `{ entity: Entity, options: RepoQuery }` | Emitted before finding multiple records. |
| `RepositoryFindManyAfter` | `{ entity: Entity, options: RepoQuery, data: EntityData }` | Emitted after finding multiple records. |
## Media Events
These events are emitted by the `Storage` class and are available on the `MediaEvents` object.
```typescript
import { MediaEvents } from "bknd/media";
```
| Event | Params | Description |
|:------|:--------|:------------|
| `FileUploadedEvent` | `{ file: FileBody } & FileUploadPayload` | Emitted when a file is successfully uploaded. Can modify the event data. |
| `FileDeletedEvent` | `{ name: string }` | Emitted when a file is deleted. |
| `FileAccessEvent` | `{ name: string }` | Emitted when a file is accessed. |
## Auth Events
Coming soon.