feat: update documentation to reflect configuration changes and add progress callouts

Added callouts to various documentation modules indicating that the documentation is a work in progress. Updated references from `initialConfig` to `config` in multiple sections to align with recent changes in configuration handling.
This commit is contained in:
dswbx
2025-09-24 18:14:55 +02:00
parent 2c976adb77
commit a655c990ed
9 changed files with 52 additions and 36 deletions

View File

@@ -4,6 +4,12 @@ description: "Easily implement reliable authentication strategies."
tags: ["documentation"] tags: ["documentation"]
--- ---
<Callout type="info" title="The documentation is currently a work in progress">
Check back soon — or stay updated on our progress on
[GitHub](https://github.com/bknd-io/bknd) and join the conversation in
[Discord](https://discord.gg/952SFk8Tb8).
</Callout>
Authentication is essential for securing applications, and **bknd** provides a straightforward approach to implementing robust strategies. Authentication is essential for securing applications, and **bknd** provides a straightforward approach to implementing robust strategies.
### **Core Features** ### **Core Features**

View File

@@ -4,6 +4,12 @@ description: "Define, query, and control your data with ease."
tags: ["documentation"] tags: ["documentation"]
--- ---
<Callout type="info" title="The documentation is currently a work in progress">
Check back soon — or stay updated on our progress on
[GitHub](https://github.com/bknd-io/bknd) and join the conversation in
[Discord](https://discord.gg/952SFk8Tb8).
</Callout>
Data is the lifeblood of any application, and **bknd** provides the tools to handle it effortlessly. From defining entities to executing complex queries, bknd offers a developer-friendly, intuitive, and powerful data management experience. Data is the lifeblood of any application, and **bknd** provides the tools to handle it effortlessly. From defining entities to executing complex queries, bknd offers a developer-friendly, intuitive, and powerful data management experience.
### **Define Your Data** ### **Define Your Data**

View File

@@ -4,6 +4,12 @@ description: "Effortlessly manage and serve all your media files."
tags: ["documentation"] tags: ["documentation"]
--- ---
<Callout type="info" title="The documentation is currently a work in progress">
Check back soon — or stay updated on our progress on
[GitHub](https://github.com/bknd-io/bknd) and join the conversation in
[Discord](https://discord.gg/952SFk8Tb8).
</Callout>
**bknd** provides a flexible and efficient way to handle media files, making it easy to upload, manage, and deliver content across various platforms. **bknd** provides a flexible and efficient way to handle media files, making it easy to upload, manage, and deliver content across various platforms.
### **Core Features** ### **Core Features**
@@ -36,13 +42,13 @@ There are two ways to enable S3 or S3 compatible storage in bknd.
2. Enable programmatically. 2. Enable programmatically.
To enable using a code-first approach, create an [Initial Structure](/usage/database#initial-structure) using the `initialConfig` option in your `bknd.config.ts` file. To enable using a code-first approach, create corresponding configuration using the `config` option in your `bknd.config.ts` file.
```typescript title="bknd.config.ts" ```typescript title="bknd.config.ts"
import type { BkndConfig } from "bknd/adapter"; import type { BkndConfig } from "bknd/adapter";
export default { export default {
initialConfig: { config: {
media: { media: {
enabled: true, enabled: true,
adapter: { adapter: {
@@ -70,7 +76,7 @@ import type { BkndConfig } from "bknd/adapter";
const local = registerLocalMediaAdapter(); const local = registerLocalMediaAdapter();
export default { export default {
initialConfig: { config: {
media: { media: {
enabled: true, enabled: true,
adapter: local({ adapter: local({

View File

@@ -6,6 +6,12 @@ tags: ["documentation"]
import { Icon } from "@iconify/react"; import { Icon } from "@iconify/react";
<Callout type="info" title="The documentation is currently a work in progress">
Check back soon — or stay updated on our progress on
[GitHub](https://github.com/bknd-io/bknd) and join the conversation in
[Discord](https://discord.gg/952SFk8Tb8).
</Callout>
This backend system focuses on 4 essential building blocks which can be tightly connected: This backend system focuses on 4 essential building blocks which can be tightly connected:
Data, Auth, Media and Flows. Data, Auth, Media and Flows.
The main idea is to supply all baseline functionality required in order to accomplish complex The main idea is to supply all baseline functionality required in order to accomplish complex

View File

@@ -274,6 +274,7 @@ sync database
Options: Options:
-c, --config <config> config file -c, --config <config> config file
--db-url <db> database url, can be any valid sqlite url --db-url <db> database url, can be any valid sqlite url
--seed perform seeding operations
--force perform database syncing operations --force perform database syncing operations
--drop include destructive DDL operations --drop include destructive DDL operations
--out <file> output file --out <file> output file

View File

@@ -314,15 +314,11 @@ const connection = new CustomConnection();
const app = createApp({ connection }); const app = createApp({ connection });
``` ```
## Initial Structure ## Data Structure
To provide an initial database structure, you can pass `initialConfig` to the creation of an app. This will only be used if there isn't an existing configuration found in the database given. Here is a quick example: To provide a database structure, you can pass `config` to the creation of an app. In [`db` mode](/usage/introduction#ui-only-mode), the data structure is only respected if the database is empty. If you made updates, ensure to delete the database first, or perform updates through the Admin UI.
<Callout type="info"> Here is a quick example:
The initial structure is only respected if the database is empty! If you made
updates, ensure to delete the database first, or perform updates through the
Admin UI.
</Callout>
```typescript ```typescript
import { createApp, em, entity, text, number } from "bknd"; import { createApp, em, entity, text, number } from "bknd";
@@ -367,10 +363,7 @@ type Database = (typeof schema)["DB"];
// pass the schema to the app // pass the schema to the app
const app = createApp({ const app = createApp({
connection: { config: {
/* ... */
},
initialConfig: {
data: schema.toJSON(), data: schema.toJSON(),
}, },
}); });
@@ -473,7 +466,7 @@ const schema = em(
To get type completion, there are two options: To get type completion, there are two options:
1. Use the CLI to [generate the types](/usage/cli#generating-types-types) 1. Use the CLI to [generate the types](/usage/cli#generating-types-types) (recommended)
2. If you have an initial structure created with the prototype functions, you can extend the `DB` interface with your own schema. 2. If you have an initial structure created with the prototype functions, you can extend the `DB` interface with your own schema.
All entity related functions use the types defined in `DB` from `bknd`. To get type completion, you can extend that interface with your own schema: All entity related functions use the types defined in `DB` from `bknd`. To get type completion, you can extend that interface with your own schema:
@@ -482,18 +475,14 @@ All entity related functions use the types defined in `DB` from `bknd`. To get t
import { em } from "bknd"; import { em } from "bknd";
import { Api } from "bknd/client"; import { Api } from "bknd/client";
const schema = em({ const schema = em({ /* ... */ });
/* ... */
});
type Database = (typeof schema)["DB"]; type Database = (typeof schema)["DB"];
declare module "bknd" { declare module "bknd" {
interface DB extends Database {} interface DB extends Database {}
} }
const api = new Api({ const api = new Api({ /* ... */ });
/* ... */
});
const { data: posts } = await api.data.readMany("posts", {}); const { data: posts } = await api.data.readMany("posts", {});
// `posts` is now typed as Database["posts"] // `posts` is now typed as Database["posts"]
``` ```
@@ -505,21 +494,13 @@ The type completion is available for the API as well as all provided [React hook
To seed your database with initial data, you can pass a `seed` function to the configuration. It To seed your database with initial data, you can pass a `seed` function to the configuration. It
provides the `ModuleBuildContext` as the first argument. provides the `ModuleBuildContext` as the first argument.
<Callout type="info">
Note that the seed function will only be executed on app's first boot. If a
configuration already exists in the database, it will not be executed.
</Callout>
```typescript ```typescript
import { createApp, type ModuleBuildContext } from "bknd"; import { createApp, type ModuleBuildContext } from "bknd";
const app = createApp({ const app = createApp({
connection: { connection: { /* ... */ },
/* ... */ config: { /* ... */ },
},
initialConfig: {
/* ... */
},
options: { options: {
seed: async (ctx: ModuleBuildContext) => { seed: async (ctx: ModuleBuildContext) => {
await ctx.em.mutator("posts").insertMany([ await ctx.em.mutator("posts").insertMany([
@@ -530,3 +511,13 @@ const app = createApp({
}, },
}); });
``` ```
Note that in [`db` mode](/usage/introduction#ui-only-mode), the seed function will only be executed on app's first boot. If a configuration already exists in the database, it will not be executed.
In [`code` mode](/usage/introduction#code-only-mode), the seed function will not be automatically executed. You can manually execute it by running the following command:
```bash
npx bknd sync --seed --force
```
See the [sync command](/usage/cli#syncing-the-database-sync) documentation for more details.

View File

@@ -28,13 +28,13 @@ Once enabled, you can access the MCP UI at `/mcp`, or choose "MCP" from the top
## Enable MCP ## Enable MCP
If you're using `initialConfig`, you can enable the MCP server by setting the `server.mcp.enabled` property to `true`. If you're using a `config`, you can enable the MCP server by setting the `server.mcp.enabled` property to `true`.
```typescript ```typescript
import type { BkndConfig } from "bknd"; import type { BkndConfig } from "bknd";
export default { export default {
initialConfig: { config: {
server: { server: {
mcp: { mcp: {
enabled: true, enabled: true,

View File

@@ -9,7 +9,7 @@ const config = {
connection: { connection: {
url: "file:data.db", url: "file:data.db",
}, },
initialConfig: { config: {
media: { media: {
enabled: true, enabled: true,
adapter: { adapter: {

View File

@@ -87,7 +87,7 @@ async function setup(opts?: {
const app = App.create({ const app = App.create({
connection, connection,
// an initial config is only applied if the database is empty // an initial config is only applied if the database is empty
initialConfig: { config: {
data: schema.toJSON(), data: schema.toJSON(),
}, },
options: { options: {