Skip to content

docs: make onboarding evaluator-first #265

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
olliethedev merged 1 commit into from
Sep 1, 2026
Merged

docs: make onboarding evaluator-first #265

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 83 additions & 37 deletions docs/content/docs/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

<Cards>
<Card
title="Installation"
href="/installation"
title="Install your first feature"
href="/installation#quickstart-add-blog-to-nextjs"
icon={<Zap size={20} />}
description="Install and configure."
description="Add Blog to an existing Next.js app and open the working route."
/>
<Card
title="Plugins"
href="/plugins"
icon={<Layers size={20} />}
description="Available plugins and features."
title="Understand how BTST works"
href="/how-it-works"
icon={<Server size={20} />}
description="See where packages, plugins, data, routes, and owned UI fit."
/>
<Card
title="CLI"
href="/cli"
icon={<Terminal size={20} />}
description="Generate database schemas and migrations."
title="View the live Blog"
href="https://www.better-stack.ai/p/blog"
icon={<Rocket size={20} />}
description="See a released BTST feature without changing an application."
/>
<Card
title="Plugin Development"
href="/plugins/development"
icon={<BookOpenCheck size={20} />}
description="Build your own plugins."
title="Explore released plugins"
href="/plugins"
icon={<Layers size={20} />}
description="Compare the capabilities you can install today."
/>
</Cards>

---
## 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.

<Cards>
<Card
title="Manual installation"
href="/installation#manual-installation"
icon={<BookOpenCheck size={20} />}
description="Work through each package, adapter, route, provider, and deployment seam."
/>
<Card
title="Build a plugin"
href="/plugins/development"
icon={<BookOpenCheck size={20} />}
description="Create a reusable backend, client, or full-stack capability."
/>
</Cards>
209 changes: 178 additions & 31 deletions docs/content/docs/installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<Toaster />`
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 <body>:
{children}
<Toaster />
```

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 `<Toaster />` 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
Expand All @@ -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:

Expand Down Expand Up @@ -1010,39 +1171,25 @@ In order to use BTST, your application must meet the following requirements:
</Step>

<Step>
### 🎉 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)

</Step>
</Steps>
Loading
Loading