Patterns for writing BTST client plugins inside the monorepo, including defineClientPlugin structure, route anatomy (PageComponent/loader/meta), lazy loading, SSR loader pattern, meta generators, ComposedRoute with ErrorBoundary/Suspense, useSuspenseQuery error throwing, query key factories, and client override shapes. Use when creating or modifying a client plugin, adding routes/loaders/meta, wiring ComposedRoute, implementing useSuspenseQuery, or building query key factories in src/plugins/{name}/client/.
Patterns for running BTST unit tests (Vitest) and E2E tests (Playwright), including unit test structure using the memory adapter, smoke test commands, per-framework E2E runs, Playwright project configuration, API key guards, and environment variable setup. Use when writing or running unit tests for plugin getters/mutations, running e2e smoke tests, targeting a specific framework, writing a new smoke test, or setting up API key guards for external service tests.
Patterns for configuring the BTST monorepo build when adding new plugin entry points, package exports, CSS exports, and updating all three example apps. Use when adding a new export path, updating build.config.ts entries, adding exports/typesVersions to package.json, exposing CSS, updating the Next.js/React Router/TanStack example apps, or adding shared UI components via @workspace/ui.
Guides developers and AI agents through manual BTST library consumption in existing apps, including plugin registration, CSS imports, adapter setup, StackProvider wiring, React Query, and CLI schema workflows. Use when integrating `@btst/stack`, configuring `@btst/adapter-*`, wiring plugin `api/client` packages, setting up `StackProvider` overrides, adding `/api/data` and `/pages` routes, or running `@btst/cli generate|migrate` without scaffolding.
Patterns for registering page-level AI context in BTST plugin pages so the AI chat widget understands the current page and can act on it. Use when adding useRegisterPageAIContext to a plugin page, implementing clientTools for AI-driven form filling or editor updates, registering server-side tool schemas in BUILT_IN_PAGE_TOOL_SCHEMAS, or wiring PageAIContextProvider in layouts.
Patterns for writing BTST backend plugins inside the monorepo, including defineBackendPlugin structure, getters.ts/mutations.ts separation, the api factory, lifecycle hook naming conventions, and accessing the adapter in AI tool execute functions. Use when creating or modifying a backend plugin, adding DB getters or mutations, wiring the api factory, or implementing lifecycle hooks in src/plugins/{name}/api/.
Workflow for updating BTST documentation when making consumer-facing changes to plugins, components, or APIs. Use when adding new props to exported components, adding new exported types or hooks, changing API shapes, adding a new plugin, or making any change that consumers of @btst/stack need to know about.
Patterns for adding SSG (static site generation) support to BTST plugins using prefetchForRoute, including query-key-defs.ts, serializers.ts, typed prefetchForRoute overloads, and the SSG page.tsx pattern for Next.js. Use when a plugin needs static generation support, when route.loader() silently fails at next build, when adding prefetchForRoute to the api factory, or when fixing infinite query shape/date serialization errors during SSG.