From d541167fb3294fd4461ffedf91e0bf3a8a57c4d0 Mon Sep 17 00:00:00 2001 From: dswbx Date: Fri, 9 Jan 2026 13:26:28 +0100 Subject: [PATCH] docs: add sveltekit integration guide --- .../integration/(frameworks)/meta.json | 2 +- .../integration/(frameworks)/sveltekit.mdx | 204 ++++++++++++++++++ .../integration/introduction.mdx | 6 + docs/content/docs/(documentation)/start.mdx | 6 + 4 files changed, 217 insertions(+), 1 deletion(-) create mode 100644 docs/content/docs/(documentation)/integration/(frameworks)/sveltekit.mdx diff --git a/docs/content/docs/(documentation)/integration/(frameworks)/meta.json b/docs/content/docs/(documentation)/integration/(frameworks)/meta.json index 82151fc..6fb7bfc 100644 --- a/docs/content/docs/(documentation)/integration/(frameworks)/meta.json +++ b/docs/content/docs/(documentation)/integration/(frameworks)/meta.json @@ -1,3 +1,3 @@ { - "pages": ["nextjs", "react-router", "astro", "vite"] + "pages": ["nextjs", "react-router", "astro", "sveltekit", "vite"] } diff --git a/docs/content/docs/(documentation)/integration/(frameworks)/sveltekit.mdx b/docs/content/docs/(documentation)/integration/(frameworks)/sveltekit.mdx new file mode 100644 index 0000000..5ef07bf --- /dev/null +++ b/docs/content/docs/(documentation)/integration/(frameworks)/sveltekit.mdx @@ -0,0 +1,204 @@ +--- +title: "SvelteKit" +description: "Run bknd inside SvelteKit" +tags: ["documentation"] +--- + +## Installation + +To get started with SvelteKit and bknd, create a new SvelteKit project by following the [official guide](https://svelte.dev/docs/kit/creating-a-project), and then install bknd as a dependency: + + + +```bash tab="npm" +npm install bknd +``` + +```bash tab="pnpm" +pnpm install bknd +``` + +```bash tab="yarn" +yarn add bknd +``` + +```bash tab="bun" +bun add bknd +``` + + + +## Configuration + + + When run with Node.js, a version of 22 (LTS) or higher is required. Please + verify your version by running `node -v`, and + [upgrade](https://nodejs.org/en/download/) if necessary. + + +Now create a `bknd.config.ts` file in the root of your project: + +```typescript title="bknd.config.ts" +import type { SvelteKitBkndConfig } from "bknd/adapter/sveltekit"; + +export default { + connection: { + url: "file:data.db", + }, +} satisfies SvelteKitBkndConfig; +``` + +See [bknd.config.ts](/extending/config) for more information on how to configure bknd. The `SvelteKitBkndConfig` type extends the base config type with the following properties: + +```typescript +export type SvelteKitBkndConfig = Pick, "adminOptions">; +``` + +## Serve the API + +The SvelteKit adapter uses SvelteKit's hooks mechanism to handle API requests. Create a `src/hooks.server.ts` file: + +```typescript title="src/hooks.server.ts" +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); +}; +``` + +For more information about the connection object, refer to the [Database](/usage/database) guide. + + + The adapter uses `$env/dynamic/private` to access environment variables, making it runtime-agnostic + and compatible with any deployment target (Node.js, Bun, Cloudflare, etc.). + + +## Enabling the Admin UI + +The SvelteKit adapter supports serving the Admin UI statically. First, copy the required assets to your `static` folder by adding a postinstall script to your `package.json`: + +```json title="package.json" +{ + "scripts": { + "postinstall": "bknd copy-assets --out static" // [!code highlight] + } +} +``` + +Then update your `bknd.config.ts` to configure the admin base path: + +```typescript title="bknd.config.ts" +import type { SvelteKitBkndConfig } from "bknd/adapter/sveltekit"; + +export default { + connection: { + url: "file:data.db", + }, + adminOptions: { // [!code highlight] + adminBasepath: "/admin" // [!code highlight] + }, // [!code highlight] +} satisfies SvelteKitBkndConfig; +``` + +Finally, update your `hooks.server.ts` to also handle admin routes: + +```typescript title="src/hooks.server.ts" +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 and admin requests + const pathname = event.url.pathname; + if (pathname.startsWith("/api/") || pathname.startsWith("/admin")) { // [!code highlight] + const res = await bkndHandler(event); + if (res.status !== 404) { + return res; + } + } + + return resolve(event); +}; +``` + +## Example usage of the API + +You can use the `getApp` function to access the bknd API in your server-side load functions: + +```typescript title="src/routes/+page.server.ts" +import type { PageServerLoad } from "./$types"; +import { getApp } from "bknd/adapter/sveltekit"; +import { env } from "$env/dynamic/private"; +import config from "../../bknd.config"; + +export const load: PageServerLoad = async () => { + const app = await getApp(config, env); + const api = app.getApi(); + + const todos = await api.data.readMany("todos"); + + return { + todos: todos.data ?? [], + }; +}; +``` + +Then display the data in your Svelte component: + +```svelte title="src/routes/+page.svelte" + + +

Todos

+
    + {#each data.todos as todo (todo.id)} +
  • {todo.title}
    • + {/each} +
+``` + +### Using authentication + +To use authentication in your load functions, pass the request headers to the API: + +```typescript title="src/routes/+page.server.ts" +import type { PageServerLoad } from "./$types"; +import { getApp } from "bknd/adapter/sveltekit"; +import { env } from "$env/dynamic/private"; +import config from "../../bknd.config"; + +export const load: PageServerLoad = async ({ request }) => { + const app = await getApp(config, env); + const api = app.getApi({ headers: request.headers }); + await api.verifyAuth(); + + const todos = await api.data.readMany("todos"); + + return { + todos: todos.data ?? [], + user: api.getUser(), + }; +}; +``` + +Check the [SvelteKit repository example](https://github.com/bknd-io/bknd/tree/main/examples/sveltekit) for more implementation details. diff --git a/docs/content/docs/(documentation)/integration/introduction.mdx b/docs/content/docs/(documentation)/integration/introduction.mdx index 6330208..7119efd 100644 --- a/docs/content/docs/(documentation)/integration/introduction.mdx +++ b/docs/content/docs/(documentation)/integration/introduction.mdx @@ -27,6 +27,12 @@ bknd seamlessly integrates with popular frameworks, allowing you to use what you href="/integration/astro" /> +} + title="SvelteKit" + href="/integration/sveltekit" +/> + Create a new issue to request a guide for your framework. diff --git a/docs/content/docs/(documentation)/start.mdx b/docs/content/docs/(documentation)/start.mdx index 91bfdd7..86ca8ce 100644 --- a/docs/content/docs/(documentation)/start.mdx +++ b/docs/content/docs/(documentation)/start.mdx @@ -103,6 +103,12 @@ Start by using the integration guide for these popular frameworks/runtimes. Ther href="/integration/deno" /> +} + title="SvelteKit" + href="/integration/sveltekit" +/> + } title="AWS Lambda"