From eaa72761731ff0d999a503133a0eef32f4f3adb3 Mon Sep 17 00:00:00 2001 From: dswbx Date: Wed, 19 Feb 2025 21:27:04 +0100 Subject: [PATCH] update docs on new cli starters --- docs/integration/astro.mdx | 60 +++++++++++++++++++------------ docs/integration/bun.mdx | 19 ++++++++-- docs/integration/cloudflare.mdx | 64 ++++++++++++++++++++------------- docs/integration/nextjs.mdx | 18 ++++++++-- docs/integration/node.mdx | 21 +++++++++-- docs/integration/remix.mdx | 19 ++++++++-- 6 files changed, 144 insertions(+), 57 deletions(-) diff --git a/docs/integration/astro.mdx b/docs/integration/astro.mdx index 690e090..ff69fbf 100644 --- a/docs/integration/astro.mdx +++ b/docs/integration/astro.mdx @@ -5,34 +5,48 @@ description: 'Run bknd inside Astro' import InstallBknd from '/snippets/install-bknd.mdx'; ## Installation -Install bknd as a dependency: - +To get started with Astro and bknd you can either install the package manually, and follow the descriptions below, or use the CLI starter: -The guide below assumes you're using Astro v4. We've experienced issues with Astro DB - using v5, see [this issue](https://github.com/withastro/astro/issues/12474). + + + Create a new Astro CLI starter project by running the following command: -For the Astro integration to work, you also need to [add the react integration](https://docs.astro.build/en/guides/integrations-guide/react/): -```bash -npx astro add react -``` + ```sh + npx bknd create -i astro + ``` + + + Create a new Astro project by following the [official guide](https://docs.astro.build/en/install-and-setup/), and then install bknd as a dependency: -You also need to make sure to set the output to `hybrid` in your Astro config: -```js {6} -// astro.config.mjs -import { defineConfig } from "astro/config"; -import react from "@astrojs/react"; + -export default defineConfig({ - output: "hybrid", - integrations: [react()] -}); -``` + The guide below assumes you're using Astro v4. We've experienced issues with Astro DB + using v5, see [this issue](https://github.com/withastro/astro/issues/12474). - - If you don't want to use React with Astro, there is also an option to serve the bknd Admin UI - statically using Astro's middleware. In case you're interested in this, feel free to reach - out in [Discord](https://discord.gg/952SFk8Tb8) or open an [issue on GitHub](https://github.com/bknd-io/bknd/issues/new). - + For the Astro integration to work, you also need to [add the react integration](https://docs.astro.build/en/guides/integrations-guide/react/): + ```bash + npx astro add react + ``` + + You also need to make sure to set the output to `hybrid` in your Astro config: + ```js {6} + // astro.config.mjs + import { defineConfig } from "astro/config"; + import react from "@astrojs/react"; + + export default defineConfig({ + output: "hybrid", + integrations: [react()] + }); + ``` + + + If you don't want to use React with Astro, there is also an option to serve the bknd Admin UI + statically using Astro's middleware. In case you're interested in this, feel free to reach + out in [Discord](https://discord.gg/952SFk8Tb8) or open an [issue on GitHub](https://github.com/bknd-io/bknd/issues/new). + + + ## Serve the API Create a new catch-all route at `src/pages/api/[...api].ts`: diff --git a/docs/integration/bun.mdx b/docs/integration/bun.mdx index a1fc991..ec79101 100644 --- a/docs/integration/bun.mdx +++ b/docs/integration/bun.mdx @@ -5,8 +5,23 @@ description: 'Run bknd inside Bun' import InstallBknd from '/snippets/install-bknd.mdx'; ## Installation -Install bknd as a dependency: - +To get started with Bun and bknd you can either install the package manually, and follow the descriptions below, or use the CLI starter: + + + + Create a new Bun CLI starter project by running the following command: + + ```sh + npx bknd create -i bun + ``` + + + Create a new Bun project and then install bknd as a dependency: + + + + + ## Serve the API & static files The `serve` function of the Bun adapter makes sure to also serve the static files required for diff --git a/docs/integration/cloudflare.mdx b/docs/integration/cloudflare.mdx index 9723708..d88575e 100644 --- a/docs/integration/cloudflare.mdx +++ b/docs/integration/cloudflare.mdx @@ -5,30 +5,51 @@ description: 'Run bknd inside Cloudflare Worker' import InstallBknd from '/snippets/install-bknd.mdx'; ## Installation -Create a new cloudflare worker project by following the -[official guide](https://developers.cloudflare.com/workers/get-started/guide/), -and then install bknd as a dependency: +To get started with Cloudflare Workers and bknd you can either install the package manually, and follow the descriptions below, or use the CLI starter: - + + + Create a new Cloudflare CLI starter project by running the following command: + + ```sh + npx bknd create -i cloudflare + ``` + + + Create a new cloudflare worker project by following the [official guide](https://developers.cloudflare.com/workers/get-started/guide/), and then install bknd as a dependency: + + + + ## Serve the API -If you don't choose anything specific, the following code will use the `warm` mode. See the +If you don't choose anything specific, the following code will use the `warm` mode and uses the first D1 binding it finds. See the chapter [Using a different mode](#using-a-different-mode) for available modes. ```ts src/index.ts -import { serve } from "bknd/adapter/cloudflare"; +import { serve, d1 } from "bknd/adapter/cloudflare"; +// scans your environment for the first D1 binding it finds +export default serve(); + +// manually specifying a D1 binding: export default serve({ - app: ({ env }) => ({ - connection: { - url: env.DB_URL, - authToken: env.DB_TOKEN - } - }) + app: ({ env }) => d1({ binding: env.D1_BINDING }) +}); + +// or specify binding using `bindings` +export default serve({ + bindings: ({ env }) => ({ db: env.D1_BINDING }) +}); + +// or use LibSQL +export default serve({ + app: ({ env }) => ({ url: env.DB_URL }) }); ``` -For more information about the connection object, refer to the [Database](/usage/database) guide. + +For more information about the connection object when using LibSQL, refer to the [Database](/usage/database) guide. Now run the worker: ```bash @@ -73,24 +94,17 @@ Now in order to also server the static admin files, you have to modify the `wran ## Adding custom routes You can also add custom routes by defining them after the app has been built, like so: -```ts {14-16} +```ts {5-7} import { serve } from "bknd/adapter/cloudflare"; -import manifest from "__STATIC_CONTENT_MANIFEST"; export default serve({ - app: ({ env }) => ({ - connection: { - url: env.DB_URL, - authToken: env.DB_TOKEN - } - }), + // ... onBuilt: async (app) => { - app.modules.server.get("/hello", (c) => c.json({ hello: "world" })); - }, - manifest, - setAdminHtml: true + app.server.get("/hello", (c) => c.json({ hello: "world" })); + } }); ``` +The property `app.server` is a [Hono](https://hono.dev/) instance, you can literally anything you can do with Hono. ## Using a different mode With the Cloudflare Workers adapter, you're being offered to 4 modes to choose from (default: diff --git a/docs/integration/nextjs.mdx b/docs/integration/nextjs.mdx index feb2cfc..2d4ed85 100644 --- a/docs/integration/nextjs.mdx +++ b/docs/integration/nextjs.mdx @@ -5,8 +5,22 @@ description: 'Run bknd inside Next.js' import InstallBknd from '/snippets/install-bknd.mdx'; ## Installation -Install bknd as a dependency: - +To get started with Next.js and bknd you can either install the package manually, and follow the descriptions below, or use the CLI starter: + + + + Create a new Next.js CLI starter project by running the following command: + + ```sh + npx bknd create -i nextjs + ``` + + + Create a new Next.js project by following the [official guide](https://nextjs.org/docs/pages/api-reference/cli/create-next-app), and then install bknd as a dependency: + + + + ## Serve the API ``` tsx diff --git a/docs/integration/node.mdx b/docs/integration/node.mdx index b023d4e..bf9803d 100644 --- a/docs/integration/node.mdx +++ b/docs/integration/node.mdx @@ -4,9 +4,24 @@ description: 'Run bknd inside Node' --- import InstallBknd from '/snippets/install-bknd.mdx'; + ## Installation -Install bknd as a dependency: - +To get started with Node and bknd you can either install the package manually, and follow the descriptions below, or use the CLI starter: + + + + Create a new Node CLI starter project by running the following command: + + ```sh + npx bknd create -i node + ``` + + + Create a new Node project and then install bknd as a dependency: + + + + ## Serve the API & static files The `serve` function of the Node adapter makes sure to also serve the static files required for @@ -20,7 +35,7 @@ import { serve } from "bknd/adapter/node"; /** @type {import("bknd/adapter/node").NodeAdapterOptions} */ const config = { connection: { - url: ":memory:" + url: "file:data.db" } }; diff --git a/docs/integration/remix.mdx b/docs/integration/remix.mdx index 3a4d015..ce823a1 100644 --- a/docs/integration/remix.mdx +++ b/docs/integration/remix.mdx @@ -5,8 +5,23 @@ description: 'Run bknd inside Remix' import InstallBknd from '/snippets/install-bknd.mdx'; ## Installation -Install bknd as a dependency: - +To get started with Remix and bknd you can either install the package manually, and follow the descriptions below, or use the CLI starter: + + + + Create a new Remix CLI starter project by running the following command: + + ```sh + npx bknd create -i remix + ``` + + + Create a new Remix project by following the [official guide](https://remix.run/docs/en/main/other-api/create-remix), and then install bknd as a dependency: + + + + + ## Serve the API Since Remix doesn't support middleware yet, we need a helper file to initialize the App to import from. Create a new file at `app/bknd.ts`: