From 33eac3587c3a80f413d0b45b5ee1473fa9c03257 Mon Sep 17 00:00:00 2001 From: olliethedev <5933733+olliethedev@users.noreply.github.com> Date: Tue, 1 Sep 2026 15:57:34 -0400 Subject: [PATCH] docs: rebuild README evaluator journey (#261) --- README.md | 338 +++++++++++++++++------------------------------------- 1 file changed, 108 insertions(+), 230 deletions(-) diff --git a/README.md b/README.md index 698655e2..a36baf71 100644 --- a/README.md +++ b/README.md @@ -4,300 +4,178 @@ ## Add complete features to the React app you already own. -BTST is an open-source TypeScript system for installing full-stack features into existing React applications. It is built for React/TypeScript developers and small product teams adding a substantial feature to an app they already have. +BTST is an open-source TypeScript system for installing full-stack features into existing React applications. -A full-stack plugin can bring the routes, APIs, database schema, hooks, SSR-aware pages, and customizable UI that its feature needs. Start with one plugin and add more only when they are useful. +It is built for React/TypeScript developers and small product teams adding a substantial feature to an app they already have. A full-stack plugin can bring the routes, APIs, database schema, hooks, SSR-aware pages, and customizable UI that its feature needs. **You own the whole application.** Your app, data, deployment, and ejected UI stay yours. BTST runs inside your stack as an open-source dependency you can inspect, fork, or replace—never as a required hosted control plane. +[**Quickstart with Blog**](#quickstart-blog-in-an-existing-nextjs-app) · [View the live Blog](https://www.better-stack.ai/p/blog) · [Read the docs](https://www.better-stack.ai/docs) + +[![npm](https://img.shields.io/npm/v/@btst/stack.svg)](https://www.npmjs.com/package/@btst/stack) +[![MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](./LICENSE.md) + ![BTST promise above a focused view of the real Blog route from the generated application.](docs/assets/product-proof/readme-hero.webp) Real output from the repository's generated Next.js application. -[![npm](https://img.shields.io/npm/v/@btst/stack.svg)](https://www.npmjs.com/package/@btst/stack) -[![MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + -[Quickstart with Blog](https://www.better-stack.ai/docs/cli#init-codegen) · [View live result](https://www.better-stack.ai/p/blog) · [Read the docs](https://www.better-stack.ai/docs) +## Where BTST fits - +BTST is **more complete than a UI kit, more incremental than a starter application, and more ownable than a hosted feature service**. + +| Starting point | What it gives you | Adoption boundary | +| --- | --- | --- | +| UI kit | Components and interaction primitives | Your team still builds the feature's routes, data model, APIs, and workflows | +| Starter application | An application foundation with initial features | You adopt its application structure as the place you start | +| Hosted feature service | A feature operated behind a vendor service boundary | Its control plane, runtime, or data path remains outside your application | +| **BTST** | An installable feature runtime, generated integration, and customizable views | Add one capability inside the app, database, and deployment you already operate | ---- +Start with one plugin and add more only when they are useful. BTST does not replace your application foundation or require a hosted control plane. -## What is BTST? +![Diagram separating the application and operating boundaries a team owns from the BTST runtimes and plugins running inside it.](docs/assets/product-proof/ownership-diagram.svg) -BTST delivers complete features through npm packages. It is more complete than -a UI kit, more incremental than a starter application, and more ownable than a -hosted feature service. +

BTST composes client and backend plugins inside the application; the app shell, ejected views, database, deployment, and external services remain yours.

+ +## Quickstart: Blog in an existing Next.js app + +This local evaluation uses the public stable releases with Node.js 22, an existing Next.js 15+ App Router application, and Radix-based shadcn/ui with CSS variables. If shadcn/ui is not configured yet, initialize that verified base and add the components Blog needs: ```bash -npx @btst/codegen@0.2.0 init --plugins blog +pnpm dlx shadcn@4.19.1 init --base radix --preset nova --css-variables +pnpm dlx shadcn@4.19.1 add button dropdown-menu sonner --yes ``` -The initializer adds BTST to an existing Next.js App Router, React Router v7, -or TanStack Start application. You can also follow the detailed -[manual installation guide](https://www.better-stack.ai/docs/installation). +Render the generated `` in your root layout and start from a clean commit you can review. The [complete prerequisite checklist](https://www.better-stack.ai/docs/installation#quickstart-prerequisites) covers the remaining application requirements. -### Available plugins +Run the released generator from the application root: -| Plugin | Topology | Description | -|--------|----------|-------------| -| **Blog** | Full-stack | Content management, editor, drafts, publishing, SEO, RSS feeds | -| **AI Chat** | Full-stack | AI-powered chat with conversation history, streaming, and customizable models | -| **CMS** | Full-stack | Headless CMS with custom content types, Zod schemas, and auto-generated forms | -| **Form Builder** | Full-stack | Dynamic form builder with drag-and-drop editor, submissions, and validation | -| **UI Builder** | Client-only · requires CMS | Visual drag-and-drop page builder with component registry and public rendering | -| **Kanban** | Full-stack | Project management with boards, columns, tasks, drag-and-drop, and priority levels | -| **Media** | Full-stack | Media library with uploads, folders, picker UI, URL registration, and reusable image inputs | -| **OpenAPI** | Backend-only | Auto-generated API documentation with interactive Scalar UI | -| **Route Docs** | Client-only | Auto-generated client route documentation with interactive navigation | -| **Comments** | Full-stack | Commenting system with moderation, likes, and nested replies | -| **Better Auth UI** | Companion · requires Better Auth | Auth and account UI for an existing Better Auth backend | +```bash +pnpm dlx @btst/codegen@0.2.0 init \ + --framework nextjs \ + --adapter memory \ + --plugins blog +``` -Full-stack plugins ship separate frontend and backend definitions. Intentional -one-sided plugins stay one-sided, dependent plugins name what they require, and -companions connect BTST to a system the application already runs. +The generator shows detected-file and conflict prompts before it writes. It installs `@btst/stack@3.0.0`, registers Blog on the backend and client, mounts the API and page routes, adds the plugin CSS, and wires the shared provider. + +Set the trusted local origins in `.env.local`: + +```dotenv +BTST_SITE_URL=http://localhost:3000 +BTST_API_URL=http://localhost:3000 +``` -**Want a specific plugin?** [Open an issue](https://github.com/better-stack-ai/better-stack/issues/new) and let us know! +Then start the app and open the generated route: ---- +```bash +pnpm dev +# http://localhost:3000/pages/blog +``` -## Why use it? +`/pages/blog` is the success condition. A fresh local route can be empty until you create content. The memory adapter resets with the process and is for evaluation and tests, not production persistence; Blog image uploads also remain an explicit application override. Continue with the [production and manual setup reference](https://www.better-stack.ai/docs/installation) before deploying. -* **Installable features** – routes, APIs, data models, pages, and UI where the plugin supplies them -* **Framework-flexible** – maintained v3 integration paths for Next.js App Router, React Router v7, and TanStack Start -* **Database adapters** – versioned adapters for Prisma, Drizzle, Kysely, and MongoDB -* **Incremental adoption** – install one feature without replacing your application foundation -* **Type-safe** – end-to-end TypeScript +![Real BTST Blog page with three published product-update posts in the generated Next.js application.](docs/assets/product-proof/blog-proof.webp) -Your application, database, and deployment remain under your control. +

The same generated Blog route after deterministic sample content is added.

---- +### The registration that produces the route -## Minimal setup (Next.js) +The stable-v3 seam is deliberately small: the backend plugin supplies Blog's server behavior and data model; the client plugin supplies its routes and UI. The generator provides the surrounding adapter, API/site runtime, QueryClient, catch-all routes, and provider wiring. -```ts title="lib/stack.ts" +```ts import { createBackendStack } from "@btst/stack/api" -import { blogBackendPlugin } from "@btst/stack/plugins/blog/api" import { createMemoryAdapter } from "@btst/adapter-memory" +import { blogBackendPlugin } from "@btst/stack/plugins/blog/api" -function createAppStack() { - return createBackendStack({ - basePath: "/api/data", - plugins: { - blog: blogBackendPlugin() - }, - adapter: (db) => createMemoryAdapter(db)({}) - }) -} - -type AppStack = ReturnType -const globalForStack = globalThis as typeof globalThis & { - __btst_stack__?: AppStack -} -export const myStack = globalForStack.__btst_stack__ ??= createAppStack() -export const { handler, dbSchema } = myStack +createBackendStack({ + basePath: "/api/data", + adapter: (db) => createMemoryAdapter(db)({}), + plugins: { blog: blogBackendPlugin() }, +}) ``` -```tsx title="lib/stack-client.tsx" -import { - createClientStack, - type ClientPluginEndpointOverride, -} from "@btst/stack/client" +```tsx +import { createClientStack } from "@btst/stack/client" import { blogClientPlugin } from "@btst/stack/plugins/blog/client" import type { QueryClient } from "@tanstack/react-query" -export interface StackClientOptions { - apiOrigin: string - siteOrigin: string -} - -export function createAppClientStack( - queryClient: QueryClient, - options: StackClientOptions & { headers?: HeadersInit }, -) { - const { apiOrigin, siteOrigin } = options - const crossOriginBlogEndpoint = apiOrigin === siteOrigin - ? undefined - : { - api: { - baseURL: apiOrigin, - basePath: "/api/data", - credentials: "include", - }, - } satisfies ClientPluginEndpointOverride - +function createAppClientStack(queryClient: QueryClient, origin: string) { return createClientStack({ - api: { - baseURL: apiOrigin, - basePath: "/api/data", - ...(options.headers ? { headers: options.headers } : {}), - }, - site: { baseURL: siteOrigin, basePath: "/pages" }, + api: { baseURL: origin, basePath: "/api/data" }, + site: { baseURL: origin, basePath: "/pages" }, queryClient, - plugins: { - blog: blogClientPlugin() - }, - ...(crossOriginBlogEndpoint - ? { endpoints: { blog: crossOriginBlogEndpoint } } - : {}), + plugins: { blog: blogClientPlugin() }, }) } - -export function getStackClient( - queryClient: QueryClient, - options: StackClientOptions, -) { - return createAppClientStack(queryClient, options) -} ``` -The generated `lib/stack-client.server.ts` resolves these origins from trusted -deployment configuration (`BTST_API_URL` and `BTST_SITE_URL`), defaults the API -to the trusted site origin, and forwards filtered credentials only to that API. -It fails closed in production if no trusted origin is available. -Existing same-origin Next.js installs may keep `NEXT_PUBLIC_BASE_URL` while -migrating; new deployments should prefer the separate site/API variables. +![The current Blog backend and client registrations point to the real published Blog route they produce.](docs/assets/product-proof/code-to-result.webp) -Use the v3 framework entry factories for the two catch-all routes: +Blog adds publishing routes, API operations, its data model, hooks, SSR-aware pages, editor UI, SEO metadata, RSS, and sitemap entries. Other plugins have different boundaries: one-sided and companion plugins are labeled instead of being forced into a full-stack claim. -```ts title="app/api/data/[[...all]]/route.ts" -import { toNextRouteHandlers } from "@btst/stack/next" -import { handler } from "@/lib/stack" +## Released capabilities -export const { GET, POST, PUT, PATCH, DELETE } = - toNextRouteHandlers(handler) -``` +Every capability below is installable from the released CLI. Follow its documentation for the actual payload, services, storage, auth, and adapter prerequisites. -```tsx title="app/(request)/pages/[[...all]]/page.tsx" -import { createNextPage } from "@btst/stack/next" -import { headers } from "next/headers" -import { getStackClientForRequest } from "@/lib/stack-client.server" -import { getOrCreateQueryClient } from "@/lib/query-client" +| Capability | Topology | Outcome | +| --- | --- | --- | +| [Blog](https://www.better-stack.ai/docs/plugins/blog) | Full-stack | Publishing workflow, routes, API, data model, editor, SEO, and RSS | +| [AI Chat](https://www.better-stack.ai/docs/plugins/ai-chat) | Full-stack | Streaming conversations, model integration, history, routes, and chat UI | +| [CMS](https://www.better-stack.ai/docs/plugins/cms) | Full-stack | Typed content models, APIs, generated forms, and editorial UI | +| [Form Builder](https://www.better-stack.ai/docs/plugins/form-builder) | Full-stack | Form authoring, validation, rendering, and submissions | +| [Kanban](https://www.better-stack.ai/docs/plugins/kanban) | Full-stack | Boards, columns, tasks, assignment, and drag-and-drop UI | +| [Comments](https://www.better-stack.ai/docs/plugins/comments) | Full-stack | Threads, replies, reactions, moderation, and embeddable UI | +| [Media](https://www.better-stack.ai/docs/plugins/media) | Full-stack | Media storage, library routes, uploads, folders, and picker UI | +| [UI Builder](https://www.better-stack.ai/docs/plugins/ui-builder) | Client-only · requires CMS | Visual page authoring and public rendering over CMS content | +| [OpenAPI](https://www.better-stack.ai/docs/plugins/open-api) | Backend-only | Generated OpenAPI document and interactive API reference endpoint | +| [Route Docs](https://www.better-stack.ai/docs/plugins/route-docs) | Client-only | Generated route reference and navigation UI | +| [Better Auth UI](https://www.better-stack.ai/docs/plugins/better-auth-ui) | Companion · requires Better Auth | Auth and account pages for an existing Better Auth backend | -export const dynamic = "force-dynamic" +[Explore the released catalog](https://www.better-stack.ai/docs/plugins) or compare complete generated setups in the [interactive playground](https://www.better-stack.ai/playground?plugins=blog,ai-chat,comments&framework=nextjs&view=preview). -const page = createNextPage({ - getStackClient: async (queryClient) => - getStackClientForRequest(queryClient, { - headers: new Headers(await headers()), - }), - getQueryClient: getOrCreateQueryClient, -}) -export default page.Page -export const generateMetadata = page.generateMetadata -``` +## Compatibility and prerequisites -The request layout at `app/(request)/pages/layout.tsx` hydrates trusted client -origins into the shared provider in `app/pages/client-layout.tsx`. Put SSG/ISR -routes under `app/(static)/pages` with a header-free layout; route groups do not -change the public `/pages/*` URLs. +The maintained and tested v3 integration paths are: -Wrap the pages subtree with one `StackProvider`: +| Framework | Maintained integration | +| --- | --- | +| Next.js 15+ App Router | Route handlers, request-aware and static pages, metadata, and sitemap factories | +| React Router v7 | Framework routes, SSR loaders, navigation, metadata, and sitemap response helpers | +| TanStack Start | File routes, SSR loaders, navigation, metadata, and sitemap response helpers | -```tsx -// app/pages/client-layout.tsx -"use client" - -function PagesClientLayout({ children, clientOrigins }: { - children: React.ReactNode - clientOrigins: StackClientOptions -}) { - const queryClient = getOrCreateQueryClient() - const clientStack = useMemo( - () => getStackClient(queryClient, clientOrigins), - [clientOrigins.apiOrigin, clientOrigins.siteOrigin, queryClient], - ) - - return ( - - - {children} - - - ) -} -``` +Other React integrations may be possible through custom adapters, but they are not part of that maintained matrix. -API, site, and QueryClient runtime belong on the resolved client stack; router -and auth services belong on the provider. Plugin overrides contain only -plugin-specific customization. See the [full installation guide](https://www.better-stack.ai/docs/installation) -for QueryClient wiring, database adapters, all three frameworks, and auth. +Versioned adapters are published for Prisma, Drizzle, Kysely, and MongoDB. Support is not blanket-equivalent: plugins that need isolated transactions have stricter persistent-adapter requirements, and the generated Form Builder and Media configurations reject MongoDB. The memory adapter is local and single-process only. Check [compatibility and prerequisites](https://www.better-stack.ai/docs/installation#compatibility-and-prerequisites) and the [adapter guide](https://www.better-stack.ai/docs/databases/adapters) for current versions and limits. -## Database schemas & migrations +## Keep the view code, too -Generate schemas and run migrations through the v3 codegen CLI. It runs the -aligned Better DB CLI in isolation, so its dependencies and `btst` binary do -not enter your application graph: +BTST's packaged runtime keeps data fetching and behavior upgradeable. When a plugin offers a shadcn v4 registry block, it copies the view layer into your application. Edit that code freely, then pass pages back through the plugin's component overrides where available or render copied components directly; hooks and API behavior can remain package dependencies. -```bash -npx @btst/codegen@0.2.0 generate --orm drizzle --config lib/stack.ts --output db/schema.ts -``` +[Read the ejection guide](https://www.better-stack.ai/docs/shadcn-registry) -Versioned adapter packages are available for Prisma, Drizzle, MongoDB, and -Kysely SQL dialects. Follow the -[installation guide](https://www.better-stack.ai/docs/installation) for their -current versions and setup requirements. +## Go deeper ---- +- [Installation and production setup](https://www.better-stack.ai/docs/installation) — frameworks, providers, auth, origins, adapters, and migrations +- [How BTST works](https://www.better-stack.ai/docs/how-it-works) — backend/client composition and ownership boundaries +- [CLI reference](https://www.better-stack.ai/docs/cli) — initialize, generate schemas, migrate, and seed +- [Build a plugin](https://www.better-stack.ai/docs/plugins/development) — create a backend-only, client-only, or full-stack capability +- [API reference](https://www.better-stack.ai/docs/api-reference) — stack factories, runtime services, and framework adapters +- [Stable-v3 migration guide](https://www.better-stack.ai/docs/breaking-changes) — migrate older integrations to the released contract -## Shadcn Registry +### Optional AI-agent guidance -Each plugin's UI layer is available as a [shadcn registry](https://ui.shadcn.com/docs/registry) block. Use it to **eject and fully customize** the page components while keeping all data-fetching and API logic from `@btst/stack`: - -```bash -# Install a single plugin's UI (for example, Media) -npx shadcn@latest add https://github.com/better-stack-ai/better-stack/blob/main/packages/stack/registry/btst-media.json - -# Or install the full collection -npx shadcn@latest add https://github.com/better-stack-ai/better-stack/blob/main/packages/stack/registry/registry.json -``` - -Components are copied into `src/components/btst/{plugin}/client/` — all relative imports remain valid and you can edit them freely. - ---- - -## AI Agent Skills - -If you're using an AI coding agent (Cursor, Claude Code, VS Code, OpenAI Codex etc.) you can install the BTST integration skill so your agent understands the plugin system, adapter setup, and wiring patterns out of the box: +After you understand the human installation path, you can give a coding agent the repository's BTST integration skill: ```bash npx skills@latest add better-stack-ai/better-stack/.agents/skills/btst-integration ``` -Or manually copy [`skills/btst-integration/SKILL.md`](./.agents/skills/btst-integration/SKILL.md) into your project's agent skills directory. - ---- - -## Live Demo - -Try the interactive playground: - -* [Next.js](https://www.better-stack.ai/playground?plugins=blog,ai-chat,comments&framework=nextjs&view=preview) -* [React Router](https://www.better-stack.ai/playground?plugins=blog,ai-chat,comments&framework=react-router&view=preview) -* [TanStack Router](https://www.better-stack.ai/playground?plugins=blog,ai-chat,comments&framework=tanstack&view=preview) - ---- - -## Learn more - -Full documentation, guides, and plugin development: -👉 **[https://www.better-stack.ai](https://www.better-stack.ai)** - ---- - -## Contributing - -Bug reports, plugin PRs, and documentation improvements are welcome. -See **[CONTRIBUTING.md](./CONTRIBUTING.md)** for the plugin development guide, testing instructions, and submission checklist. -Public-facing copy should follow the **[BTST message and claims contract](./docs/positioning.md)**. +## Contributing and license ---- +Bug reports, plugin contributions, and documentation improvements are welcome. Read [CONTRIBUTING.md](./CONTRIBUTING.md) for the development workflow, tests, and submission checklist; public-facing copy follows the [BTST message and claims contract](./docs/positioning.md). -If this saves you time, a ⭐ helps others find it. +BTST is released under the [MIT License](./LICENSE.md). -MIT © [olliethedev](https://github.com/olliethedev) +If BTST is useful to you, a star helps other React developers find it.