Migrating to v6

Use pnpm dlx @btst/codegen@6.0.0 init for the stable v6 installation set. The npm next channel now tests the 6.2 beta installation set. The version table below records the initial v6 migration; use the beta guide for current package versions, new plugins, and additional database migrations.

BTST v6 keeps the shared runtime in @btst/stack. Install each selected plugin package alongside core. Plugin package versions describe their own backend and client contract; they do not need to match the core version.

The initial tested set uses Core 6.0.0 and all 19 independently versioned plugin packages at 1.0.0. Install the features your application selects and their documented code dependencies. Runtime registration is separate: for example, Job Board uses Form Builder code without automatically registering its routes. The CLI selects the tested package and adapter versions, adds required runtime registrations, and wires Blog–Newsletter behavior only when both are selected.

Plugins support Core >=6.0.0 <7.0.0. At the first stable rollout the minimum and latest supported Core versions are both 6.0.0. The optional companion selection uses @btst/better-auth-ui@3.0.3 for Core v6.

The complete v5.2.0 import map records every one of the 157 original exports, including retained Core contracts, CSS and module-specific declaration surfaces. Feature imports move to their owners; generic Core plugin-authoring imports remain in Core. In particular, old @btst/stack/ui/css moves to the separate @btst/components/ui/css theme, while Markdown CSS stays at @btst/components/markdown/css.

Packages and their exact local candidate artifacts can be checked before npm provisioning or first publication. Core v6 contains no legacy feature/component facade. Existing routes, plugin IDs, permissions, query keys, serialized data and model/table identities are preserved; this package move needs no data reset.

Tested installation set

Use @btst/codegen@6.0.0 with Core 6.0.0, the 19 feature owners at 1.0.0, and optional @btst/components@1.0.0. The supported adapters are @btst/adapter-memory, @btst/adapter-prisma, @btst/adapter-drizzle, @btst/adapter-kysely, and @btst/adapter-mongodb, each at 3.0.1. Core uses @btst/db@3.0.1 and @btst/yar@1.3.2. The scaffold pins lucide-react@0.475.0 to the shared UI cohort so server and browser bundles use that tested direct dependency. Blog retains its own ^1.63.0 icon dependency. For Vite SSR, add lucide-react to ssr.noExternal so each owner keeps its own resolution on the server and browser; the CLI patches supported static configs.

The package version table and adapter, Auth, AI and ORM metadata record the complete coordinated installation set, including the exact selected third-party versions. Install only the extras required by your selected features and adapter. The companion's auth and account client registrations still require an application-owned Better Auth backend; selecting it does not configure organization, API-key, or passkey features. Form Builder and Affiliate require an adapter with isolated transactions; the CLI rejects memory scaffolds for them.

Vitest dependency transformation

If your Vitest configuration inlines @btst/stack to transform dependency CSS or apply module mocks, add the extracted packages your tests import. For example, AI Chat imports editor CSS and Media tests may mock a storage provider SDK:

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    server: {
      deps: {
        inline: ["@btst/stack", "@btst/plugin-ai-chat", "@btst/plugin-media"],
      },
    },
  },
});

This configuration affects the test runner; application imports still use each package's public entries.

AI Chat import migration

@btst/plugin-ai-chat/types also exposes the existing conversation and message types. Existing type exports from the API, client, and query-key entries remain available. Both ESM and CommonJS consumers receive declarations for their module format. Import the plugin stylesheet to keep its styles in production builds.

Keep registering the plugin as aiChat. Its routes, permission namespace, query keys, serialized data, and conversation/message database identities remain unchanged. Changing package imports does not reset stored data.

Core owns PageAIContextProvider, useRegisterPageAIContext, and usePageAIContext. Put the provider above the application providers and import page registration from @btst/stack/page-context, including in pages that do not install AI Chat. AI Chat consumes that same provider.

Media import migration

Install @btst/plugin-media@1.0.0 with core v6. Keep the registration key media; existing asset/folder IDs, mediaAsset/mediaFolder data, permissions, and query partitions remain unchanged.

Existing model types are also available at @btst/plugin-media/types. Local and S3 browser clients do not require the Blob SDK. For Blob uploads, import vercelBlobUpload from @btst/plugin-media/client/vercel-blob and supply it as uploadBlob alongside uploadMode: "vercel-blob". This also applies to direct uploadAsset() calls. Install AWS/Blob SDKs only for the selected adapters; the CLI's existing default remains local storage.

Kanban import migration

Install @btst/plugin-kanban@1.0.0 alongside core 6.0.0. Kanban supports core >=6.0.0 <7.0.0 and does not require another plugin package.

@btst/plugin-kanban/types exposes existing board, column and task types, including Task and Column for integrations. Keep registering the plugin as kanban. Its routes, permissions, query keys, SSG serialization and kanbanBoard/kanbanColumn/kanbanTask identities are preserved. Importing the new package does not require a data reset.

CMS import migration

Install @btst/plugin-cms@1.0.0 with core 6.0.0. Its supported core range is >=6.0.0 <7.0.0.

@btst/plugin-cms/types exposes the existing content records, configurations and serialized types. The browser/server-safe query-keys entry also exports the existing contentListDiscriminator for integrations that share CMS cache identities. Keep the registration ID cms, existing permission namespace, query keys and the contentType, contentItem and contentRelation database identities. No data reset or schema migration is needed for the package extraction.

Ecommerce import migration

Install @btst/plugin-ecommerce@1.0.0 with core 6.0.0 and its CMS and Media code dependencies. The supported core range is >=6.0.0 <7.0.0.

@btst/plugin-ecommerce/types exposes existing product, order, cart and checkout types. Keep registration ID ecommerce, ecommerce-product CMS content, inventory/order table identities, permission namespace and query keys. CMS is required at runtime; Media registration remains optional even though its code package is installed. Existing URL images, asset resolution when enabled, authorization and isolated checkout transaction requirements are preserved. No data reset is needed.

Form Builder import migration

Install @btst/plugin-form-builder@1.0.0 with core 6.0.0.

The types entry exposes existing form and submission records. Keep registering the plugin as formBuilder; its forms permission namespace, query keys, and form/formSubmission model identities are preserved. The package move requires no data reset. Adapter isolation requirements remain in force.

Independent releases

Use pnpm changeset to describe a change to the packages it affects, then inspect pnpm changeset status before versioning. There are no fixed or linked release groups. A change to AI Chat does not require a release of an unchanged unrelated plugin. A CLI release exposes a tested installation set through its exact package specifications, including the existing adapter and companion dependency pins.

CRM

Install @btst/plugin-crm@1.0.0 with @btst/plugin-kanban@1.0.0 and core v6. Register Kanban before CRM on the backend. The CLI includes this requirement. Replace @btst/stack/plugins/crm/{api,client,client/hooks,client/components,query-keys,permissions,css} with the matching @btst/plugin-crm/ entry. Model types are also available from @btst/plugin-crm/types. Runtime IDs, schemas, permissions and existing data stay unchanged; AI Chat is optional.

UI Builder import migration

UI Builder requires @btst/plugin-cms@1.0.0 and core 6.0.0. Register the CMS backend with UI_BUILDER_CONTENT_TYPE and register the CMS and UI Builder client plugins. UI Builder keeps its uiBuilder runtime ID and uses the CMS API; it does not introduce a backend plugin or require AI Chat. Existing CMS records with the ui-builder-page content type retain their data and query identities.

The existing model and registry types are also available through @btst/plugin-ui-builder/types. Permissions remain owned by @btst/plugin-cms/permissions; import the shared page-context hooks from @btst/stack/page-context when adding optional AI assistance.

School

Install @btst/plugin-school@1.0.0 with @btst/plugin-cms@1.0.0 and core v6. Replace @btst/stack/plugins/school/{api,client,client/hooks,client/components,query-keys,permissions,types,css} with the matching @btst/plugin-school/ entry. Register CMS with SCHOOL_COURSE_CONTENT_TYPE from @btst/plugin-school/api before the School backend. Keep registering the plugin as school and the content type as school-course. Existing courses, learning records, permissions, and query keys retain their identities; no data reset is needed. Payment and certificate hooks keep their existing validation and access rules.

Job Board import migration

Job Board retains its jobBoard runtime ID and the job-posting CMS content type. Install core 6.0.0, @btst/plugin-job-board@1.0.0, CMS and Form Builder packages at 1.0.0. CMS registration remains required; Form Builder registration remains optional. The CLI pins both code dependencies without enabling application forms unless Form Builder is selected. Existing job records, closing dates and routes are preserved; no data reset is required.

Existing model types are also available through @btst/plugin-job-board/types.

Blog

Install @btst/plugin-blog@1.0.0 with Core 6.0.0 (supported range >=6.0.0 <7.0.0). Replace each public import prefix below:

Keep the blog registration ID, blog: permissions, routes and query keys. The post, tag and postTag model/table identities and serialized dates stay unchanged; extraction needs no data reset or schema migration. Blog requires neither Newsletter nor AI Chat nor @btst/components. Its optional editPostAction override remains a generic React slot. Page-context hooks come from @btst/stack/page-context.

ESM and CommonJS backend entries remain supported. CommonJS browser editor bundles need Milkdown's import condition; follow the exact Blog bundler configuration. Native Node loading of Markdown UI is unsupported; the API works without loading that UI.

Optional standalone components

Install @btst/components@1.0.0 for the existing standalone APIs. Neither core nor plugin packages require this package. It compiles the private reusable UI and needs no BTST runtime or feature-plugin registration. Keep the React Hook Form and Zod peers shared with custom fields and application schemas.

Existing named component and type exports are preserved. Continue importing the Markdown stylesheet through its mapped path; configure Tailwind's source scan as described in Standalone Components. The package does not introduce standalone Kanban or UI Builder APIs.

For CommonJS Markdown consumers, Milkdown Kit 7.23 has import-only subpaths. Use a browser bundler that accepts dependency import conditions; the verified Vite configuration is resolve.conditions: ["module", "browser", "production", "import"]. The package still provides actual CommonJS modules. Native Node require() does not support the Markdown CSS and ESM-only editor dependencies. See the standalone guide for the verified Vite configuration, including aliases that explicitly select the CommonJS entries, styles, and peers.

Affiliate import migration

Install @btst/plugin-affiliate@1.0.0 alongside core v6 (>=6.0.0 <7.0.0).

Existing model types are also available at @btst/plugin-affiliate/types. Keep the affiliate registration ID and permission namespace. Existing affiliate, referralClick, affiliateConversion, affiliateCommission, and affiliatePayout data identities, query keys, opaque attribution cookies and commission/payout safeguards remain unchanged. Server authorization is still required; no other plugin registration or payment processor is required. Protected pages load their data in the browser, as before, and do not add SSG data exports.

Comments

Install @btst/plugin-comments@1.0.0 alongside Core v6. Existing plugin IDs, comment and commentLike tables, routes, permission descriptors, serialized records, and query partitions are preserved; existing data needs no migration. Comments and moderation do not require AI Chat or @btst/components.

Existing model types are also available from @btst/plugin-comments/types.

Newsletter

Install @btst/plugin-newsletter@1.0.0 with core v6. Newsletter works without Blog, AI Chat or @btst/components; its shared editor is included. Existing subscriber/campaign/send tables, permission namespaces, routes and query keys keep their identities. No data reset is required.

Existing Newsletter record types are also available from @btst/plugin-newsletter/types. CampaignSource remains an optional override. When both packages are installed, import NewsletterAction and BlogCampaignSource from @btst/plugin-newsletter/client/blog-integration and pass them as Blog’s editPostAction and Newsletter’s CampaignSource overrides. The CLI wires this only when both plugins are selected. See manual composition. Blog is an optional Newsletter peer; neither standalone setup requires the other.

Analytics import migration

Install @btst/plugin-analytics@1.0.0 with Core v6. Continue registering analytics; routes, permission descriptors, query partitions and existing pageView/customEvent tables retain their identities. The daily session hash secret remains application-owned. No data reset or schema migration is required.

Existing model and dashboard types are also available from @btst/plugin-analytics/types. Dashboard queries remain dynamic and protected; server registration does not fetch private dashboard data during static builds.

Feature Flags

Install @btst/plugin-feature-flags@1.0.0 with Core v6 and retain the canonical featureFlags registration ID. Existing flag records, deterministic rollout assignments, targeting, routes, permissions and query partitions are unchanged. Neither AI Chat nor the standalone Components package is required.

Existing flag, context and input types are also available from @btst/plugin-feature-flags/types. /evaluate remains pure and edge-safe; management pages stay dynamic and protected, with no new static data API.

Calendar import migration

Install @btst/plugin-calendar@1.0.0 with core v6 (>=6.0.0 <7.0.0).

Existing model types are also available at @btst/plugin-calendar/types. Keep the calendar registration ID, routes and permission namespace. Existing calendarHost, calendarEventType and calendarBooking records remain in place; no data reset or schema migration is required by this extraction. Other feature packages and standalone components are not required.

Open API import migration

Install @btst/plugin-open-api@1.0.0 alongside Core v6. Its backend-only API keeps canonical registration ID openApi, schema path /open-api/schema, configurable reference path and existing public infrastructure access. No database tables, client plugin or stylesheet are added; other feature packages are optional.

This entry retains openApiBackendPlugin, generateOpenAPISchema, OpenAPIOptions, ScalarTheme and OpenApiRouter, with ESM/CommonJS JavaScript and declarations. The optional Scalar reference still loads its upstream browser script from jsDelivr. Restrict the documentation endpoints at the framework boundary if their metadata should be private; documented application operations retain their own authorization and validation.

Route Docs

Install @btst/plugin-route-docs@1.0.0 with Core 6.0.0. Keep the canonical routeDocs registration and existing /route-docs route. Route Docs introspects the selected client definitions and preserves their sitemap entries; it adds no backend plugin, data tables or required feature registrations.

The client entry retains routeDocsClientPlugin, getRegisteredRoutes, useRegisteredRoutes, generateSchema, ROUTE_DOCS_QUERY_KEY and its public schema/configuration types. Existing private generator source is not a new public entry. The supported Core peer range is >=6.0.0 <7.0.0.