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

57
docs/integration/astro.mdx
View File

@@ -28,14 +28,14 @@ To get started with Astro and bknd you can either install the package manually,
npx astro add react
```
You also need to make sure to set the output to `hybrid` in your Astro config:
You also need to make sure to set the output to `server` in your Astro config:
```js {6}
// astro.config.mjs
import { defineConfig } from "astro/config";
import react from "@astrojs/react";
export default defineConfig({
output: "hybrid",
output: "server",
integrations: [react()]
});
```
@@ -48,8 +48,58 @@ To get started with Astro and bknd you can either install the package manually,
</Tab>
</Tabs>
## Configuration
Now create a `bknd.config.ts` file in the root of your project. If you created the project using the CLI starter, this file is already created for you.
```typescript bknd.config.ts
import type { AstroBkndConfig } from "bknd/adapter/astro";
export default {
connection: {
url: "file:data.db"
},
} satisfies AstroBkndConfig;
```
See [bknd.config.ts](/extending/config) for more information on how to configure bknd. The `AstroBkndConfig` type extends the `BkndConfig` type with the following additional properties:
```typescript
type AstroEnv = NodeJS.ProcessEnv;
export type AstroBkndConfig<Env = AstroEnv> = FrameworkBkndConfig<Env>;
```
## Serve the API
Create a new catch-all route at `src/pages/api/[...api].ts`:
Create a helper file to instantiate the bknd instance and retrieve the API, importing the configurationfrom the `bknd.config.ts` file:
```ts src/bknd.ts
import type { AstroGlobal } from "astro";
import { getApp as getBkndApp } from "bknd/adapter/astro";
import config from "../bknd.config";
export { config };
export async function getApp() {
return await getBkndApp(config);
}
export async function getApi(
astro: AstroGlobal,
opts?: { mode: "static" } | { mode?: "dynamic"; verify?: boolean },
) {
const app = await getApp();
if (opts?.mode !== "static" && opts?.verify) {
const api = app.getApi({ headers: astro.request.headers });
await api.verifyAuth();
return api;
}
return app.getApi();
}
```
Create a new catch-all route at `src/pages/api/[...api].ts`.
```ts src/pages/api/[...api].ts
import { serve } from "bknd/adapter/astro";
@@ -63,6 +113,7 @@ export const ALL = serve({
}
});
```
For more information about the connection object, refer to the [Database](/usage/database) guide. In the
special case of astro, you may also use your Astro DB credentials since it's also using LibSQL
under the hood. Refer to the [Astro DB documentation](https://docs.astro.build/en/guides/astro-db/) for more information.

35
docs/integration/nextjs.mdx
View File

@@ -22,21 +22,42 @@ To get started with Next.js and bknd you can either install the package manually
</Tab>
</Tabs>
## Configuration
Now create a `bknd.config.ts` file in the root of your project. If you created the project using the CLI starter, this file is already created for you.
```typescript bknd.config.ts
import type { NextjsBkndConfig } from "bknd/adapter/nextjs";
export default {
connection: {
url: "file:data.db"
},
} satisfies NextjsBkndConfig;
```
See [bknd.config.ts](/extending/config) for more information on how to configure bknd. 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[] };
};
```
## Serve the API
Create a helper file to instantiate the bknd instance and retrieve the API:
Create a helper file to instantiate the bknd instance and retrieve the API, importing the configurationfrom the `bknd.config.ts` file:
```ts src/bknd.ts
import { type NextjsBkndConfig, getApp as getBkndApp } from "bknd/adapter/nextjs";
import { headers } from "next/headers";
import config from "../bknd.config";
export const config = {
connection: {
url: "file:data.db"
},
} as const satisfies NextjsBkndConfig;
export { config };
export async function getApp() {
return await getBkndApp(config);
return await getBkndApp(config, process.env);
}
export async function getApi(opts?: { verify?: boolean }) {

41
docs/integration/react-router.mdx
View File

@@ -22,21 +22,44 @@ To get started with React Router and bknd you can either install the package man
</Tab>
</Tabs>
## Configuration
Now create a `bknd.config.ts` file in the root of your project. If you created the project using the CLI starter, this file is already created for you.
```typescript bknd.config.ts
import type { ReactRouterBkndConfig } from "bknd/adapter/react-router";
export default {
connection: {
url: "file:data.db"
},
} satisfies ReactRouterBkndConfig;
```
See [bknd.config.ts](/extending/config) for more information on how to configure bknd. The `ReactRouterBkndConfig` type extends the `BkndConfig` type with the following additional properties:
```typescript
type ReactRouterEnv = NodeJS.ProcessEnv;
type ReactRouterFunctionArgs = {
request: Request;
};
export type ReactRouterBkndConfig<Env = ReactRouterEnv> = FrameworkBkndConfig<Env>;
```
## Serve the API
Create a helper file to instantiate the bknd instance and retrieve the API:
Create a helper file to instantiate the bknd instance and retrieve the API, importing the configurationfrom the `bknd.config.ts` file:
```ts app/bknd.ts
import { type ReactRouterBkndConfig, getApp as getBkndApp } from "bknd/adapter/react-router";
import config from "../bknd.config";
const config = {
connection: {
url: "file:data.db"
}
} as const satisfies ReactRouterBkndConfig;
export { config };
export async function getApp(args?: { request: Request }) {
return await getBkndApp(config, args);
// you may adjust this function depending on your runtime environment.
// e.g. when deploying to cloudflare workers, you'd want the FunctionArgs to be passed in
// to resolve environment variables
export async function getApp() {
return await getBkndApp(config, process.env as any);
}
export async function getApi(
@@ -60,7 +83,7 @@ Create a new api splat route file at `app/routes/api.$.ts`:
import { getApp } from "~/bknd";
const handler = async (args: { request: Request }) => {
const app = await getApp(args);
const app = await getApp();
return app.fetch(args.request);
};

65
docs/integration/vite.mdx
View File

@@ -16,25 +16,42 @@ Additionally, install required dependencies:
npm install @hono/vite-dev-server
```
## Configuration
Now create a `bknd.config.ts` file in the root of your project.
```typescript bknd.config.ts
import type { ViteBkndConfig } from "bknd/adapter/vite";
export default {
connection: {
url: "file:data.db"
}
} satisfies ViteBkndConfig;
```
See [bknd.config.ts](/extending/config) for more information on how to configure bknd.
The `ViteBkndConfig` type extends the `BkndConfig` type with the following additional properties:
```typescript
export type ViteEnv = NodeJS.ProcessEnv;
export type ViteBkndConfig<Env = ViteEnv> = RuntimeBkndConfig<Env> & {};
```
## Serve the API
To serve the **bknd** API, you first have to create a local server file for you vite environment.
Create a `server.ts` file:
```ts
```typescript
import { serve } from "bknd/adapter/vite";
import config from "./bknd.config";
// the configuration given is optional
export default serve({
mode: "cached", // that's the default
connection: {
url: ":memory:"
}
})
export default serve(config)
```
For more information about the connection object, refer to the [Database](/usage/database) guide.
You can also run your vite server in `mode: "fresh"`, this will re-create the app on every fetch.
This is only useful for when working on the `bknd` repository directly.
For more information about the connection object, refer to the [Database](/usage/database) guide.
Next, adjust your `vite.config.ts` to look like the following:
```ts
import { devServer } from "bknd/adapter/vite";
@@ -82,17 +99,22 @@ options you can make use of to adjust it according to your setup.
There might be cases you want to be sure to be in control over the HTML that is being used.
`bknd` generates it automatically, but you use your own one as follows:
```ts server.ts
```typescript server.ts
import { serve, addViteScript } from "bknd/adapter/vite";
import { readFile } from "node:fs/promises"
import config from "./bknd.config";
let html = await readFile("./index.html", "utf-8");
// add vite scripts
html = addViteScript(html);
// then add it as an option
export default serve({ html })
export default serve({
...config,
adminOptions: {
html: addViteScript(html),
// optionally, you can change the base path for the admin UI
adminBasePath: "/admin"
}
})
```
The vite scripts has to be added manually currently, as adding them automatically with
@@ -101,13 +123,18 @@ The vite scripts has to be added manually currently, as adding them automaticall
### Use a custom entry point
By default, the entry point `/src/main.tsx` is used and should fit most cases. If that's not you,
you can supply a different one like so:
```ts server.ts
```typescript server.ts
import { serve } from "bknd/adapter/vite";
import config from "./bknd.config";
// the configuration given is optional
export default serve({
forceDev: {
mainPath: "/src/special.tsx"
}
...config,
adminOptions: {
forceDev: {
mainPath: "/src/special.tsx"
}
}
});
```