mirror of
https://github.com/shishantbiswas/bknd.git
synced 2026-03-16 12:37:20 +00:00
init: solid start adapter
This commit is contained in:
@@ -5,6 +5,7 @@
|
||||
"astro",
|
||||
"sveltekit",
|
||||
"tanstack-start",
|
||||
"vite"
|
||||
"vite",
|
||||
"solid-start"
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,335 @@
|
||||
---
|
||||
title: "Solid Start"
|
||||
description: "Run bknd inside Solid Start"
|
||||
tags: ["documentation"]
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
To get started with Solid Start and bknd you can either install the package manually, and follow the descriptions below, or use the CLI starter.
|
||||
|
||||
Create a new Solid Start project by following the [official guide](https://docs.solidjs.com/solid-start/getting-started), and then install bknd as a dependency:
|
||||
|
||||
<Tabs groupId='package-manager' persist items={[ 'npm', 'pnpm', 'yarn', 'bun']}>
|
||||
|
||||
```bash tab="npm"
|
||||
npm install bknd
|
||||
```
|
||||
|
||||
```bash tab="pnpm"
|
||||
pnpm install bknd
|
||||
```
|
||||
|
||||
```bash tab="yarn"
|
||||
yarn add bknd
|
||||
```
|
||||
|
||||
```bash tab="bun"
|
||||
bun add bknd
|
||||
```
|
||||
|
||||
</Tabs>
|
||||
|
||||
## Configuration
|
||||
|
||||
<Callout type="warning">
|
||||
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.
|
||||
</Callout>
|
||||
|
||||
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 title="bknd.config.ts"
|
||||
import type { SolidStartBkndConfig } from "bknd/adapter/solid-start";
|
||||
import { em, entity, text, boolean } from "bknd";
|
||||
import { secureRandomString } from "bknd/utils";
|
||||
|
||||
const schema = em({
|
||||
todos: entity("todos", {
|
||||
title: text(),
|
||||
done: boolean(),
|
||||
}),
|
||||
});
|
||||
|
||||
// register your schema to get automatic type completion
|
||||
type Database = (typeof schema)["DB"];
|
||||
declare module "bknd" {
|
||||
interface DB extends Database {}
|
||||
}
|
||||
|
||||
export default {
|
||||
connection: {
|
||||
url: "file:data.db",
|
||||
},
|
||||
options: {
|
||||
// the seed option is only executed if the database was empty
|
||||
seed: async (ctx) => {
|
||||
// create some entries
|
||||
await ctx.em.mutator("todos").insertMany([
|
||||
{ title: "Learn bknd", done: true },
|
||||
{ title: "Build something cool", done: false },
|
||||
]);
|
||||
|
||||
// and create a user
|
||||
await ctx.app.module.auth.createUser({
|
||||
email: "test@bknd.io",
|
||||
password: "12345678",
|
||||
});
|
||||
},
|
||||
},
|
||||
config: {
|
||||
data: schema.toJSON(),
|
||||
auth: {
|
||||
enabled: true,
|
||||
jwt: {
|
||||
secret: secureRandomString(32),
|
||||
},
|
||||
},
|
||||
},
|
||||
// please run `bun bknd copy-assets --out public/admin` to copy the admin assets into the public directory
|
||||
// alternatively add this as a postinstall script in your package.json like this:
|
||||
// "postinstall": "bknd copy-assets --out public/admin"
|
||||
adminOptions: {
|
||||
adminBasepath: "/admin",
|
||||
assetsPath: "/admin/", // trailing slash is important
|
||||
},
|
||||
} satisfies SolidStartBkndConfig;
|
||||
```
|
||||
|
||||
See [bknd.config.ts](/extending/config) for more information on how to configure bknd. The `SolidStartBkndConfig` type extends the `BkndConfig` type with the following additional properties:
|
||||
|
||||
```typescript
|
||||
export type SolidStartBkndConfig<Env = SolidStartEnv> = RuntimeBkndConfig<Env>;
|
||||
```
|
||||
|
||||
## Serve the API and Admin UI
|
||||
|
||||
The Solid Start adapter uses middleware to handle API requests and serve the Admin UI. Create a `src/middleware/index.ts` file:
|
||||
|
||||
```ts title="src/middleware/index.ts"
|
||||
import { createMiddleware } from "@solidjs/start/middleware";
|
||||
import config from "../../bknd.config";
|
||||
import { serve } from "bknd/adapter/solid-start";
|
||||
|
||||
const handler = serve(config);
|
||||
|
||||
export default createMiddleware({
|
||||
onRequest: async (event) => {
|
||||
const url = new URL(event.request.url);
|
||||
const pathname = url.pathname;
|
||||
|
||||
if (pathname.startsWith("/api") || pathname !== "/") {
|
||||
const res = await handler(event.request);
|
||||
|
||||
if (res && res.status !== 404) {
|
||||
return res;
|
||||
}
|
||||
}
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Update the app config (Solid Start v1 based on vinxi)
|
||||
|
||||
Add the following to your `app.config.ts` file:
|
||||
|
||||
```ts title="app.config.ts"
|
||||
import { defineConfig } from "@solidjs/start/config";
|
||||
|
||||
const app = defineConfig({
|
||||
// ... your existing config
|
||||
middleware: "src/middleware/index.ts",
|
||||
// ... your existing config
|
||||
});
|
||||
|
||||
export default app;
|
||||
```
|
||||
|
||||
### Update the vite config (Solid Start v2)
|
||||
|
||||
Add the following to your `vite.config.ts` file:
|
||||
|
||||
```ts title="vite.config.ts"
|
||||
import { defineConfig } from "vite";
|
||||
import solid from "vite-plugin-solid";
|
||||
import { solidStart } from "@solidjs/start/vite";
|
||||
|
||||
export default defineConfig({
|
||||
plugins: [
|
||||
solid(),
|
||||
solidStart({
|
||||
middleware: "./src/middleware/index.ts",
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
|
||||
<Callout type="success">
|
||||
You can visit https://localhost:3000/admin to see the admin UI. Additionally you can create more todos as you explore the admin UI.
|
||||
</Callout>
|
||||
|
||||
Create a helper file to instantiate the bknd instance and retrieve the API, importing the configuration from the `bknd.config.ts` file:
|
||||
|
||||
|
||||
```ts title="src/lib/bknd.ts"
|
||||
import { getApp as getBkndApp } from "bknd/adapter/solid-start";
|
||||
import bkndConfig from "../../bknd.config";
|
||||
import type { App } from "bknd";
|
||||
|
||||
export const getApp = async () => {
|
||||
return await getBkndApp(bkndConfig);
|
||||
};
|
||||
|
||||
export async function getApi({
|
||||
headers,
|
||||
verify,
|
||||
}: {
|
||||
verify?: boolean;
|
||||
headers?: Headers;
|
||||
}) {
|
||||
const app = await getApp();
|
||||
|
||||
if (verify) {
|
||||
const api = app.getApi({ headers });
|
||||
await api.verifyAuth();
|
||||
return api;
|
||||
}
|
||||
|
||||
return app.getApi();
|
||||
};
|
||||
```
|
||||
## Example usage of the API
|
||||
|
||||
You can use the `getApi` helper function we've already set up to fetch and mutate in static pages and server components:
|
||||
|
||||
```tsx title="src/routes/index.tsx"
|
||||
import { getApi } from "~/lib/bknd";
|
||||
import { query, createAsync } from "@solidjs/router";
|
||||
|
||||
export const getTodo = async () => {
|
||||
"use server"
|
||||
const api = await getApi({});
|
||||
const limit = 5;
|
||||
const todos = await api.data.readMany("todos");
|
||||
const total = todos.body.meta.total as number;
|
||||
return { total, todos: todos as unknown as Todo[], limit };
|
||||
};
|
||||
|
||||
const getTodosFromServer = query(async () => await getTodo(), "getTodosFromServer");
|
||||
|
||||
export default async function Home() {
|
||||
const api = await getApi();
|
||||
const data = createAsync(() => getTodosFromServer());
|
||||
|
||||
return (
|
||||
<ul>
|
||||
<For each={data()}>
|
||||
{(todo) => <li>{todo.title}</li>}
|
||||
</For>
|
||||
</ul>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Using authentication
|
||||
|
||||
When using authentication, you'll need to pass the headers to the `getApi` function to verify the user is authenticated.
|
||||
|
||||
```tsx title="src/routes/auth.tsx"
|
||||
import { createResource, Suspense } from "solid-js";
|
||||
import { A } from "@solidjs/router";
|
||||
import { getRequestEvent } from "solid-js/web";
|
||||
import { getApi } from "~/lib/bknd";
|
||||
|
||||
export const getUser = async () => {
|
||||
"use server"
|
||||
const request = getRequestEvent()?.request;
|
||||
const api = await getApi({ verify: true, headers: request?.headers });
|
||||
return api.getUser();
|
||||
}
|
||||
|
||||
export default function Home() {
|
||||
const [data] = createResource(async () => {
|
||||
const user = await getUser()
|
||||
return { user };
|
||||
}, {
|
||||
initialValue: {
|
||||
user: null
|
||||
}
|
||||
});
|
||||
|
||||
return (
|
||||
<div class="grid grid-rows-[20px_1fr_20px] items-center justify-items-center min-h-screen p-8 pb-20 gap-16 sm:p-20">
|
||||
<main class="flex flex-col gap-8 row-start-2 items-center sm:items-start">
|
||||
<div class="flex flex-row items-center ">
|
||||
<img
|
||||
class="dark:invert size-18"
|
||||
src="/solid.svg"
|
||||
alt="Solid logo"
|
||||
/>
|
||||
<div class="ml-3.5 mr-2 opacity-70">&</div>
|
||||
<img
|
||||
class="dark:invert"
|
||||
src="/bknd.svg"
|
||||
alt="bknd logo"
|
||||
width={183}
|
||||
height={59}
|
||||
/>
|
||||
</div>
|
||||
|
||||
<Suspense fallback={<p>Loading...</p>}>
|
||||
<div>
|
||||
{data()?.user ? (
|
||||
<>
|
||||
Logged in as {data()?.user?.email}.
|
||||
<A
|
||||
class="underline"
|
||||
target="_self"
|
||||
href={"/api/auth/logout"}
|
||||
>
|
||||
Logout
|
||||
</A>
|
||||
</>
|
||||
) : (
|
||||
<div class="flex flex-col gap-1">
|
||||
<p>
|
||||
Not logged in.
|
||||
<A
|
||||
class="underline"
|
||||
target="_self"
|
||||
href={"/admin/auth/login"}
|
||||
>
|
||||
Login
|
||||
</A>
|
||||
</p>
|
||||
<p class="text-xs opacity-50">
|
||||
Sign in with:
|
||||
<b>
|
||||
<code>test@bknd.io</code>
|
||||
</b>
|
||||
/
|
||||
<b>
|
||||
<code>12345678</code>
|
||||
</b>
|
||||
</p>
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
</Suspense>
|
||||
</main>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Tips
|
||||
|
||||
Use `target="_self"` on links, anytime your traversing to an external route (like `/api/auth/logout` which are handled by bknd's middleware) to prevent solid router from intercepting the link.
|
||||
```jsx
|
||||
<A href="/api/auth/logout" target="_self">
|
||||
Logout
|
||||
</A>
|
||||
```
|
||||
@@ -39,6 +39,12 @@ bknd seamlessly integrates with popular frameworks, allowing you to use what you
|
||||
href="/integration/tanstack-start"
|
||||
/>
|
||||
|
||||
<Card
|
||||
icon={<Icon icon="simple-icons:solid" className="text-fd-primary !size-6" />}
|
||||
title="Solid Start"
|
||||
href="/integration/solid-start"
|
||||
/>
|
||||
|
||||
<Card title="Yours missing?" href="https://github.com/bknd-io/bknd/issues/new">
|
||||
Create a new issue to request a guide for your framework.
|
||||
</Card>
|
||||
|
||||
@@ -156,6 +156,12 @@ Pick your framework or runtime to get started.
|
||||
href="/integration/tanstack-start"
|
||||
/>
|
||||
|
||||
<Card
|
||||
icon={<Icon icon="simple-icons:solid" className="text-fd-primary !size-6" />}
|
||||
title="Solid Start"
|
||||
href="/integration/solid-start"
|
||||
/>
|
||||
|
||||
<Card
|
||||
icon={<Icon icon="tabler:lambda" className="text-fd-primary !size-6" />}
|
||||
title="AWS Lambda"
|
||||
|
||||
Reference in New Issue
Block a user