Merge pull request #58 from bknd-io/release/0.6.2

Release 0.6.2
release version 0.6.2
2026-08-02 16:16:02 +00:00 · 2025-01-25 09:40:44 +01:00 · 2025-01-25 09:40:15 +01:00 · 2025-01-25 09:17:39 +01:00 · 2025-01-25 09:17:23 +01:00 · 2025-01-25 09:14:02 +01:00
43 changed files with 957 additions and 292 deletions
@@ -1,13 +1,15 @@
-[![npm version](https://img.shields.io/npm/v/bknd.svg)](https://npmjs.org/package/bknd 
-"View this project on NPM")
+[![npm version](https://img.shields.io/npm/v/bknd.svg)](https://npmjs.org/package/bknd)
 [![npm downloads](https://img.shields.io/npm/dm/bknd)](https://www.npmjs.com/package/bknd)

 ![bknd](https://raw.githubusercontent.com/bknd-io/bknd/refs/heads/main/docs/_assets/poster.png)

-bknd simplifies app development by providing fully functional backend for data management, 
-authentication, workflows and media. Since it's lightweight and built on Web Standards, it can 
-be deployed nearly anywhere, including running inside your framework of choice. No more 
-deploying multiple separate services!
+<p align="center" width="100%">
+<a href="https://stackblitz.com/github/bknd-io/bknd-examples?hideExplorer=1&embed=1&view=preview&startScript=example-admin-rich&initialPath=%2Fdata%2Fschema">
+<strong>⭐ Live Demo</strong>
+</a>
+</p>
+
+bknd simplifies app development by providing a fully functional backend for database management, authentication, media and workflows. Being lightweight and built on Web Standards, it can be deployed nearly anywhere, including running inside your framework of choice. No more deploying multiple separate services!

 **For documentation and examples, please visit https://docs.bknd.io.**

@@ -15,33 +17,116 @@ deploying multiple separate services!
 > Please keep in mind that **bknd** is still under active development
 > and therefore full backward compatibility is not guaranteed before reaching v1.0.0.

-## ✨ Features
-**📊 Data**: Define, query, and control your data with ease. 
-  - Define entities with fields and relationships, synced directly to your database.  
-  - Supported field types: `primary`, `text`, `number`, `date`, `boolean`, `enum`, `json`, `jsonschema`.  
-  - Relationship types: `one-to-one`, `many-to-one`, `many-to-many`, and `polymorphic`.  
-  - Advanced querying with the **Repository**: filtering, sorting, pagination, and relational data handling.
-  - Seamlessly manage data with mutators and a robust event system.  
-  - Extend database functionality with batching, introspection, and support for multiple SQL dialects.
+## Size
+![gzipped size of bknd](https://img.badgesize.io/https://unpkg.com/bknd@0.6.1/dist/index.js?compression=gzip&label=bknd)
+![gzipped size of bknd/client](https://img.badgesize.io/https://unpkg.com/bknd@0.6.1/dist/ui/client/index.js?compression=gzip&label=bknd/client)
+![gzipped size of bknd/elements](https://img.badgesize.io/https://unpkg.com/bknd@0.6.1/dist/ui/elements/index.js?compression=gzip&label=bknd/elements)
+![gzipped size of bknd/ui](https://img.badgesize.io/https://unpkg.com/bknd@0.6.1/dist/ui/index.js?compression=gzip&label=bknd/ui)

-**🔐 Auth**: Easily implement reliable authentication strategies.
-  - Built-in `user` entity with customizable fields.  
-  - Supports multiple authentication strategies:  
-    - Email/password (with hashed storage).  
-    - OAuth/OIDC (Google, GitHub, and more).  
-  - Secure JWT generation and session management.
+The size on npm is misleading, as the `bknd` package includes the backend, the ui components as well as the whole backend bundled into the cli including static assets. 

-**🖼️ Media**: Effortlessly manage and serve all your media files.
-  - Upload files with ease.  
-  - Adapter-based support for S3, S3-compatible storage (e.g., R2, Tigris), and Cloudinary.
+## Motivation
+Creating digital products always requires developing both the backend (the logic) and the frontend (the appearance). Building a backend from scratch demands deep knowledge in areas such as authentication and database management. Using a backend framework can speed up initial development, but it still requires ongoing effort to work within its constraints (e.g., *"how to do X with Y?"*), which can quickly slow you down. Choosing a backend system is a tough decision, as you might not be aware of its limitations until you encounter them.

-**🔄 Flows** (UI integration coming soon!): Design and run workflows with seamless automation.
-  - Create and run workflows with trigger-based automation:  
-    - Manual triggers or events from data, auth, media, or server actions.  
-    - HTTP triggers for external integrations.  
-  - Define tasks in sequence, parallel, or loops, with conditional execution.  
-  - Use reusable sub-workflows to organize complex processes.  
-  - Leverage OpenAPI specifications for API-based tasks.
+**The solution:** A backend system that only assumes and implements primitive details, integrates into multiple environments, and adheres to industry standards.
+
+## Features
+* ⚡ Instant backend with full REST API:
+  * **Data**: Define, query, and control your data with ease.
+  * **Auth**: Easily implement reliable authentication strategies.
+  * **Media**: Effortlessly manage and serve all your media files.
+  * **Flows**: Design and run workflows with seamless automation. (UI integration coming soon!)
+* 🌐 Built on Web Standards for maximum compatibility
+* 🏃‍♂️ Multiple run modes
+  * standalone using the CLI
+  * using a JavaScript runtime (Node, Bun, workerd)
+  * using a React framework (Astro, Remix, Next.js)
+* 📦 Official API and React SDK with type-safety
+* ⚛️ React elements for auto-configured authentication and media components
+
+## Structure
+The package is mainly split into 4 parts, each serving a specific purpose:
+
+| Import                      | Purpose                                              |
+|-----------------------------|------------------------------------------------------|
+| `bknd`<br/>`bknd/adapter/*` | Backend including APIs and adapters                  |
+| `bknd/ui`                   | Admin UI components for react frameworks             |
+| `bknd/client`               | TypeScript SDK and React hooks for the API endpoints |
+| `bknd/elements`             | React components for authentication and media        |
+
+
+### The backend (`bknd`)
+Serve the backend as an API for any JS runtime or framework. The latter is especially handy, as it allows you to deploy your frontend and backend bundled together. Furthermore it allows adding additional logic in a way you're already familar with. Just add another route and you're good to go.
+
+Here is an example of serving the API using node:
+```js index.js
+import { serve } from "bknd/adapter/node"
+serve();
+```
+
+### Integrated admin UI (`bknd/ui`)
+The admin UI allows to manage your data including full configuration of your backend using a graphical user interface. Using `vite`, your admin route looks like this:
+```tsx
+import { Admin } from "bknd/ui"
+import "bknd/dist/styles.css";
+
+export default function AdminPage() {
+   return <Admin />
+}
+```
+
+### Using the REST API or TypeScript SDK (`bknd/client`)
+If you're not using a JavaScript environment, you can still access any endpoint using the REST API:
+```bash
+curl -XGET <your-endpoint>/api/data/<entity>
+{
+  "data": [
+    { "id": 1, ... },
+    { "id": 2, ... }
+  ],
+  "meta": { /* ... */ }
+}
+```
+
+In a JavaScript environment, you can use the TypeScript SDK with type-safety. The above example would look like this:
+```ts
+import { Api } from "bknd/client";
+
+const api = new Api({ host: "<endpoint>" });
+const { data } = await api.data.readMany("<entity>");
+```
+
+If you're using React, there are 2 hooks exposed (`useApi`, `useEntity`), as well as an `swr` wrapper around each (`useApiQuery`, `useEntityQuery`). The `swr` wrapped hooks automatically handled query invalidation:
+
+```tsx
+import { useState } from "react";
+import { useEntityQuery } from "bknd/client";
+
+export default function App() {
+   const { data } = useEntityQuery("todos");   
+   return <ul>
+      {data?.map(todo => (
+         <li key={todo.id}>{todo.name}</li>
+      ))}
+   </ul>
+}
+```
+
+### React elements (`bknd/elements`)
+You don't have to figure out API details to include media uploads to your app. For an user avatar upload, this is all you need:
+```tsx
+import { Media } from "bknd/elements"
+import "bknd/dist/main.css"
+
+export function UserAvatar() {
+   return <Media.Dropzone
+     entity={{ name: "users", id: 1, field: "avatar" }}
+     maxItems={1}
+     overwrite
+   />
+}
+```
+The import path also exports components for login and registration forms which are automatically pointed to the `bknd` defaults.


 ## 🚀 Quick start
@@ -2,6 +2,7 @@ import { beforeEach, describe, expect, it } from "bun:test";

 import { Hono } from "hono";
 import { Guard } from "../../src/auth";
+import { DebugLogger } from "../../src/core";
 import { EventManager } from "../../src/core/events";
 import { Default, stripMark } from "../../src/core/utils";
 import { EntityManager } from "../../src/data";
@@ -17,6 +18,7 @@ export function makeCtx(overrides?: Partial<ModuleBuildContext>): ModuleBuildCon
      emgr: new EventManager(),
      guard: new Guard(),
      flags: Module.ctx_flags,
+      logger: new DebugLogger(false),
      ...overrides
   };
 }
@@ -3,7 +3,7 @@
  "type": "module",
  "sideEffects": false,
  "bin": "./dist/cli/index.js",
-  "version": "0.6.1",
+  "version": "0.6.2",
  "description": "Lightweight Firebase/Supabase alternative built to run anywhere — incl. Next.js, Remix, Astro, Cloudflare, Bun, Node, AWS Lambda & more.",
  "homepage": "https://bknd.io",
  "repository": {
@@ -1,10 +1,10 @@
-import { cloneDeep, get, has, mergeWith, omit, set } from "lodash-es";
+import { get, has, omit, set } from "lodash-es";
 import {
   Default,
   type Static,
   type TObject,
   getFullPathKeys,
-   mark,
+   mergeObjectWith,
   parse,
   stripMark
 } from "../utils";
@@ -33,7 +33,7 @@ export class SchemaObject<Schema extends TObject> {
   ) {
      this._default = Default(_schema, {} as any) as any;
      this._value = initial
-         ? parse(_schema, cloneDeep(initial as any), {
+         ? parse(_schema, structuredClone(initial as any), {
              forceParse: this.isForceParse(),
              skipMark: this.isForceParse()
           })
@@ -64,8 +64,12 @@ export class SchemaObject<Schema extends TObject> {
      return this._config;
   }

+   clone() {
+      return structuredClone(this._config);
+   }
+
   async set(config: Static<Schema>, noEmit?: boolean): Promise<Static<Schema>> {
-      const valid = parse(this._schema, cloneDeep(config) as any, {
+      const valid = parse(this._schema, structuredClone(config) as any, {
         forceParse: true,
         skipMark: this.isForceParse()
      });
@@ -114,7 +118,7 @@ export class SchemaObject<Schema extends TObject> {
   }

   async patch(path: string, value: any): Promise<[Partial<Static<Schema>>, Static<Schema>]> {
-      const current = cloneDeep(this._config);
+      const current = this.clone();
      const partial = path.length > 0 ? (set({}, path, value) as Partial<Static<Schema>>) : value;

      this.throwIfRestricted(partial);
@@ -122,11 +126,13 @@ export class SchemaObject<Schema extends TObject> {

      // overwrite arrays and primitives, only deep merge objects
      // @ts-ignore
-      const config = mergeWith(current, partial, (objValue, srcValue) => {
+      //console.log("---alt:new", _jsonp(mergeObject(current, partial)));
+      const config = mergeObjectWith(current, partial, (objValue, srcValue) => {
         if (Array.isArray(objValue) && Array.isArray(srcValue)) {
            return srcValue;
         }
      });
+      //console.log("---new", _jsonp(config));

      //console.log("overwritePaths", this.options?.overwritePaths);
      if (this.options?.overwritePaths) {
@@ -164,14 +170,14 @@ export class SchemaObject<Schema extends TObject> {
         }
      }

-      //console.log("patch", { path, value, partial, config, current });
+      //console.log("patch", _jsonp({ path, value, partial, config, current }));

      const newConfig = await this.set(config);
      return [partial, newConfig];
   }

   async overwrite(path: string, value: any): Promise<[Partial<Static<Schema>>, Static<Schema>]> {
-      const current = cloneDeep(this._config);
+      const current = this.clone();
      const partial = path.length > 0 ? (set({}, path, value) as Partial<Static<Schema>>) : value;

      this.throwIfRestricted(partial);
@@ -192,7 +198,7 @@ export class SchemaObject<Schema extends TObject> {
      if (p.length > 1) {
         const parent = p.slice(0, -1).join(".");
         if (!has(this._config, parent)) {
-            console.log("parent", parent, JSON.stringify(this._config, null, 2));
+            //console.log("parent", parent, JSON.stringify(this._config, null, 2));
            throw new Error(`Parent path "${parent}" does not exist`);
         }
      }
@@ -207,7 +213,7 @@ export class SchemaObject<Schema extends TObject> {
         throw new Error(`Path "${path}" does not exist`);
      }

-      const current = cloneDeep(this._config);
+      const current = this.clone();
      const removed = get(current, path) as Partial<Static<Schema>>;
      const config = omit(current, path);
      const newConfig = await this.set(config);
@@ -4,6 +4,14 @@ export function _jsonp(obj: any, space = 2): string {
   return JSON.stringify(obj, null, space);
 }

+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+   return Object.prototype.toString.call(value) === "[object Object]";
+}
+
+export function isObject(value: unknown): value is Record<string, unknown> {
+   return value !== null && typeof value === "object";
+}
+
 export function safelyParseObjectValues<T extends { [key: string]: any }>(obj: T): T {
   return Object.entries(obj).reduce((acc, [key, value]) => {
      try {
@@ -97,15 +105,6 @@ export function objectEach<T extends Record<string, any>, U>(
   );
 }

-/**
- * Simple object check.
- * @param item
- * @returns {boolean}
- */
-export function isObject(item) {
-   return item && typeof item === "object" && !Array.isArray(item);
-}
-
 /**
 * Deep merge two objects.
 * @param target
@@ -197,3 +196,73 @@ export function objectCleanEmpty<Obj extends { [key: string]: any }>(obj: Obj):
      return acc;
   }, {} as any);
 }
+
+/**
+ * Lodash's merge implementation caused issues in Next.js environments
+ * From: https://thescottyjam.github.io/snap.js/#!/nolodash/merge
+ * NOTE: This mutates `object`. It also may mutate anything that gets attached to `object` during the merge.
+ * @param object
+ * @param sources
+ */
+export function mergeObject(object, ...sources) {
+   for (const source of sources) {
+      for (const [key, value] of Object.entries(source)) {
+         if (value === undefined) {
+            continue;
+         }
+
+         // These checks are a week attempt at mimicking the various edge-case behaviors
+         // that Lodash's `_.merge()` exhibits. Feel free to simplify and
+         // remove checks that you don't need.
+         if (!isPlainObject(value) && !Array.isArray(value)) {
+            object[key] = value;
+         } else if (Array.isArray(value) && !Array.isArray(object[key])) {
+            object[key] = value;
+         } else if (!isObject(object[key])) {
+            object[key] = value;
+         } else {
+            mergeObject(object[key], value);
+         }
+      }
+   }
+
+   return object;
+}
+
+/**
+ * Lodash's mergeWith implementation caused issues in Next.js environments
+ * From: https://thescottyjam.github.io/snap.js/#!/nolodash/mergeWith
+ * NOTE: This mutates `object`. It also may mutate anything that gets attached to `object` during the merge.
+ * @param object
+ * @param sources
+ * @param customizer
+ */
+export function mergeObjectWith(object, source, customizer) {
+   for (const [key, value] of Object.entries(source)) {
+      const mergedValue = customizer(object[key], value, key, object, source);
+      if (mergedValue !== undefined) {
+         object[key] = mergedValue;
+         continue;
+      }
+      // Otherwise, fall back to default behavior
+
+      if (value === undefined) {
+         continue;
+      }
+
+      // These checks are a week attempt at mimicking the various edge-case behaviors
+      // that Lodash's `_.merge()` exhibits. Feel free to simplify and
+      // remove checks that you don't need.
+      if (!isPlainObject(value) && !Array.isArray(value)) {
+         object[key] = value;
+      } else if (Array.isArray(value) && !Array.isArray(object[key])) {
+         object[key] = value;
+      } else if (!isObject(object[key])) {
+         object[key] = value;
+      } else {
+         mergeObjectWith(object[key], value, customizer);
+      }
+   }
+
+   return object;
+}
@@ -13,7 +13,15 @@ import { type AppDataConfig, dataConfigSchema } from "./data-schema";

 export class AppData extends Module<typeof dataConfigSchema> {
   override async build() {
-      const entities = transformObject(this.config.entities ?? {}, (entityConfig, name) => {
+      const {
+         entities: _entities = {},
+         relations: _relations = {},
+         indices: _indices = {}
+      } = this.config;
+
+      this.ctx.logger.context("AppData").log("building with entities", Object.keys(_entities));
+
+      const entities = transformObject(_entities, (entityConfig, name) => {
         return constructEntity(name, entityConfig);
      });

@@ -21,14 +29,14 @@ export class AppData extends Module<typeof dataConfigSchema> {
         const name = typeof _e === "string" ? _e : _e.name;
         const entity = entities[name];
         if (entity) return entity;
-         throw new Error(`Entity "${name}" not found`);
+         throw new Error(`[AppData] Entity "${name}" not found`);
      };

-      const relations = transformObject(this.config.relations ?? {}, (relation) =>
+      const relations = transformObject(_relations, (relation) =>
         constructRelation(relation, _entity)
      );

-      const indices = transformObject(this.config.indices ?? {}, (index, name) => {
+      const indices = transformObject(_indices, (index, name) => {
         const entity = _entity(index.entity)!;
         const fields = index.fields.map((f) => entity.field(f)!);
         return new EntityIndex(entity, fields, index.unique, name);
@@ -52,6 +60,7 @@ export class AppData extends Module<typeof dataConfigSchema> {
      );
      this.ctx.guard.registerPermissions(Object.values(DataPermissions));

+      this.ctx.logger.clear();
      this.setBuilt();
   }

@@ -14,3 +14,6 @@ export { registries } from "modules/registries";

 export type * from "./adapter";
 export { Api, type ApiOptions } from "./Api";
+
+export type { MediaFieldSchema } from "media/AppMedia";
+export type { UserFieldSchema } from "auth/AppAuth";
@@ -1,6 +1,6 @@
 import type { App } from "App";
 import type { Guard } from "auth";
-import { SchemaObject } from "core";
+import { type DebugLogger, SchemaObject } from "core";
 import type { EventManager } from "core/events";
 import type { Static, TSchema } from "core/utils";
 import {
@@ -35,6 +35,7 @@ export type ModuleBuildContext = {
   em: EntityManager;
   emgr: EventManager<any>;
   guard: Guard;
+   logger: DebugLogger;
   flags: (typeof Module)["ctx_flags"];
 };

@@ -231,7 +231,8 @@ export class ModuleManager {
         em: this.em,
         emgr: this.emgr,
         guard: this.guard,
-         flags: Module.ctx_flags
+         flags: Module.ctx_flags,
+         logger: this.logger
      };
   }

@@ -43,7 +43,11 @@ export function useBkndData() {
            return {
               config: async (partial: Partial<TAppDataEntity["config"]>): Promise<boolean> => {
                  console.log("patch config", entityName, partial);
-                  return await bkndActions.patch("data", `entities.${entityName}.config`, partial);
+                  return await bkndActions.overwrite(
+                     "data",
+                     `entities.${entityName}.config`,
+                     partial
+                  );
               },
               fields: entityFieldActions(bkndActions, entityName)
            };
@@ -16,6 +16,7 @@ export type JsonSchemaFormProps = any & {
   uiSchema?: any;
   direction?: "horizontal" | "vertical";
   onChange?: (value: any, isValid: () => boolean) => void;
+   cleanOnChange?: boolean;
 };

 export type JsonSchemaFormRef = {
@@ -36,6 +37,7 @@ export const JsonSchemaForm = forwardRef<JsonSchemaFormRef, JsonSchemaFormProps>
         templates,
         fields,
         widgets,
+         cleanOnChange,
         ...props
      },
      ref
@@ -51,8 +53,8 @@ export const JsonSchemaForm = forwardRef<JsonSchemaFormRef, JsonSchemaFormProps>
         return false;
      };
      const handleChange = ({ formData }: any, e) => {
-         const clean = JSON.parse(JSON.stringify(formData));
-         //console.log("Data changed: ", clean, JSON.stringify(formData, null, 2));
+         const clean = cleanOnChange !== false ? JSON.parse(JSON.stringify(formData)) : formData;
+         console.log("Data changed: ", clean, { cleanOnChange });
         setValue(clean);
         onChange?.(clean, () => isValid(clean));
      };
@@ -7,10 +7,23 @@ export type AuthScreenProps = {
   action?: "login" | "register";
   logo?: ReactNode;
   intro?: ReactNode;
+   formOnly?: boolean;
 };

-export function AuthScreen({ method = "POST", action = "login", logo, intro }: AuthScreenProps) {
+export function AuthScreen({
+   method = "POST",
+   action = "login",
+   logo,
+   intro,
+   formOnly
+}: AuthScreenProps) {
   const { strategies, basepath, loading } = useAuthStrategies();
+   const Form = <AuthForm auth={{ basepath, strategies }} method={method} action={action} />;
+
+   if (formOnly) {
+      if (loading) return null;
+      return Form;
+   }

   return (
      <div className="flex flex-1 flex-col select-none h-dvh w-dvw justify-center items-center bknd-admin">
@@ -25,7 +38,7 @@ export function AuthScreen({ method = "POST", action = "login", logo, intro }: A
                     <p className="text-primary/50">Enter your credentials below to get access.</p>
                  </div>
               )}
-               <AuthForm auth={{ basepath, strategies }} method={method} action={action} />
+               {Form}
            </div>
         )}
      </div>
@@ -1,3 +1,4 @@
+import { useAuthStrategies } from "../hooks/use-auth";
 import { AuthForm } from "./AuthForm";
 import { AuthScreen } from "./AuthScreen";
 import { SocialLink } from "./SocialLink";
@@ -7,3 +8,5 @@ export const Auth = {
   Form: AuthForm,
   SocialLink: SocialLink
 };
+
+export { useAuthStrategies };
@@ -1,2 +1,2 @@
-export { Auth } from "./auth";
+export * from "./auth";
 export * from "./media";
@@ -1,31 +1,32 @@
-import type { RepoQuery, RepoQueryIn } from "data";
+import type { RepoQueryIn } from "data";
 import type { MediaFieldSchema } from "media/AppMedia";
 import type { TAppMediaConfig } from "media/media-schema";
-import { useId } from "react";
-import { useApi, useBaseUrl, useEntityQuery, useInvalidate } from "ui/client";
+import { type ReactNode, createContext, useContext, useId } from "react";
+import { useApi, useEntityQuery, useInvalidate } from "ui/client";
 import { useEvent } from "ui/hooks/use-event";
 import { Dropzone, type DropzoneProps, type DropzoneRenderProps, type FileState } from "./Dropzone";
 import { mediaItemsToFileStates } from "./helper";

 export type DropzoneContainerProps = {
-   children?: (props: DropzoneRenderProps) => JSX.Element;
+   children?: ReactNode;
   initialItems?: MediaFieldSchema[];
   entity?: {
      name: string;
      id: number;
      field: string;
   };
+   media?: Pick<TAppMediaConfig, "entity_name" | "storage">;
   query?: RepoQueryIn;
-} & Partial<Pick<TAppMediaConfig, "basepath" | "entity_name" | "storage">> &
-   Partial<DropzoneProps>;
+} & Omit<Partial<DropzoneProps>, "children" | "initialItems">;
+
+const DropzoneContainerContext = createContext<DropzoneRenderProps>(undefined!);

 export function DropzoneContainer({
   initialItems,
-   basepath = "/api/media",
-   storage = {},
-   entity_name = "media",
+   media,
   entity,
   query,
+   children,
   ...props
 }: DropzoneContainerProps) {
   const id = useId();
@@ -33,10 +34,11 @@ export function DropzoneContainer({
   const baseUrl = api.baseUrl;
   const invalidate = useInvalidate();
   const limit = query?.limit ? query?.limit : props.maxItems ? props.maxItems : 50;
-   console.log("dropzone:baseUrl", baseUrl);
+   const entity_name = (media?.entity_name ?? "media") as "media";
+   //console.log("dropzone:baseUrl", baseUrl);

   const $q = useEntityQuery(
-      entity_name as "media",
+      entity_name,
      undefined,
      {
         ...query,
@@ -89,6 +91,18 @@ export function DropzoneContainer({
         autoUpload
         initialItems={_initialItems}
         {...props}
-      />
+      >
+         {children
+            ? (props) => (
+                 <DropzoneContainerContext.Provider value={props}>
+                    {children}
+                 </DropzoneContainerContext.Provider>
+              )
+            : undefined}
+      </Dropzone>
   );
 }
+
+export function useDropzone() {
+   return useContext(DropzoneContainerContext);
+}
@@ -1,11 +1,14 @@
 import { PreviewWrapperMemoized } from "./Dropzone";
-import { DropzoneContainer } from "./DropzoneContainer";
+import { DropzoneContainer, useDropzone } from "./DropzoneContainer";

 export const Media = {
   Dropzone: DropzoneContainer,
-   Preview: PreviewWrapperMemoized
+   Preview: PreviewWrapperMemoized,
+   useDropzone: useDropzone
 };

+export { useDropzone as useMediaDropzone };
+
 export type {
   PreviewComponentProps,
   FileState,
@@ -201,7 +201,7 @@ const EntityContextMenu = ({
            separator,
            {
               icon: IconSettings,
-               label: "Settings",
+               label: "Advanced",
               onClick: () =>
                  navigate(routes.settings.path(["data", "entities", entity.name]), {
                     absolute: true
@@ -40,8 +40,8 @@ export function DataEntityList({ params }) {
   useBrowserTitle(["Data", entity?.label ?? params.entity]);
   const [navigate] = useNavigate();
   const search = useSearch(searchSchema, {
-      select: undefined,
-      sort: undefined
+      select: entity.getSelect(undefined, "form"),
+      sort: entity.getDefaultSort()
   });

   const $q = useApiQuery(
@@ -1,4 +1,4 @@
-import { type DropzoneRenderProps, Media } from "ui/elements";
+import { Media } from "ui/elements";
 import { Scrollable } from "ui/layouts/AppShell/AppShell";

 export default function DropzoneElementTest() {
@@ -12,7 +12,7 @@ export default function DropzoneElementTest() {
                  maxItems={1}
                  overwrite
               >
-                  {(props) => <CustomUserAvatarDropzone {...props} />}
+                  <CustomUserAvatarDropzone />
               </Media.Dropzone>
            </div>

@@ -49,12 +49,13 @@ export default function DropzoneElementTest() {
   );
 }

-function CustomUserAvatarDropzone({
-   wrapperRef,
-   inputProps,
-   state: { files, isOver, isOverAccepted, showPlaceholder },
-   actions: { openFileInput }
-}: DropzoneRenderProps) {
+function CustomUserAvatarDropzone() {
+   const {
+      wrapperRef,
+      inputProps,
+      state: { files, isOver, isOverAccepted, showPlaceholder },
+      actions: { openFileInput }
+   } = Media.useDropzone();
   const file = files[0];

   return (
@@ -1,106 +0,0 @@
---
-title: 'Development'
-description: 'Preview changes locally to update your docs'
---
-
-<Info>
-  **Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.
-</Info>
-
-Follow these steps to install and run Mintlify on your operating system:
-
-**Step 1**: Install Mintlify:
-
-<CodeGroup>
-
-  ```bash npm
-  npm i -g mintlify
-  ```
-
-```bash yarn
-yarn global add mintlify
-```
-
-</CodeGroup>
-
-**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command:
-
-```bash
-mintlify dev
-```
-
-A local preview of your documentation will be available at `http://localhost:3000`.
-
-### Custom Ports
-
-By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. To run Mintlify on port 3333, for instance, use this command:
-
-```bash
-mintlify dev --port 3333
-```
-
-If you attempt to run Mintlify on a port that's already in use, it will use the next available port:
-
-```md
-Port 3000 is already in use. Trying 3001 instead.
-```
-
-## Mintlify Versions
-
-Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI:
-
-<CodeGroup>
-
-```bash npm
-npm i -g mintlify@latest
-```
-
-```bash yarn
-yarn global upgrade mintlify
-```
-
-</CodeGroup>
-
-## Validating Links
-
-The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
-
-```bash
-mintlify broken-links
-```
-
-## Deployment
-
-<Tip>
-  Unlimited editors available under the [Pro
-  Plan](https://mintlify.com/pricing) and above.
-</Tip>
-
-If the deployment is successful, you should see the following:
-
-<Frame>
-  <img src="/images/checks-passed.png" style={{ borderRadius: '0.5rem' }} />
-</Frame>
-
-## Code Formatting
-
-We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
-
-## Troubleshooting
-
-<AccordionGroup>
-  <Accordion title='Error: Could not load the "sharp" module using the darwin-arm64 runtime'>
-
-    This may be due to an outdated version of node. Try the following:
-    1. Remove the currently-installed version of mintlify: `npm remove -g mintlify`
-    2. Upgrade to Node v19 or higher.
-    3. Reinstall mintlify: `npm install -g mintlify`
-  </Accordion>
-
-  <Accordion title="Issue: Encountering an unknown error">
-  
-    Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again.
-  </Accordion>
-</AccordionGroup>
-
-Curious about what changed in the CLI version? [Check out the CLI changelog.](https://www.npmjs.com/package/mintlify?activeTab=versions)
@@ -52,7 +52,7 @@ export const ALL = serve({
   }
 });
 ```
-For more information about the connection object, refer to the [Setup](/setup/introduction) guide. In the
+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.

@@ -27,7 +27,7 @@ serve({
   }
 });
 ```
-For more information about the connection object, refer to the [Setup](/setup/introduction) guide.
+For more information about the connection object, refer to the [Database](/usage/database) guide.

 Run the application using Bun by executing:
 ```bash
@@ -31,7 +31,7 @@ export default serve({
   })
 });
 ```
-For more information about the connection object, refer to the [Setup](/setup/introduction) guide.
+For more information about the connection object, refer to the [Database](/usage/database) guide.

 Now run the worker:
 ```bash
@@ -0,0 +1,94 @@
+---
+title: 'Introduction'
+description: 'Integrate bknd into your runtime/framework of choice'
+---
+
+import { cloudflare, nextjs, remix, astro, bun, node, docker, vite } from "/snippets/integration-icons.mdx"
+
+## Start with a Framework
+bknd seamlessly integrates with popular frameworks, allowing you to use what you're already familar with. The following guides will help you get started with your framework of choice.
+
+<CardGroup cols={2}>
+  <Card
+    title="Next.js"
+    icon={<div className="text-primary-light">{nextjs}</div>}
+    href="/integration/nextjs"
+  />
+  <Card
+    title="Remix"
+    icon={<div className="text-primary-light">{remix}</div>}
+    href="/integration/remix"
+  />
+   <Card
+      title="Astro"
+      icon={<div className="text-primary-light">{astro}</div>}
+      href="/integration/astro"
+   />
+   <Card
+      horizontal
+      title="Yours missing?"
+      href="https://github.com/bknd-io/bknd/issues/new"
+   >
+     Create a new issue to request a guide for your framework.
+   </Card>
+</CardGroup>
+
+## Start with a Runtime
+If you prefer to use a runtime instead of a framework, you can choose from the following options. These runtimes allow you to serve the API and UI in the runtime's native server and serve the UI assets statically from `node_modules`.
+
+<CardGroup cols={2}>
+   <Card
+      title="Node"
+      icon={<div className="text-primary-light">{node}</div>}
+      href="/integration/node"
+   />
+   <Card
+      title="Bun"
+      icon={<div className="text-primary-light">{bun}</div>}
+      href="/integration/bun"
+   />
+   <Card
+      title="Cloudflare"
+      icon={<div className="text-primary-light">{cloudflare}</div>}
+      href="/integration/cloudflare"
+   />
+   <Card
+      title="Vite"
+      icon={<div className="text-primary-light">{vite}</div>}
+      href="/integration/vite"
+   />
+   <Card
+      title="Docker"
+      icon={<div className="text-primary-light">{docker}</div>}
+      href="/integration/docker"
+   />
+   <Card
+      horizontal
+      title="Yours missing?"
+      href="https://github.com/bknd-io/bknd/issues/new"
+   >
+     Create a new issue to request a guide for your runtime.
+   </Card>
+</CardGroup>
+
+## Overview
+
+### Serving the backend (API)
+Serve the backend as an API for any JS runtime or framework. The latter is especially handy, as it allows you to deploy your frontend and backend bundled together. Furthermore it allows adding additional logic in a way you're already familar with. Just add another route and you're good to go.
+
+Here is an example of serving the API using node:
+```js index.js
+import { serve } from "bknd/adapter/node"
+serve();
+```
+
+### Serving the Admin UI
+The admin UI allows to manage your data including full configuration of your backend using a graphical user interface. Using `vite`, your admin route looks like this:
+```tsx admin.tsx
+import { Admin } from "bknd/ui"
+import "bknd/dist/styles.css";
+
+export default function AdminPage() {
+   return <Admin withProvider />
+}
+```
@@ -28,7 +28,7 @@ export default serve({
   }
 });
 ```
-For more information about the connection object, refer to the [Setup](/setup/introduction) guide.
+For more information about the connection object, refer to the [Database](/usage/database) guide.

 ## Enabling the Admin UI
 Create a file `[[...admin]].tsx` inside the `pages/admin` folder:
@@ -29,7 +29,7 @@ const config = {

 serve(config);
 ```
-For more information about the connection object, refer to the [Setup](/setup/introduction) guide.
+For more information about the connection object, refer to the [Database](/usage/database) guide.

 Run the application using node by executing:
 ```bash
@@ -26,7 +26,7 @@ const handler = serve({
 export const loader = handler;
 export const action = handler;
 ```
-For more information about the connection object, refer to the [Setup](/setup/introduction) guide.
+For more information about the connection object, refer to the [Database](/usage/database) guide.

 Now make sure that you wrap your root layout with the `ClientProvider` so that all components
 share the same context:
@@ -33,7 +33,7 @@ export default serve({
   }
 })
 ```
-For more information about the connection object, refer to the [Setup](/setup/introduction) guide.
+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.
@@ -2,13 +2,26 @@
 title: Introduction
 ---

+import { cloudflare, nextjs, remix, astro, bun, node, docker, vite } from "/snippets/integration-icons.mdx"
+import { Stackblitz, examples } from "/snippets/stackblitz.mdx"
+
 Glad you're here! This is about **bknd**, a feature-rich backend that is so lightweight it could
 run on your toaster (probably).

 <Note>
-   The documentation is currently a work in progress and not complete. Updates will be made soon.
+   The documentation is currently a work in progress and not complete. Updates will be made regularily.
 </Note>

+## Preview
+**bknd** is so lightweight that it fully runs inside StackBlitz. Take a look at the preview below:
+<Stackblitz {...examples.adminRich} />
+
+<Accordion title="What's going on?" icon="lightbulb">
+   The example shown is starting a [node server](/integration/node) using an [in-memory database](/usage/database#sqlite-in-memory). To ensure there are a few entities defined, it is using an [initial structure](/usage/database#initial-structure) using the prototype methods. Furthermore it uses the [seed option](/usage/database#seeding-the-database) to seed some data in the structure created.
+
+   To ensure there are users defined on first boot, it hooks into the `App.Events.AppFirstBoot` event to create them (documentation pending).
+</Accordion>
+
 ## Quickstart
 Enter the following command to spin up an instance:
 <CodeGroup>
@@ -20,7 +33,8 @@ Enter the following command to spin up an instance:
   bunx bknd run
   ```
 </CodeGroup>
-To learn more about the CLI, check out the [Using the CLI](/cli) guide.
+
+To learn more about the CLI, check out the [Using the CLI](/usage/cli) guide.


 ## Start with a Framework/Runtime
@@ -30,73 +44,42 @@ in the future, so stay tuned!
 <CardGroup cols={2}>
  <Card
    title="Next.js"
-    icon={<div className="text-primary-light">
-       <svg xmlns="http://www.w3.org/2000/svg" width="28px" height="28px"
-          viewBox="0 0 24 24"><path fill="none" stroke="currentColor"
-          stroke-linecap="round" stroke-linejoin="round"
-       stroke-width="2" d="M9 15V9l7.745 10.65A9 9 0 1 1 19 17.657M15 12V9"/></svg></div>}
+    icon={<div className="text-primary-light">{nextjs}</div>}
    href="/integration/nextjs"
  />
  <Card
    title="Remix"
-    icon={<div className="text-primary-light">
-       <svg xmlns="http://www.w3.org/2000/svg"  width="24px" height="24px"
-          viewBox="0 0 24 24"><path fill="currentColor" fill-rule="evenodd" d="M19.932
-       17.424c.18 2.31.18 3.394.18 4.576h-5.35c0-.258.004-.493.009-.732c.014-.743.03-1.517-.09-3.081c-.16-2.29-1.147-2.799-2.961-2.799H3.305v-4.166h8.67c2.291 0 3.437-.696 3.437-2.54c0-1.623-1.146-2.605-3.437-2.605h-8.67V2h9.624c5.189 0 7.767 2.449 7.767 6.36c0 2.926-1.814 4.834-4.265 5.152c2.069.413 3.278 1.59 3.501 3.912" clip-rule="evenodd"/><path fill="currentColor" d="M3.305 22v-3.106h5.657c.945 0 1.15.7 1.15 1.118V22z"/></svg>
-    </div>}
+    icon={<div className="text-primary-light">{remix}</div>}
    href="/integration/remix"
  />
   <Card
      title="Astro"
-      icon={<div className="text-primary-light">
-         <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
-            <rect width="24" height="24" fill="none"/><path fill="currentColor" d="M9.24 19.035c-.901-.826-1.164-2.561-.789-3.819c.65.793 1.552 1.044 2.486 1.186c1.44.218 2.856.137 4.195-.524c.153-.076.295-.177.462-.278c.126.365.159.734.115 1.11c-.107.915-.56 1.622-1.283 2.158c-.289.215-.594.406-.892.608c-.916.622-1.164 1.35-.82 2.41l.034.114a2.4 2.4 0 0 1-1.07-.918a2.6 2.6 0 0 1-.412-1.401c-.003-.248-.003-.497-.036-.74c-.081-.595-.36-.86-.883-.876a1.034 1.034 0 0 0-1.075.843q-.013.058-.033.126M4.1 15.007s2.666-1.303 5.34-1.303l2.016-6.26c.075-.304.296-.51.544-.51c.25 0 .47.206.545.51l2.016 6.26c3.167 0 5.34 1.303 5.34 1.303L15.363 2.602c-.13-.366-.35-.602-.645-.602H9.283c-.296 0-.506.236-.645.602c-.01.024-4.538 12.405-4.538 12.405"/>
-         </svg>
-      </div>}
+      icon={<div className="text-primary-light">{astro}</div>}
      href="/integration/astro"
   />
+   <Card
+      title="Node"
+      icon={<div className="text-primary-light">{node}</div>}
+      href="/integration/node"
+   />
   <Card
      title="Cloudflare"
-      icon={<div className="text-primary-light">
-         <svg xmlns="http://www.w3.org/2000/svg" width="24px" height="24px" viewBox="0 0 128 128">
-            <path fill="currentColor" d="M30.743 116.257a15.5 15.5 0 0 1-3.42-4.107L4.068 71.752a15.56 15.56 0 0 1 0-15.503L27.323 15.85a15.5 15.5 0 0 1 3.417-4.084l15.601 28.166l-11.266 20.282a7.75 7.75 0 0 0 0 7.543l11.277 20.349zM100.665 15.85l23.255 40.398a15.49 15.49 0 0 1 0 15.503l-23.255 40.398a15.5 15.5 0 0 1-13.416 7.752H68.994l28.92-52.145a7.75 7.75 0 0 0 0-7.513L68.994 8.099h18.255a15.5 15.5 0 0 1 13.416 7.751M36.119 9.139a15.5 15.5 0 0 1 5.562-1.041h21.255l28.92 52.145a7.75 7.75 0 0 1 0 7.513l-28.92 52.145H41.682c-2.062 0-4.124-.423-5.993-1.193L63.406 67.29c.894-1.61 1.002-4.738.107-6.348z"/>
-         </svg>
-      </div>}
+      icon={<div className="text-primary-light">{cloudflare}</div>}
      href="/integration/cloudflare"
   />
   <Card
      title="Bun"
-      icon={<div className="text-primary-light">
-         <svg xmlns="http://www.w3.org/2000/svg" width="24px" height="24px" viewBox="0 0 24 24">
-            <path fill="currentColor" d="M12 22.596c6.628 0 12-4.338 12-9.688c0-3.318-2.057-6.248-5.219-7.986c-1.286-.715-2.297-1.357-3.139-1.89C14.058 2.025 13.08 1.404 12 1.404c-1.097 0-2.334.785-3.966 1.821a50 50 0 0 1-2.816 1.697C2.057 6.66 0 9.59 0 12.908c0 5.35 5.372 9.687 12 9.687zM10.599 4.715c.334-.759.503-1.58.498-2.409c0-.145.202-.187.23-.029c.658 2.783-.902 4.162-2.057 4.624c-.124.048-.199-.121-.103-.209a5.8 5.8 0 0 0 1.432-1.977m2.058-.102a5.8 5.8 0 0 0-.782-2.306v-.016c-.069-.123.086-.263.185-.172c1.962 2.111 1.307 4.067.556 5.051c-.082.103-.23-.003-.189-.126a5.85 5.85 0 0 0 .23-2.431m1.776-.561a5.7 5.7 0 0 0-1.612-1.806v-.014c-.112-.085-.024-.274.114-.218c2.595 1.087 2.774 3.18 2.459 4.407a.12.12 0 0 1-.049.071a.11.11 0 0 1-.153-.026a.12.12 0 0 1-.022-.083a5.9 5.9 0 0 0-.737-2.331m-5.087.561c-.617.546-1.282.76-2.063 1c-.117 0-.195-.078-.156-.181c1.752-.909 2.376-1.649 2.999-2.778c0 0 .155-.118.188.085c0 .304-.349 1.329-.968 1.874m4.945 11.237a2.96 2.96 0 0 1-.937 1.553c-.346.346-.8.565-1.286.62a2.18 2.18 0 0 1-1.327-.62a2.96 2.96 0 0 1-.925-1.553a.24.24 0 0 1 .064-.198a.23.23 0 0 1 .193-.069h3.965a.23.23 0 0 1 .19.07c.05.053.073.125.063.197m-5.458-2.176a1.86 1.86 0 0 1-2.384-.245a1.98 1.98 0 0 1-.233-2.447c.207-.319.503-.566.848-.713a1.84 1.84 0 0 1 1.092-.11c.366.075.703.261.967.531a1.98 1.98 0 0 1 .408 2.114a1.93 1.93 0 0 1-.698.869zm8.495.005a1.86 1.86 0 0 1-2.381-.253a1.96 1.96 0 0 1-.547-1.366c0-.384.11-.76.32-1.079c.207-.319.503-.567.849-.713a1.84 1.84 0 0 1 1.093-.108c.367.076.704.262.968.534a1.98 1.98 0 0 1 .4 2.117a1.93 1.93 0 0 1-.702.868"/>
-         </svg>
-      </div>}
+      icon={<div className="text-primary-light">{bun}</div>}
      href="/integration/bun"
   />
-   <Card
-      title="Node"
-      icon={<div className="text-primary-light">
-         <svg xmlns="http://www.w3.org/2000/svg" width={24} height={24} viewBox="0 0 24 24">
-            <path fill="currentColor" d="M12 23.956c-.342 0-.66-.089-.957-.243l-3.029-1.738c-.455-.242-.227-.33-.09-.374c.614-.198.728-.242 1.366-.595c.068-.044.16-.022.228.022l2.323 1.343c.09.044.205.044.273 0l9.087-5.084c.09-.044.136-.132.136-.242V6.899c0-.11-.045-.198-.136-.242l-9.087-5.061c-.091-.044-.205-.044-.273 0L2.754 6.657c-.091.044-.137.154-.137.242v10.146c0 .088.046.198.137.242l2.482 1.387c1.344.66 2.186-.11 2.186-.88V7.78c0-.132.114-.264.274-.264h1.161c.137 0 .273.11.273.264v10.013c0 1.739-.979 2.751-2.687 2.751c-.524 0-.934 0-2.095-.55l-2.391-1.32A1.85 1.85 0 0 1 1 17.067V6.921c0-.66.364-1.276.957-1.606L11.044.23a2.1 2.1 0 0 1 1.912 0l9.088 5.084c.592.33.956.946.956 1.606v10.146c0 .66-.364 1.276-.956 1.607l-9.087 5.083a2.4 2.4 0 0 1-.957.198m2.801-6.977c-3.985 0-4.805-1.76-4.805-3.257c0-.132.114-.264.273-.264h1.184c.137 0 .25.088.25.22c.183 1.166.707 1.738 3.121 1.738c1.913 0 2.733-.418 2.733-1.408c0-.572-.228-.99-3.211-1.276c-2.483-.243-4.031-.77-4.031-2.685c0-1.783 1.548-2.84 4.145-2.84c2.915 0 4.35.969 4.532 3.082a.35.35 0 0 1-.069.198c-.045.044-.113.088-.182.088h-1.184a.265.265 0 0 1-.25-.198c-.274-1.21-.98-1.607-2.847-1.607c-2.096 0-2.346.704-2.346 1.233c0 .638.296.836 3.12 1.188c2.801.352 4.122.858 4.122 2.75c-.023 1.938-1.662 3.038-4.555 3.038"></path>
-         </svg>
-      </div>}
-      href="/integration/node"
-   />
   <Card
      title="Vite"
-      icon={<div className="text-primary-light">
-         <svg xmlns="http://www.w3.org/2000/svg" width="28" height="28" viewBox="0 0 24 24">
-            <rect width="24" height="24" fill="none"/><path fill="currentColor" d="m8.525 4.63l-5.132-.915a1.17 1.17 0 0 0-1.164.468a1.16 1.16 0 0 0-.07 1.28l8.901 15.58a1.182 1.182 0 0 0 2.057-.008l8.729-15.578c.49-.875-.262-1.917-1.242-1.739l-4.574.813l-.206.754l4.906-.871a.474.474 0 0 1 .498.697L12.5 20.689a.47.47 0 0 1-.5.234a.47.47 0 0 1-.326-.231L2.772 5.112a.474.474 0 0 1 .496-.7l5.133.916l.074.013z"/><path fill="currentColor" d="m15.097 5.26l.162-.593l-.6.107zm-5.88-.506l.513.09l-.542.427z"/><path fill="currentColor" d="m15.549 2.367l-6.1 1.26a.22.22 0 0 0-.126.077a.25.25 0 0 0-.055.142l-.375 6.685a.24.24 0 0 0 .079.194a.21.21 0 0 0 .195.05l1.698-.414c.16-.038.302.11.27.278l-.505 2.606c-.034.176.122.326.285.274l1.049-.336c.162-.052.319.098.284.274l-.801 4.093c-.05.257.272.396.407.177l.09-.147l4.97-10.464c.084-.175-.06-.375-.242-.338l-1.748.356c-.165.034-.304-.128-.258-.297l1.14-4.173c.047-.17-.093-.331-.257-.297"/>
-         </svg>
-      </div>}
+      icon={<div className="text-primary-light">{vite}</div>}
      href="/integration/vite"
   />
   <Card
      title="Docker"
-      icon={<div className="text-primary-light">
-         <svg xmlns="http://www.w3.org/2000/svg" width={30} height={30} viewBox="0 0 24 24"><path
-            fill="currentColor" d="M21.81 10.25c-.06-.04-.56-.43-1.64-.43c-.28 0-.56.03-.84.08c-.21-1.4-1.38-2.11-1.43-2.14l-.29-.17l-.18.27c-.24.36-.43.77-.51 1.19c-.2.8-.08 1.56.33 2.21c-.49.28-1.29.35-1.46.35H2.62c-.34 0-.62.28-.62.63c0 1.15.18 2.3.58 3.38c.45 1.19 1.13 2.07 2 2.61c.98.6 2.59.94 4.42.94c.79 0 1.61-.07 2.42-.22c1.12-.2 2.2-.59 3.19-1.16A8.3 8.3 0 0 0 16.78 16c1.05-1.17 1.67-2.5 2.12-3.65h.19c1.14 0 1.85-.46 2.24-.85c.26-.24.45-.53.59-.87l.08-.24zm-17.96.99h1.76c.08 0 .16-.07.16-.16V9.5c0-.08-.07-.16-.16-.16H3.85c-.09 0-.16.07-.16.16v1.58c.01.09.07.16.16.16m2.43 0h1.76c.08 0 .16-.07.16-.16V9.5c0-.08-.07-.16-.16-.16H6.28c-.09 0-.16.07-.16.16v1.58c.01.09.07.16.16.16m2.47 0h1.75c.1 0 .17-.07.17-.16V9.5c0-.08-.06-.16-.17-.16H8.75c-.08 0-.15.07-.15.16v1.58c0 .09.06.16.15.16m2.44 0h1.77c.08 0 .15-.07.15-.16V9.5c0-.08-.06-.16-.15-.16h-1.77c-.08 0-.15.07-.15.16v1.58c0 .09.07.16.15.16M6.28 9h1.76c.08 0 .16-.09.16-.18V7.25c0-.09-.07-.16-.16-.16H6.28c-.09 0-.16.06-.16.16v1.57c.01.09.07.18.16.18m2.47 0h1.75c.1 0 .17-.09.17-.18V7.25c0-.09-.06-.16-.17-.16H8.75c-.08 0-.15.06-.15.16v1.57c0 .09.06.18.15.18m2.44 0h1.77c.08 0 .15-.09.15-.18V7.25c0-.09-.07-.16-.15-.16h-1.77c-.08 0-.15.06-.15.16v1.57c0 .09.07.18.15.18m0-2.28h1.77c.08 0 .15-.07.15-.16V5c0-.1-.07-.17-.15-.17h-1.77c-.08 0-.15.06-.15.17v1.56c0 .08.07.16.15.16m2.46 4.52h1.76c.09 0 .16-.07.16-.16V9.5c0-.08-.07-.16-.16-.16h-1.76c-.08 0-.15.07-.15.16v1.58c0 .09.07.16.15.16"></path></svg>
-      </div>}
+      icon={<div className="text-primary-light">{docker}</div>}
      href="/integration/docker"
   />
 </CardGroup>
@@ -61,11 +61,43 @@
  "navigation": [
    {
      "group": "Getting Started",
-      "pages": ["introduction", "sdk", "react", "cli"]
+      "pages": ["introduction", "motivation"]
    },
    {
-      "group": "Setup",
-      "pages": ["setup/introduction", "setup/database"]
+      "group": "Usage",
+      "pages": [
+        "usage/introduction",
+        "usage/database",
+        "usage/cli",
+        "usage/sdk",
+        "usage/react",
+        "usage/elements"
+      ]
+    },
+    {
+      "group": "Integration",
+      "pages": [
+        "integration/introduction",
+        {
+          "group": "Frameworks",
+          "pages": [
+            "integration/nextjs",
+            "integration/remix",
+            "integration/astro",
+            "integration/vite"
+          ]
+        },
+        {
+          "group": "Runtimes",
+          "pages": [
+            "integration/node",
+            "integration/bun",
+            "integration/cloudflare",
+            "integration/deno",
+            "integration/docker"
+          ]
+        }
+      ]
    },
    {
      "group": "Modules",
@@ -78,21 +110,6 @@
        "modules/flows"
      ]
    },
-    {
-      "group": "Integration",
-      "pages": [
-        "integration/extending",
-        "integration/nextjs",
-        "integration/remix",
-        "integration/cloudflare",
-        "integration/bun",
-        "integration/astro",
-        "integration/node",
-        "integration/deno",
-        "integration/vite",
-        "integration/docker"
-      ]
-    },
    {
      "group": "Deployment",
      "pages": [
@@ -0,0 +1,71 @@
+---
+title: "Motivation"
+description: "Why another backend system?"
+---
+
+Creating digital products always requires developing both the backend (the logic) and the frontend (the appearance). Building a backend from scratch demands deep knowledge in areas such as authentication and database management. Using a backend framework can speed up initial development, but it still requires ongoing effort to work within its constraints (e.g., *"how to do X with Y?"*), which can quickly slow you down. Choosing a backend system is a tough decision, as you might not be aware of its limitations until you encounter them.
+
+<Check>
+   **The solution:** A backend system that only assumes and implements primitive details, integrates into multiple environments, and adheres to industry standards.
+</Check>
+
+For the sake of brevity, let's assume you are looking for a "backend system" rather than dealing with custom implementations yourself. Let's identify the most common challenges:
+
+1. Database lock-in
+2. Environment and framework lock-in
+3. Deviation from standards (such as `X-Auth` headers for authentication)
+4. *Wrong-for-your-use-case* implementations
+5. Complex self-hosting
+
+## Database lock-in
+As the developer of a backend system, you must make tough decisions, one of which is choosing which database(s) to support. To simplify development, many systems lock you into a single database, leveraging its advanced features.
+
+But isn't the database known to be the hardest part to scale? Isn't more logic moving to the application layer? Haven't NoSQL databases proven this? If you're like me, you may have dipped your toes into the NoSQL world only to quickly return to SQL. SQL is known, predictable, and safe. But what if we could have both? NoSQL offers flexibility and scalability, yet querying it is tedious due to vendor-specific implementations.
+
+To get the best of both worlds, bknd focuses on the weakest SQL database (SQLite), treating it as a data store and query interface. Schema details and enforcement are moved to the application layer, making it easy to adjust a default value or property length. The added benefit is that any SQL database could theoretically work the same way, and since it's all TypeScript, the same validation logic can be used on both the client and server sides–you can validate your data before it even reaches your server. It even works without database-enforced referential integrity, as the integrity checks occur on the application layer. This opens the door to NewSQL systems like PlanetScale.
+
+## Environment and framework lock-in
+There are backend systems that embed themselves into a specific React framework. This works well until you realize it doesn't support your preferred framework or the new hyped one you're considering switching to. Just like database choices, decisions must be made. The easiest path is to select a single option and let people live with it.
+
+Alternatively, you could develop for the weakest environment (workerd) by strictly using Web APIs, avoiding shortcuts, and implementing certain logic manually because the go-to package is using Node APIs. This isn't always fun, but it's essential. The benefit? It works anywhere JavaScript does.
+
+bknd is the only backend system that not only works with any JavaScript framework but also integrates directly into it. It runs within the framework, enabling a single deployment for your entire app.
+
+*"But isn't it ironic that it forces a JavaScript environment?"* you might ask. And you're right, but it also allows running standalone via CLI or Docker.
+
+
+## Deviation from standards
+One of the biggest frustrations I've encountered is when software vendors choose custom headers for authentication or implement query parameters in a format they find more suitable—such as unencoded JSON for simplicity. When you are in full control, it's tempting to use a more suitable format, or just use an auth-ish name for the header property–after all, it's just a header, right?
+
+The issue is that users may rely on HTTP clients that offer built-in authentication methods, which won't include your custom solution. Custom `SearchParams` implementations might be convenient, but translating them across different environments and languages can be challenging without trial and error.
+
+bknd strives to adhere to web standards as much as possible while offering handy alternatives. Here's an example of the `select` search parameter for retrieving a list of entities:
+```bash
+/api/data/todos?select=id&select=name # web standard
+/api/data/todos?select=id,name # handy alternative
+```
+
+If you ever find an instance where bknd isn't adhering to standards or could be improved, please feel free to [file an issue](https://github.com/bknd-io/bknd/issues/new). Your feedback is greatly appreciated!
+
+
+## Wrong-for-your-use-case implementations
+If you've ever developed a social chat application, you likely discovered the extensive feature depth required—features we often take for granted. Things like socket connections for single and group chats, partial loading, asset attachments, and emoji reactions. Even more frustrating, these features make the app being considered incomplete until delivered.
+
+The same applies to backend systems. Features such as email sending, password resets, and image transformations are expected. Worse still, you'll receive feedback requesting different email verification methods—PIN codes instead of links, 4-digit codes versus 6-digit ones, or UUIDs like Axiom uses.
+
+Since it's impossible to satisfy all requirements, why implement them at all? *"Because people expect it."* That's fair. But technically, email verification is not a core backend feature—it's business logic. Setting it up involves:
+1. Adding a `code` and `verified` field to the users' entity and generating a random code on creation.
+2. Creating an endpoint to accept the code, retrieve the authenticated user, check the code, clear it, and mark the user as verified.
+
+Additional security measures, such as short-lived tokens, can be added, but the concept remains simple.
+
+Instead of hardcoding such features, bknd offers a powerful event system that supports asynchronous (like webhooks) and synchronous execution, blocking further actions if needed. With integrated workflows (UI coming soon), you can listen to and react to system events, and even map them to endpoints. Since workflows, like everything else in bknd, are JSON-serializable, they're easy to export and import.
+
+## Complex self-hosting
+Finally, hosting. It's a business advantage if your system is highly sought after but difficult to self-host, forcing users to opt for your cloud service. The truth is, if it's hard for users, it's also hard for the vendor, which drives up costs.
+
+If you know how to deploy your Next.js, Remix, or Astro application, you can deploy bknd. It's straightforward to deploy using Cloudflare Workers/Pages or with just 28 lines of a Dockerfile. No PhD required.
+
+
+
+
@@ -0,0 +1,31 @@
+export const nextjs = <svg xmlns="http://www.w3.org/2000/svg" width="28px" height="28px"
+   viewBox="0 0 24 24"><path fill="none" stroke="currentColor"
+   stroke-linecap="round" stroke-linejoin="round"
+stroke-width="2" d="M9 15V9l7.745 10.65A9 9 0 1 1 19 17.657M15 12V9"/></svg>
+
+export const remix = <svg xmlns="http://www.w3.org/2000/svg"  width="24px" height="24px"
+   viewBox="0 0 24 24"><path fill="currentColor" fill-rule="evenodd" d="M19.932
+17.424c.18 2.31.18 3.394.18 4.576h-5.35c0-.258.004-.493.009-.732c.014-.743.03-1.517-.09-3.081c-.16-2.29-1.147-2.799-2.961-2.799H3.305v-4.166h8.67c2.291 0 3.437-.696 3.437-2.54c0-1.623-1.146-2.605-3.437-2.605h-8.67V2h9.624c5.189 0 7.767 2.449 7.767 6.36c0 2.926-1.814 4.834-4.265 5.152c2.069.413 3.278 1.59 3.501 3.912" clip-rule="evenodd"/><path fill="currentColor" d="M3.305 22v-3.106h5.657c.945 0 1.15.7 1.15 1.118V22z"/></svg>;
+
+export const astro = <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+   <rect width="24" height="24" fill="none"/><path fill="currentColor" d="M9.24 19.035c-.901-.826-1.164-2.561-.789-3.819c.65.793 1.552 1.044 2.486 1.186c1.44.218 2.856.137 4.195-.524c.153-.076.295-.177.462-.278c.126.365.159.734.115 1.11c-.107.915-.56 1.622-1.283 2.158c-.289.215-.594.406-.892.608c-.916.622-1.164 1.35-.82 2.41l.034.114a2.4 2.4 0 0 1-1.07-.918a2.6 2.6 0 0 1-.412-1.401c-.003-.248-.003-.497-.036-.74c-.081-.595-.36-.86-.883-.876a1.034 1.034 0 0 0-1.075.843q-.013.058-.033.126M4.1 15.007s2.666-1.303 5.34-1.303l2.016-6.26c.075-.304.296-.51.544-.51c.25 0 .47.206.545.51l2.016 6.26c3.167 0 5.34 1.303 5.34 1.303L15.363 2.602c-.13-.366-.35-.602-.645-.602H9.283c-.296 0-.506.236-.645.602c-.01.024-4.538 12.405-4.538 12.405"/>
+</svg>
+
+export const cloudflare = <svg xmlns="http://www.w3.org/2000/svg" width="24px" height="24px" viewBox="0 0 128 128">
+   <path fill="currentColor" d="M30.743 116.257a15.5 15.5 0 0 1-3.42-4.107L4.068 71.752a15.56 15.56 0 0 1 0-15.503L27.323 15.85a15.5 15.5 0 0 1 3.417-4.084l15.601 28.166l-11.266 20.282a7.75 7.75 0 0 0 0 7.543l11.277 20.349zM100.665 15.85l23.255 40.398a15.49 15.49 0 0 1 0 15.503l-23.255 40.398a15.5 15.5 0 0 1-13.416 7.752H68.994l28.92-52.145a7.75 7.75 0 0 0 0-7.513L68.994 8.099h18.255a15.5 15.5 0 0 1 13.416 7.751M36.119 9.139a15.5 15.5 0 0 1 5.562-1.041h21.255l28.92 52.145a7.75 7.75 0 0 1 0 7.513l-28.92 52.145H41.682c-2.062 0-4.124-.423-5.993-1.193L63.406 67.29c.894-1.61 1.002-4.738.107-6.348z"/>
+</svg>
+
+export const bun = <svg xmlns="http://www.w3.org/2000/svg" width="24px" height="24px" viewBox="0 0 24 24">
+   <path fill="currentColor" d="M12 22.596c6.628 0 12-4.338 12-9.688c0-3.318-2.057-6.248-5.219-7.986c-1.286-.715-2.297-1.357-3.139-1.89C14.058 2.025 13.08 1.404 12 1.404c-1.097 0-2.334.785-3.966 1.821a50 50 0 0 1-2.816 1.697C2.057 6.66 0 9.59 0 12.908c0 5.35 5.372 9.687 12 9.687zM10.599 4.715c.334-.759.503-1.58.498-2.409c0-.145.202-.187.23-.029c.658 2.783-.902 4.162-2.057 4.624c-.124.048-.199-.121-.103-.209a5.8 5.8 0 0 0 1.432-1.977m2.058-.102a5.8 5.8 0 0 0-.782-2.306v-.016c-.069-.123.086-.263.185-.172c1.962 2.111 1.307 4.067.556 5.051c-.082.103-.23-.003-.189-.126a5.85 5.85 0 0 0 .23-2.431m1.776-.561a5.7 5.7 0 0 0-1.612-1.806v-.014c-.112-.085-.024-.274.114-.218c2.595 1.087 2.774 3.18 2.459 4.407a.12.12 0 0 1-.049.071a.11.11 0 0 1-.153-.026a.12.12 0 0 1-.022-.083a5.9 5.9 0 0 0-.737-2.331m-5.087.561c-.617.546-1.282.76-2.063 1c-.117 0-.195-.078-.156-.181c1.752-.909 2.376-1.649 2.999-2.778c0 0 .155-.118.188.085c0 .304-.349 1.329-.968 1.874m4.945 11.237a2.96 2.96 0 0 1-.937 1.553c-.346.346-.8.565-1.286.62a2.18 2.18 0 0 1-1.327-.62a2.96 2.96 0 0 1-.925-1.553a.24.24 0 0 1 .064-.198a.23.23 0 0 1 .193-.069h3.965a.23.23 0 0 1 .19.07c.05.053.073.125.063.197m-5.458-2.176a1.86 1.86 0 0 1-2.384-.245a1.98 1.98 0 0 1-.233-2.447c.207-.319.503-.566.848-.713a1.84 1.84 0 0 1 1.092-.11c.366.075.703.261.967.531a1.98 1.98 0 0 1 .408 2.114a1.93 1.93 0 0 1-.698.869zm8.495.005a1.86 1.86 0 0 1-2.381-.253a1.96 1.96 0 0 1-.547-1.366c0-.384.11-.76.32-1.079c.207-.319.503-.567.849-.713a1.84 1.84 0 0 1 1.093-.108c.367.076.704.262.968.534a1.98 1.98 0 0 1 .4 2.117a1.93 1.93 0 0 1-.702.868"/>
+</svg>
+
+export const node = <svg xmlns="http://www.w3.org/2000/svg" width={24} height={24} viewBox="0 0 24 24">
+   <path fill="currentColor" d="M12 23.956c-.342 0-.66-.089-.957-.243l-3.029-1.738c-.455-.242-.227-.33-.09-.374c.614-.198.728-.242 1.366-.595c.068-.044.16-.022.228.022l2.323 1.343c.09.044.205.044.273 0l9.087-5.084c.09-.044.136-.132.136-.242V6.899c0-.11-.045-.198-.136-.242l-9.087-5.061c-.091-.044-.205-.044-.273 0L2.754 6.657c-.091.044-.137.154-.137.242v10.146c0 .088.046.198.137.242l2.482 1.387c1.344.66 2.186-.11 2.186-.88V7.78c0-.132.114-.264.274-.264h1.161c.137 0 .273.11.273.264v10.013c0 1.739-.979 2.751-2.687 2.751c-.524 0-.934 0-2.095-.55l-2.391-1.32A1.85 1.85 0 0 1 1 17.067V6.921c0-.66.364-1.276.957-1.606L11.044.23a2.1 2.1 0 0 1 1.912 0l9.088 5.084c.592.33.956.946.956 1.606v10.146c0 .66-.364 1.276-.956 1.607l-9.087 5.083a2.4 2.4 0 0 1-.957.198m2.801-6.977c-3.985 0-4.805-1.76-4.805-3.257c0-.132.114-.264.273-.264h1.184c.137 0 .25.088.25.22c.183 1.166.707 1.738 3.121 1.738c1.913 0 2.733-.418 2.733-1.408c0-.572-.228-.99-3.211-1.276c-2.483-.243-4.031-.77-4.031-2.685c0-1.783 1.548-2.84 4.145-2.84c2.915 0 4.35.969 4.532 3.082a.35.35 0 0 1-.069.198c-.045.044-.113.088-.182.088h-1.184a.265.265 0 0 1-.25-.198c-.274-1.21-.98-1.607-2.847-1.607c-2.096 0-2.346.704-2.346 1.233c0 .638.296.836 3.12 1.188c2.801.352 4.122.858 4.122 2.75c-.023 1.938-1.662 3.038-4.555 3.038"></path>
+</svg>
+
+export const vite = <svg xmlns="http://www.w3.org/2000/svg" width="28" height="28" viewBox="0 0 24 24">
+   <rect width="24" height="24" fill="none"/><path fill="currentColor" d="m8.525 4.63l-5.132-.915a1.17 1.17 0 0 0-1.164.468a1.16 1.16 0 0 0-.07 1.28l8.901 15.58a1.182 1.182 0 0 0 2.057-.008l8.729-15.578c.49-.875-.262-1.917-1.242-1.739l-4.574.813l-.206.754l4.906-.871a.474.474 0 0 1 .498.697L12.5 20.689a.47.47 0 0 1-.5.234a.47.47 0 0 1-.326-.231L2.772 5.112a.474.474 0 0 1 .496-.7l5.133.916l.074.013z"/><path fill="currentColor" d="m15.097 5.26l.162-.593l-.6.107zm-5.88-.506l.513.09l-.542.427z"/><path fill="currentColor" d="m15.549 2.367l-6.1 1.26a.22.22 0 0 0-.126.077a.25.25 0 0 0-.055.142l-.375 6.685a.24.24 0 0 0 .079.194a.21.21 0 0 0 .195.05l1.698-.414c.16-.038.302.11.27.278l-.505 2.606c-.034.176.122.326.285.274l1.049-.336c.162-.052.319.098.284.274l-.801 4.093c-.05.257.272.396.407.177l.09-.147l4.97-10.464c.084-.175-.06-.375-.242-.338l-1.748.356c-.165.034-.304-.128-.258-.297l1.14-4.173c.047-.17-.093-.331-.257-.297"/>
+</svg>
+
+export const docker = <svg xmlns="http://www.w3.org/2000/svg" width={30} height={30} viewBox="0 0 24 24"><path
+   fill="currentColor" d="M21.81 10.25c-.06-.04-.56-.43-1.64-.43c-.28 0-.56.03-.84.08c-.21-1.4-1.38-2.11-1.43-2.14l-.29-.17l-.18.27c-.24.36-.43.77-.51 1.19c-.2.8-.08 1.56.33 2.21c-.49.28-1.29.35-1.46.35H2.62c-.34 0-.62.28-.62.63c0 1.15.18 2.3.58 3.38c.45 1.19 1.13 2.07 2 2.61c.98.6 2.59.94 4.42.94c.79 0 1.61-.07 2.42-.22c1.12-.2 2.2-.59 3.19-1.16A8.3 8.3 0 0 0 16.78 16c1.05-1.17 1.67-2.5 2.12-3.65h.19c1.14 0 1.85-.46 2.24-.85c.26-.24.45-.53.59-.87l.08-.24zm-17.96.99h1.76c.08 0 .16-.07.16-.16V9.5c0-.08-.07-.16-.16-.16H3.85c-.09 0-.16.07-.16.16v1.58c.01.09.07.16.16.16m2.43 0h1.76c.08 0 .16-.07.16-.16V9.5c0-.08-.07-.16-.16-.16H6.28c-.09 0-.16.07-.16.16v1.58c.01.09.07.16.16.16m2.47 0h1.75c.1 0 .17-.07.17-.16V9.5c0-.08-.06-.16-.17-.16H8.75c-.08 0-.15.07-.15.16v1.58c0 .09.06.16.15.16m2.44 0h1.77c.08 0 .15-.07.15-.16V9.5c0-.08-.06-.16-.15-.16h-1.77c-.08 0-.15.07-.15.16v1.58c0 .09.07.16.15.16M6.28 9h1.76c.08 0 .16-.09.16-.18V7.25c0-.09-.07-.16-.16-.16H6.28c-.09 0-.16.06-.16.16v1.57c.01.09.07.18.16.18m2.47 0h1.75c.1 0 .17-.09.17-.18V7.25c0-.09-.06-.16-.17-.16H8.75c-.08 0-.15.06-.15.16v1.57c0 .09.06.18.15.18m2.44 0h1.77c.08 0 .15-.09.15-.18V7.25c0-.09-.07-.16-.15-.16h-1.77c-.08 0-.15.06-.15.16v1.57c0 .09.07.18.15.18m0-2.28h1.77c.08 0 .15-.07.15-.16V5c0-.1-.07-.17-.15-.17h-1.77c-.08 0-.15.06-.15.17v1.56c0 .08.07.16.15.16m2.46 4.52h1.76c.09 0 .16-.07.16-.16V9.5c0-.08-.07-.16-.16-.16h-1.76c-.08 0-.15.07-.15.16v1.58c0 .09.07.16.15.16"></path></svg>
@@ -0,0 +1,45 @@
+export const examples = {
+   adminRich: {
+      path: "github/bknd-io/bknd-examples",
+      startScript: "example-admin-rich",
+      initialPath: "/data/schema"
+   }
+}
+
+export const Stackblitz = ({
+   path = "github/bknd-io/bknd-examples",
+   ratio = 9/16,
+   ...props
+}) => {
+   const params = new URLSearchParams({
+      ctl: 1,
+      hideExplorer: 1,
+      embed: 1,
+      view: "preview",
+      ...props
+   })
+   const url = new URL(`https://stackblitz.com/${path}?${params.toString()}`)
+
+   return (
+      <>
+         <div style={{
+            position: "relative",
+            overflow: "hidden",
+            width: '100%',
+            paddingTop: `${ratio*100}%`
+         }}>
+            <iframe width="100%" height="100%" src={url.toString()}
+               style={{
+                  position: "absolute",
+                  top: 0,
+                  left: 0,
+                  bottom: 0,
+                  right: 0,
+                  border: "none"
+               }}
+            ></iframe>
+         </div>
+         <div style={{ fontSize: "80%", opacity: 0.7, marginTop: "0.2rem", marginBottom: "1rem", textAlign: "center" }}>If you're having issues viewing it inline, <a href={url.toString()} target="_blank">try in a new tab</a>.</div>
+      </>
+   )
+}
@@ -12,9 +12,21 @@ the dependencies.
 </Note>

 ## Database
+### SQLite in-memory
+The easiest to get started is using SQLite in-memory. When serving the API in the "Integrations",
+the function accepts an object with connection details. To use an in-memory database, you can either omit the object completely or explicitly use it as follows:
+```json
+{
+   "type": "libsql",
+   "config": {
+      "url": ":memory:"
+   }
+}
+```
+
 ### SQLite as file
-The easiest to get started is using SQLite as a file. When serving the API in the "Integrations",
-the function accepts an object with connection details. To use a file, use the following:
+Just like the in-memory option, using a file is just as easy:
+
 ```json
 {
   "type": "libsql",
@@ -156,11 +168,11 @@ const { data: posts } = await api.data.readMany("posts", {})
 // `posts` is now typed as Database["posts"]
 ```

-The type completion is available for the API as well as all provided [React hooks](/react).
+The type completion is available for the API as well as all provided [React hooks](/usage/react).

 ### Seeding the database
 To seed your database with initial data, you can pass a `seed` function to the configuration. It
-provides the `ModuleBuildContext` ([reference](/setup/introduction#modulebuildcontext)) as the first argument.
+provides the `ModuleBuildContext` ([reference](/usage/introduction#modulebuildcontext)) as the first argument.

 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.
@@ -0,0 +1,136 @@
+---
+title: "React Elements"
+description: "Speed up your frontend development"
+---
+
+Not only creating and maintaing a backend is time-consuming, but also integrating it into your frontend can be a hassle. With `bknd/elements`, you can easily add media uploads and authentication forms to your app without having to figure out API details.
+
+<Note>
+   In order to use these exported elements, make sure to wrap your app inside `ClientProvider`. See the [React Setup](/usage/react#setup) for more information.
+</Note>
+
+# Media
+
+## Media.Dropzone
+The `Media.Dropzone` element allows retrieving from and uploading media items to your bknd instance. Without any properties specified, it will behave similar to your media library inside the bknd Admin UI. Here is how to get the last 10 items:
+
+```tsx
+import { Media } from "bknd/elements"
+
+export default function MediaGallery() {
+   return <Media.Dropzone query={{ limit: 10, sort: "-id" }} />
+}
+```
+
+Since you can also upload media to a specific entity, you can also point that `Dropzone` to it. Here is an example of a single user avatar that gets overwritten on re-upload:
+
+```tsx
+import { Media } from "bknd/elements";
+
+export default function UserAvatar() {
+   return <Media.Dropzone
+      entity={{ name: "users", id: 1, field: "avatar" }}
+      maxItems={1}
+      overwrite
+   />
+}
+```
+
+### Props
+- `initialItems?: xMediaFieldSchema[]`: Initial items to display, must be an array of media objects.
+- `entity?: { name: string; id: number; field: string }`: If given, the initial media items fetched will be from this entity.
+- `query?: RepoQueryIn`: Query to filter the media items.
+- `overwrite?: boolean`: If true, the media item will be overwritten on entity media uploads if limit was reached.
+- `maxItems?: number`: Maximum number of media items that can be uploaded.
+- `autoUpload?: boolean`: If true, the media items will be uploaded automatically.
+- `onRejected?: (files: FileWithPath[]) => void`: Callback when a file is rejected.
+- `onDeleted?: (file: FileState) => void`: Callback when a file is deleted.
+- `onUploaded?: (file: FileState) => void`: Callback when a file is uploaded.
+- `placeholder?: { show?: boolean; text?: string }`: Placeholder text to show when no media items are present.
+
+### Customize Rendering
+You can also customize the rendering of the media items and its uploading by passing a react element as a child. Here is an example of a custom `Media.Dropzone` that renders an user avatar (styled using tailwind):
+
+```tsx
+import { Media, useMediaDropzone } from "bknd/elements";
+
+export default function CustomUserAvatar() {
+   return <Media.Dropzone
+      entity={{ name: "users", id: 1, field: "avatar" }}
+      maxItems={1}
+      overwrite
+   >
+      <CustomUserAvatar />
+   </Media.Dropzone>
+}
+
+function CustomUserAvatar() {
+   const {
+      wrapperRef,
+      inputProps,
+      state: { files, isOver, isOverAccepted, showPlaceholder },
+      actions: { openFileInput }
+   } = useMediaDropzone();
+   
+   const file = files[0];
+
+   return (
+      <div
+         ref={wrapperRef}
+         className="size-32 rounded-full border border-gray-200 flex justify-center items-center leading-none overflow-hidden"
+      >
+         <div className="hidden">
+            <input {...inputProps} />
+         </div>
+         {showPlaceholder && <>{isOver && isOverAccepted ? "let it drop" : "drop here"}</>}
+         {file && (
+            <Media.Preview
+               file={file}
+               className="object-cover w-full h-full"
+               onClick={openFileInput}
+            />
+         )}
+      </div>
+   );
+}
+```
+
+# Auth
+Adding authentication to your app with bknd is as easy as adding a `<form method="POST" />` with an action pointing to the action (`login` or `register`) to the strategy you want to use, e.g. for the password strategy, use `/api/auth/password/login`. But to make it even easier, you can use the `Auth.*` elements.
+
+## `Auth.Screen`
+The `Auth.Screen` element is a wrapper around the `Auth.Form` element that provides a full page screen. The current layout is admittedly very basic, but there will be more customization options in the future.
+
+```tsx
+import { Auth } from "bknd/elements"
+
+export default function LoginScreen() {
+   return <Auth.Screen action="login" />
+}
+```
+
+### Props
+Note that this component doesn't require any strategy-specific information, as it gathers it itself. 
+
+- `action: "login" | "register"`: The action to perform.
+- `method?: "POST" | "GET"`: The method to use for the form.
+
+
+
+## `Auth.Form`
+If you only wish to render the form itself without the screen, you can use the `Auth.Form` element. Unlike the `Auth.Screen`, this element requires the `strategy` prop to be set to the strategy you want to use. You can either specify it manually, use use the exported hook `useAuthStrategies()` for fetch them from your bknd instance.
+
+```tsx
+import { Auth, useAuthStrategies } from "bknd/elements"
+
+export default function LoginForm() {
+   const { strategies, basepath, loading } = useAuthStrategies();
+   if (loading) return null;
+   
+   return <Auth.Form 
+      action="login" 
+      strategies={strategies} 
+      basepath={basepath} 
+   />
+}
+```
@@ -4,7 +4,7 @@ description: 'Setting up bknd'
 ---

 There are several methods to get **bknd** up and running. You can choose between these options:
-1. [Run it using the CLI](/cli): That's the easiest and fastest way to get started.
+1. [Run it using the CLI](/usage/cli): That's the easiest and fastest way to get started.
 2. Use a runtime like [Node](/integration/node), [Bun](/integration/bun) or
 [Cloudflare](/integration/cloudflare) (workerd). This will run the API and UI in the runtime's
 native server and serves the UI assets statically from `node_modules`.
@@ -78,7 +78,7 @@ const connection = {
 ```

 Alternatively, you can pass an instance of a `Connection` class directly,
-see [Custom Connection](/setup/database#custom-connection) as a reference.
+see [Custom Connection](/usage/database#custom-connection) as a reference.

 If the connection object is omitted, the app will try to use an in-memory database.

@@ -160,7 +160,7 @@ To validate your configuration against a JSON schema, you can also dump the sche
 npx bknd schema
 ```

-To create an initial data structure, you can use helpers [described here](/setup/database#initial-structure).
+To create an initial data structure, you can use helpers [described here](/usage/database#initial-structure).

 ### `plugins`
 The `plugins` property is an array of functions that are called after the app has been built,
@@ -3,10 +3,31 @@ title: 'SDK (React)'
 description: 'Use the bknd SDK for React'
 ---

-For all SDK options targeting React, you always have 2 options:
-1. use simple hooks which are solely based on the [API](/sdk)
-2. use the query hook that makes wraps the API in [SWR](https://swr.vercel.app/)
+There are 4 useful hooks to work with your backend:
+1. simple hooks which are solely based on the [API](/usage/sdk):
+   - [`useApi`](#useapi)
+   - [`useEntity`](#useentity)
+2. query hooks that wraps the API in [SWR](https://swr.vercel.app/):
+   - [`useApiQuery`](#useapiquery)
+   - [`useEntityQuery`](#useentityquery)

+
+## Setup
+In order to use them, make sure you wrap your `<App />` inside `<ClientProvider />`, so that these hooks point to your bknd instance:
+
+```tsx
+import { ClientProvider } from "bknd/client";
+
+export default function App() {
+   return <ClientProvider>
+      {/* your app */}
+   </ClientProvider>
+}
+```
+
+For all other examples below, we'll assume that your app is wrapped inside the `ClientProvider`.
+
+## `useApi()`
 To use the simple hook that returns the Api, you can use:
 ```tsx
 import { useApi } from "bknd/client";
@@ -17,7 +38,7 @@ export default function App() {
 }
 ```

-## `useApiQuery([selector], [options])`
+## `useApiQuery()`
 This hook wraps the API class in an SWR hook for convenience. You can use any API endpoint
 supported, like so:
 ```tsx
@@ -41,12 +62,12 @@ export default function App() {

 * `options`: optional object that inherits from `SWRConfiguration`

-   ```ts
-   type Options<Data> = SWRConfiguration & {
-      enabled?: boolean;
-      refine?: (data: Data) => Data | any;
-   }
-   ```
+```ts
+type Options <Data> = import("swr").SWRConfiguration & {
+   enabled? : boolean;
+   refine? : (data: Data) => Data | any;
+}
+```

      * `enabled`: Determines whether this hook should trigger a fetch of the data or not.
      * `refine`: Optional refinement that is called after a response from the API has been
@@ -58,7 +79,7 @@ following example we'll also use a `refine` function as well as `revalidateOnFoc
 `SWRConfiguration`) so that our data keeps updating on window focus change.

 ```tsx
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { useApiQuery } from "bknd/client";

 export default function App() {
@@ -108,7 +129,7 @@ export default function App() {
 ## `useEntity()`
 This hook wraps the endpoints of `DataApi` and returns CRUD options as parameters:
 ```tsx
-import { useState } from "react",
+import { useState, useEffect } from "react";
 import { useEntity } from "bknd/client";

 export default function App() {
@@ -144,7 +165,6 @@ optional. Deletes the given entry.
 This hook wraps the actions from `useEntity` around `SWR`. The previous example would look like
 this:
 ```tsx
-import { useState } from "react",
 import { useEntityQuery } from "bknd/client";

 export default function App() {
@@ -158,7 +178,7 @@ export default function App() {
 All actions returned from `useEntityQuery` are conveniently wrapped around the `mutate` function,
 so you don't have think about this:
 ```tsx
-import { useState } from "react";
+import { useState, useEffect } from "react";
 import { useEntityQuery } from "bknd/client";

 export default function App() {
@@ -10,6 +10,9 @@ import { Api } from "bknd";
 const api = new Api({
   host: "..." // point to your bknd instance
 });
+
+// make sure to verify auth
+await api.verifyAuth();
 ```

 The `Api` class is the main entry point for interacting with the bknd API. It provides methods
@@ -1,6 +1,6 @@
 {
   "name": "@bknd/plasmic",
-   "version": "0.5.0",
+   "version": "0.5.1",
   "type": "module",
   "sideEffects": false,
   "scripts": {
@@ -30,9 +30,13 @@
      "@plasmicapp/host": ">=1.0.0",
      "@plasmicapp/loader-react": ">=1.0.0"
   },
+   "optionalDependencies": {
+      "@plasmicapp/loader-nextjs": "^1.0.0"
+   },
   "tsup": {
      "entry": [
-         "src/index.ts"
+         "src/index.ts",
+         "src/nextjs/index.tsx"
      ],
      "minify": true,
      "clean": true,
@@ -42,7 +46,11 @@
         "@plasmicapp/host",
         "@plasmicapp/query",
         "@plasmicapp/loader-react",
-         "swr"
+         "@plasmicapp/loader-nextjs",
+         "swr",
+         "next",
+         "next/error",
+         "next/router"
      ],
      "format": [
         "esm"
@@ -54,9 +62,19 @@
      "sourceMap": true,
      "outDir": "dist"
   },
-   "types": "dist/index.d.ts",
-   "module": "dist/index.js",
-   "main": "dist/index.js",
+   "types": "./dist/index.d.ts",
+   "module": "./dist/index.js",
+   "main": "./dist/index.js",
+   "exports": {
+      ".": {
+         "types": "./dist/index.d.ts",
+         "import": "./dist/index.js"
+      },
+      "./nextjs": {
+         "types": "./dist/nextjs/index.d.ts",
+         "import": "./dist/nextjs/index.js"
+      }
+   },
   "files": [
      "dist",
      "README.md",
@@ -6,7 +6,7 @@ import {
 } from "@plasmicapp/host";
 import { usePlasmicQueryData } from "@plasmicapp/loader-react";
 import { useApi, useEntityQuery } from "bknd/client";
-import type { RepoQuery } from "bknd/data";
+import type { RepoQueryIn } from "bknd/data";
 // biome-ignore lint/style/useImportType: <explanation>
 import React from "react";
 import { usePlasmicBkndContext } from "../../contexts/BkndContext";
@@ -171,7 +171,7 @@ type ModeProps = {
   error?: React.ReactNode;
   empty?: React.ReactNode;
   entityId?: number;
-   query?: Partial<RepoQuery>;
+   query?: RepoQueryIn;
 };

 const ModeFetch = ({
@@ -0,0 +1,125 @@
+import {
+   type ComponentRenderData,
+   type NextJsPlasmicComponentLoader,
+   PlasmicComponent,
+   PlasmicRootProvider,
+   extractPlasmicQueryData
+} from "@plasmicapp/loader-nextjs";
+import type { GetStaticPaths, GetStaticProps, GetStaticPropsContext } from "next";
+import NextjsError from "next/error";
+import { useRouter } from "next/router";
+import React from "react";
+
+type TPlasmic = NextJsPlasmicComponentLoader;
+export type TGetStaticPropsOptions = {
+   baseUrl?: string;
+   revalidate?: number | boolean;
+};
+
+export function plasmicNextjsStatic(PLASMIC: TPlasmic, opts?: TGetStaticPropsOptions) {
+   return {
+      getStaticPaths: getStaticPaths(PLASMIC),
+      getStaticProps: getStaticProps(PLASMIC, opts),
+      CatchallPage: CatchallPage(PLASMIC)
+   };
+}
+
+export function getStaticPaths(PLASMIC: TPlasmic): GetStaticPaths {
+   return async () => {
+      const pages = await PLASMIC.fetchPages();
+      return {
+         paths: pages.map((page) => ({
+            params: { catchall: page.path.substring(1).split("/") }
+         })),
+         fallback: "blocking"
+      };
+   };
+}
+
+export function getStaticProps(PLASMIC: TPlasmic, opts?: TGetStaticPropsOptions): GetStaticProps {
+   return async (context: GetStaticPropsContext) => {
+      const baseUrl = opts?.baseUrl ?? process.env.BASE_URL!;
+
+      let { catchall } = context.params ?? {};
+      if (catchall && Array.isArray(catchall) && catchall[0] === "index") {
+         console.log("setting catch all to undefined");
+         catchall = undefined;
+      }
+
+      const globalContextsProps = {
+         bkndContextProps: {
+            baseUrl
+         }
+      };
+
+      // Convert the catchall param into a path string
+      const plasmicPath =
+         typeof catchall === "string"
+            ? catchall
+            : catchall !== null && Array.isArray(catchall)
+              ? `/${catchall.join("/")}`
+              : "/";
+
+      const plasmicData = await PLASMIC.maybeFetchComponentData(plasmicPath);
+      if (!plasmicData) {
+         // This is some non-Plasmic catch-all page
+         return {
+            props: {}
+         };
+      }
+
+      // This is a path that Plasmic knows about.
+      const pageMeta = plasmicData.entryCompMetas[0];
+
+      // Cache the necessary data fetched for the page.
+      const queryCache = await extractPlasmicQueryData(
+         <PlasmicRootProvider
+            loader={PLASMIC}
+            prefetchedData={plasmicData}
+            pageRoute={pageMeta.path}
+            pageParams={pageMeta.params}
+            globalContextsProps={globalContextsProps}
+         >
+            <PlasmicComponent component={pageMeta.displayName} />
+         </PlasmicRootProvider>
+      );
+
+      const props = { plasmicData, queryCache, globalContextsProps };
+
+      // Pass the data in as props.
+      return {
+         props,
+         // Using incremental static regeneration, will invalidate this page
+         // after 300s (no deploy webhooks needed)
+         revalidate: opts?.revalidate ?? 300
+      };
+   };
+}
+
+export function CatchallPage(PLASMIC: TPlasmic) {
+   return (props: {
+      plasmicData?: ComponentRenderData;
+      queryCache?: Record<string, any>;
+      globalContextsProps?: any;
+   }) => {
+      const { plasmicData, queryCache, globalContextsProps } = props;
+      const router = useRouter();
+      if (!plasmicData || plasmicData.entryCompMetas.length === 0) {
+         return <NextjsError statusCode={404} />;
+      }
+      const pageMeta = plasmicData.entryCompMetas[0];
+      return (
+         <PlasmicRootProvider
+            loader={PLASMIC}
+            prefetchedData={plasmicData}
+            prefetchedQueryData={queryCache}
+            pageRoute={pageMeta.path}
+            pageParams={pageMeta.params}
+            pageQuery={router.query}
+            globalContextsProps={globalContextsProps}
+         >
+            <PlasmicComponent component={pageMeta.displayName} />
+         </PlasmicRootProvider>
+      );
+   };
+}
Author	SHA1	Message	Date
dswbx	3d1d52cbf8	Merge pull request #58 from bknd-io/release/0.6.2 Release 0.6.2	2025-01-25 09:40:44 +01:00
dswbx	acc504cdc9	release version 0.6.2	2025-01-25 09:40:15 +01:00
dswbx	d98d3351c0	Merge pull request #57 from bknd-io/feat/elements-docs-and-custom restructured elements for better customization	2025-01-25 09:17:39 +01:00
dswbx	3e606cb159	Merge pull request #54 from bknd-io/fix/nextjs-schema-update fixed schema updates to fail in nextjs envs due to lodash's merge	2025-01-25 09:17:23 +01:00
dswbx	cc76964d03	restructured elements slightly for better customization, updated readme and docs	2025-01-25 09:14:02 +01:00
dswbx	b3019d7333	Merge pull request #55 from bknd-io/feat/nextjs-plasmic-catchall bknd/plasmic: added helper functions for integration	2025-01-25 09:03:30 +01:00
dswbx	2265451d4b	added handy nextjs-plasmic-bknd functions	2025-01-23 10:59:33 +01:00
dswbx	ba936604a3	fix overwrite of entity config (e.g. empty label)	2025-01-23 09:02:58 +01:00
dswbx	7dd42fbff3	fixed schema updates to fail in nextjs envs due to lodash's merge	2025-01-23 08:34:11 +01:00
dswbx	f64e5dac03	updated README and documentation (first part) to match 0.6	2025-01-21 18:30:01 +01:00