diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdx index 9d0d01a5..8366bdc6 100644 --- a/docs/content/docs/index.mdx +++ b/docs/content/docs/index.mdx @@ -1,62 +1,108 @@ --- title: Introduction -description: Add complete full-stack features to your React app in minutes, not weeks +description: Add complete features to the React app you already own. full: true --- import { Card, Cards } from "fumadocs-ui/components/card"; -import { Rocket, BookOpenCheck, Server, Layers, Router, Zap, Terminal } from "lucide-react"; +import { BookOpenCheck, Layers, Rocket, Server, Zap } from "lucide-react"; -## 👋 Welcome to BTST +## Add complete features to the React app you already own -**@btst - BTST** is a composable full-stack plugin system for modern React frameworks. +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 that need a substantial recurring feature without +replacing the application they already have. -Instead of building routes, APIs, databases, SSR, and forms from scratch, BTST gives you **complete full-stack features as plugins** that work with any modern React framework. - -### Key Features - -- **🔄 Framework Agnostic** - Works with Next.js, React Router, TanStack Router, Remix -- **📦 Full-Stack** - Routes, APIs, database schemas, components, hooks, SSR, metatags, sitemaps -- **🎯 Composable** - Mix and match features like LEGO blocks -- **🚀 Zero Boilerplate** - Configure and it works - -### Available Plugins - -**Blog** - Content management, editor, drafts, publishing, tags, SEO and more - -More plugins coming soon (AI assistant, scheduling, feedback, newsletters, comments). -Or build your own plugins for any horizontal feature. +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. } - description="Install and configure." + description="Add Blog to an existing Next.js app and open the working route." /> } - description="Available plugins and features." + title="Understand how BTST works" + href="/how-it-works" + icon={} + description="See where packages, plugins, data, routes, and owned UI fit." /> } - description="Generate database schemas and migrations." + title="View the live Blog" + href="https://www.better-stack.ai/p/blog" + icon={} + description="See a released BTST feature without changing an application." /> } - description="Build your own plugins." + title="Explore released plugins" + href="/plugins" + icon={} + description="Compare the capabilities you can install today." /> ---- +## 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. It is not a new +application foundation or a required hosted control plane: plugins run inside +your stack, with your database and deployment. + +**You own the whole application.** Your application, data, deployment, and +ejected UI stay yours. Packaged runtime and data behavior remains upgradeable +through `@btst/*` dependencies, and the open-source code can be inspected, +forked, or replaced. -## LLMs.txt +## Released capabilities -BTST provides an LLMs.txt file that helps AI models understand how to use the library. You can find it at [/docs/llms.txt](/llms.txt). +Different plugins have different boundaries. Full-stack plugins register both +backend and client behavior; one-sided plugins intentionally provide only the +side they need. Companions connect BTST to a system the application already +runs. +| Capability | Topology | What it adds | +| --- | --- | --- | +| [Blog](/plugins/blog) | Full-stack | Publishing workflow, routes, API, data model, editor, SEO, and RSS | +| [AI Chat](/plugins/ai-chat) | Full-stack | Streaming conversations, model integration, history, routes, and UI | +| [CMS](/plugins/cms) | Full-stack | Typed content models, APIs, generated forms, and editorial UI | +| [Form Builder](/plugins/form-builder) | Full-stack | Form authoring, validation, rendering, and submissions | +| [UI Builder](/plugins/ui-builder) | Client-only · requires CMS | Visual page authoring and public rendering over CMS content | +| [Kanban](/plugins/kanban) | Full-stack | Boards, columns, tasks, assignment, and drag-and-drop UI | +| [Comments](/plugins/comments) | Full-stack | Threads, replies, reactions, moderation, and embeddable UI | +| [Media](/plugins/media) | Full-stack | Media storage, library routes, uploads, folders, and picker UI | +| [OpenAPI](/plugins/open-api) | Backend-only | Generated OpenAPI document and interactive API reference endpoint | +| [Route Docs](/plugins/route-docs) | Client-only | Generated route reference and navigation UI | +| [Better Auth UI](/plugins/better-auth-ui) | Companion · requires Better Auth | Auth and account pages for an existing Better Auth backend | + +These are installable, released capabilities. The catalog does not mix future +ideas into the available inventory. See +[compatibility and prerequisites](/installation#compatibility-and-prerequisites) +before choosing an adapter or a plugin with an external dependency. + +## Choose the level of guidance you need + +- **Generated setup** is the shortest supported path for an existing Next.js + App Router, React Router v7, or TanStack Start application. +- **Manual installation** keeps every integration decision visible for teams + with custom project structure, routing, runtime, or deployment requirements. +- **Plugin development** is for building a reusable capability rather than + installing one of the released plugins. + + + } + description="Work through each package, adapter, route, provider, and deployment seam." + /> + } + description="Create a reusable backend, client, or full-stack capability." + /> + diff --git a/docs/content/docs/installation.mdx b/docs/content/docs/installation.mdx index 383302f4..88cfca89 100644 --- a/docs/content/docs/installation.mdx +++ b/docs/content/docs/installation.mdx @@ -7,10 +7,165 @@ import { Steps, Step } from "fumadocs-ui/components/steps"; import { Tabs, Tab } from "fumadocs-ui/components/tabs"; import { Callout } from "fumadocs-ui/components/callout"; +Use the generated path for the shortest supported integration into an existing +application. Use the manual reference when you need to control every route, +adapter, provider, and deployment seam. -## AI Agent Skills +Want to evaluate the result without changing an app? Open the +[live Blog](https://www.better-stack.ai/p/blog). The live demo uses `/p/blog`; +the generated application below uses its own `/pages/blog` route. -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: +## Quickstart: add Blog to Next.js + +This path adds the released Blog feature to an **existing Next.js App Router +application**. It uses the memory adapter for a local evaluation, so it does not +require a database migration and does not represent a production persistence +choice. + +### Quickstart prerequisites + +- Node.js 22 and an existing Next.js App Router application +- shadcn/ui initialized with CSS variables and Tailwind configured +- a clean commit or working tree you can review after the generator patches it +- the shadcn Button, dropdown menu, and Sonner components, with `` + rendered in the root layout + +Install the UI prerequisites first: + +```bash +npx shadcn@latest add button dropdown-menu sonner +``` + +Render the generated Sonner component once in your root layout. Keep your +existing providers and layout markup in place: + +```tsx title="app/layout.tsx" +import { Toaster } from "@/components/ui/sonner" + +// Inside the existing : +{children} + +``` + +The generated runtime uses React Query. Codegen installs +`@tanstack/react-query`, `@btst/stack`, and the selected adapter; the manual path +below lists them explicitly. + +### 1. Initialize Blog + +Run this command from the existing application root: + +```bash +npx @btst/codegen@0.2.0 init \ + --framework nextjs \ + --adapter memory \ + --plugins blog +``` + +Review conflict prompts before allowing generated files to replace application +files. The command registers the Blog backend and client plugin, mounts the API +and page catch-all routes, adds the required CSS, and wires the shared provider. + +### 2. Configure the local origin + +Add the trusted local origins to `.env.local`: + +```dotenv +BTST_SITE_URL=http://localhost:3000 +BTST_API_URL=http://localhost:3000 +``` + +Use the deployed application origin for both values in a same-origin +production deployment. The generated server integration fails closed during a +production build when it cannot resolve a trusted site or API origin. + +### 3. Start the app and verify the feature + +```bash +npm run dev +``` + +Open [http://localhost:3000/pages/blog](http://localhost:3000/pages/blog). The +Blog page should render successfully; it can be empty until you create content. +That visible route—not the presence of generated files—is the quickstart success +condition. + +The generated Blog override leaves image upload as an explicit application TODO. +The listing route works without it, but editor image uploads do not. The memory +adapter also resets when the process restarts. + +Before deploying, replace the memory adapter with the appropriate persistent +adapter, complete plugin-specific TODOs, and verify a production build: + +```bash +BTST_SITE_URL=http://localhost:3000 \ +BTST_API_URL=http://localhost:3000 \ +npm run build +``` + +## Generated setup or manual setup? + +Use [`@btst/codegen init`](/cli#init-codegen) when the application follows a +supported framework shape and you want BTST to write the standard integration. +Use the [manual installation](#manual-installation) when the application has +custom routing, provider composition, deployment boundaries, or file-layout +constraints. The detailed manual material remains the source of truth for those +seams. + +## Compatibility and prerequisites + +### Maintained framework paths + +The released v3 integration and codegen paths are maintained and tested for: + +| Framework | Integration | +| --- | --- | +| Next.js 15+ App Router | Route handlers, request-aware pages, 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 | + +Other React frameworks may be possible through custom adapters, but they are +not part of the maintained/tested matrix above. Remix is not a separate v3 +support claim. + +### Adapter choices + +| Adapter | Intended use and important limits | +| --- | --- | +| Prisma, Drizzle, Kysely | Versioned persistent adapter choices. Enable native isolated transactions for AI Chat, Form Builder, Kanban, or Media. | +| MongoDB | Versioned adapter with plugin-specific limits; generated Form Builder and Media configurations reject it. | +| Memory | Local, single-process evaluation and tests only; not a production persistence or isolation substitute. | + +See [Database Adapters](/databases/adapters) for provider configuration, +transactions, generation, and migrations. + +### Shared UI and runtime requirements + +- shadcn/ui with CSS variables, plus the UI components used by the selected + plugin +- Tailwind CSS and the selected plugin CSS imports +- Sonner with `` rendered in the application layout +- `@tanstack/react-query` and one `QueryClientProvider` + +### Plugin-specific exceptions + +| Capability | Requirement | +| --- | --- | +| Blog | Image uploads remain an application-provided override. | +| AI Chat | Requires an AI SDK model provider and its credentials; persistent writes require an isolating adapter. | +| UI Builder | Requires CMS; codegen adds CMS when UI Builder is selected. | +| Form Builder | Requires an isolating Prisma, Drizzle, or Kysely configuration for persistent use. | +| Media | Requires a storage adapter; persistent writes require isolation, and MongoDB is not accepted by the generated configuration. | +| Better Auth UI | Requires an existing Better Auth server endpoint and its aligned dependency cohort; it does not generate an auth backend. | + +Read the selected plugin page before installation for its exact package, +service, storage, auth, and override requirements. + +## AI coding agent assistance (optional) + +After you understand the product and normal installation path, you can install +the BTST integration skill so a coding agent understands the plugin system, +adapter setup, and wiring patterns: ```bash npx skills@latest add better-stack-ai/better-stack/.agents/skills/btst-integration @@ -20,7 +175,13 @@ Or manually copy the [`SKILL.md`](https://github.com/better-stack-ai/better-stac --- -## Prerequisites +## Manual installation + +The steps below preserve the complete framework and adapter integration +reference. Use them when generated setup is not appropriate or when you need to +audit each layer explicitly. + +### Prerequisites In order to use BTST, your application must meet the following requirements: @@ -1010,39 +1171,25 @@ In order to use BTST, your application must meet the following requirements: - ### 🎉 That's it! - - Your setup is complete! Here's what you've configured: - - - ✅ Backend API handler that processes all plugin requests - - ✅ Database adapter that connects plugins to your database - - ✅ Client-side router with SSR support - - ✅ React Query integration for data fetching - - ✅ API, site, and QueryClient configured once on the resolved client stack - - ✅ Framework router and optional auth services configured once on the provider - - **Next steps:** - - 1. **Add plugins** to both backend and client configurations: - - Backend: `plugins: { blog: blogBackendPlugin() }` - - Client: `plugins: { blog: blogClientPlugin() }` - - 2. **Visit your pages** at `/pages/*` to see plugin routes in action + ### Verify the integration - **Available plugins:** - - `@btst/stack/plugins/blog` - Full-featured blog with markdown editor, SEO, and RSS. Learn more about the blog plugin [here](/plugins/blog). - - More plugins coming soon! + The shared runtime is ready when the application has: - Each plugin provides everything you need: routes, API endpoints, database schemas, React components, and hooks - all working together seamlessly. + - a mounted backend API handler and selected database adapter; + - a resolved client stack, QueryClient, framework router, and provider; + - the selected plugin registered on every side it actually provides; + - plugin CSS and required UI components; and + - trusted site and API origins for production rendering. - ## Example Projects + Run the application build, then open a route registered by the selected + plugin. For Blog, `/pages/blog` is the visible success condition. - See complete working examples for each framework: - - **[Next.js App Router](https://www.better-stack.ai/playground?plugins=blog,ai-chat,comments&framework=nextjs&view=preview)** - Full Next.js App Router setup with blog and todo plugins - - **[React Router](https://www.better-stack.ai/playground?plugins=blog,ai-chat,comments&framework=react-router&view=preview)** - React Router v7 setup with SSR support - - **[TanStack Start](https://www.better-stack.ai/playground?plugins=blog,ai-chat,comments&framework=tanstack&view=preview)** - TanStack Router setup with file-based routing + Continue with the [released plugin catalog](/plugins), or compare complete + generated setups in the playground: - Each example includes complete configuration, plugin setup, and demonstrates framework-specific patterns. + - [Next.js App Router](https://www.better-stack.ai/playground?plugins=blog,ai-chat,comments&framework=nextjs&view=preview) + - [React Router v7](https://www.better-stack.ai/playground?plugins=blog,ai-chat,comments&framework=react-router&view=preview) + - [TanStack Start](https://www.better-stack.ai/playground?plugins=blog,ai-chat,comments&framework=tanstack&view=preview) diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json index 212b7165..1d9a708c 100644 --- a/docs/content/docs/meta.json +++ b/docs/content/docs/meta.json @@ -1,13 +1,14 @@ { "title": "BTST", - "description": "A composable full-stack plugin system for modern React frameworks.", + "description": "Add complete features to the React app you already own.", "icon": "Building", "root": true, "pages": [ "---[Hammer]Getting Started---", "index", - "installation", - "breaking-changes", + "[Install your first feature](/installation#quickstart-add-blog-to-nextjs)", + "[Compatibility & prerequisites](/installation#compatibility-and-prerequisites)", + "[Manual installation](/installation#manual-installation)", "how-it-works", "---[Layers]Plugins---", "plugins/index", @@ -25,13 +26,14 @@ "plugins/development", "---[Database]Databases---", "databases/adapters", - "---[BookOpenCheck]Concepts---", + "---[BookOpenCheck]Guides & Reference---", "auth", "i18n", "cli", "api-reference", "standalone-components", "shadcn-registry", + "breaking-changes", "---[Play]Playground---", "[Try the Playground](https://www.better-stack.ai/playground)" ] diff --git a/docs/content/docs/plugins/index.mdx b/docs/content/docs/plugins/index.mdx index b8b78052..2bf5655b 100644 --- a/docs/content/docs/plugins/index.mdx +++ b/docs/content/docs/plugins/index.mdx @@ -7,9 +7,14 @@ import { Card, Cards } from "fumadocs-ui/components/card"; import { BookOpen, Database, Hammer, Bot, FileText, FileCode, Route, Layout, Columns3, MessageSquare, ImageIcon, ShieldCheck } from "lucide-react"; -BTST provides a collection of full-stack plugins that you can easily integrate into your React application. Each plugin includes routes, APIs, database schemas, components, and hooks—everything you need to add complete features to your app. +BTST ships installable capabilities with different boundaries. Full-stack +plugins register backend and client behavior. OpenAPI is backend-only, Route +Docs is client-only, UI Builder is client-only and depends on CMS, and Better +Auth UI is a companion for an application that already runs Better Auth. -With more plugins coming soon, you can add complete features to your app in minutes. +Every capability below is released and installable. Choose a page to see its +actual payload and prerequisites; the catalog does not mix roadmap ideas into +the available inventory.