[v3 docs] Turn the v2-to-v3 guide into a production migration and verification playbook

[olliethedev]

Parent

• Phase 3d: publish and validate the v3 release candidate #153

Migration experience

The RC2 v2-to-v3 breaking-changes guide correctly captures the main architectural shift: framework entry factories own catch-all routes, StackProvider owns browser router/API/auth services, and plugin overrides return to plugin-specific customization.

A representative migration of an established Next.js and Prisma application confirmed that this design materially improves steady-state development:

• 34 repeated router/API/auth/identity fields were removed from plugin overrides;
• the primary provider layout fell from 204 to 158 lines;
• the catch-all route fell from 22 lines to 6;
• the hand-written application/library migration was a net reduction of 96 source lines;
• createNextPage replaced manual matching, loader ordering, dehydration, metadata, and 404 handling while retaining request-aware session/header support; and
• 48 declared plugin and host surfaces, 69 route/role pairs, representative CRUD flows, SSR, SSG/ISR, and a production build passed against RC2 with no migration regression.

The same exercise also showed that completing the migration required knowledge that was not obvious from the primary sequence alone: selecting the companion package cohort, understanding the client/server authorization split, avoiding empty override activation folklore, preserving richer identity types, keeping instance-specific comment return URLs, ordering Better Auth's cookie bridge last, and validating embedded components outside the main catch-all layout.

The existing guide is a strong API diff. The next improvement is to make it sufficient as an end-to-end production migration and verification playbook.

Problem

A syntax-focused guide can produce compiling code while leaving important behavioral regressions undiscovered. Existing applications commonly include more than the generated happy path:

• request-aware authenticated SSR;
• dedicated wrapper routes that delegate to BTST pages;
• plugin components embedded on public pages;
• several independent StackProvider roots;
• client presentation policy plus authoritative lifecycle hooks;
• per-resource sign-in return URLs;
• Better Auth plugins and cookie/session refresh behavior;
• database adapters and existing records; and
• production SSG/ISR and optimized builds.

The migration guide should tell adopters both how to transform the integration and how to prove that the transformed application still behaves correctly. It must also clearly separate required migration work from optional cleanup and from application-specific abstractions.

What to build

Expand the existing v2-to-v3 guide into a staged, copyable migration and verification path. Keep the current concise API diffs, then add the production concerns discovered by real RC2 upgrades.

The guide should cover:

1. Preflight and versions — choose a compatible package cohort, record the baseline, install cleanly, and understand prerelease dist-tags.
2. Framework entry points — adopt API/page factories, including request-aware Next.js clients and dedicated wrapper pages that need synthetic route params.
3. Provider services — move router/API/auth concerns once, explain zero-customization providers, and leave only true plugin customization in overrides.
4. Authentication and authorization — define identity, explain client presentation versus server enforcement, reuse policy safely, and preserve record-aware lifecycle checks.
5. Embedded surfaces — migrate comments, forms, direct hooks, cards, and other exported components that live outside the primary BTST layout.
6. Auth bridge details — document session refresh, per-instance sign-in return URLs, and required Better Auth plugin ordering such as placing nextCookies() last.
7. Plugin-specific breaking changes — parameterized page-component context, removed render guards/props, lifecycle denial semantics, and renamed hooks.
8. Verification — clean install, typecheck, lint, schema generation/migration, optimized build, production start, browser console/hydration checks, authorization roles, and representative plugin mutations.
9. Cleanup — identify compatibility wrappers and duplicated v2 wiring that should disappear, while clearly marking optional application-owned refactors.

Use stable terminology and link to focused API/plugin references rather than duplicating every reference table inline.

Definition of success

A developer who did not participate in v3 design can migrate a non-trivial v2 application using only the published guide and normal package documentation. They should not need to inspect BTST source, search release-tracker comments, or copy a retained audit lockfile.

Success is demonstrated by a second clean migration exercise in which:

• the dependency graph installs without manual peer repair;
• the application typechecks and builds on the first documented path;
• request-aware authenticated SSR uses the factory rather than a hand-written rendering pipeline;
• shared provider boilerplate decreases rather than moves elsewhere;
• anonymous, user, and administrator outcomes remain correct;
• embedded components retain API, identity, and return-URL behavior; and
• the migration produces no browser console errors, hydration errors, or authorization surprises in production mode.

The guide should set an explicit expectation that v3 improves both lines of integration code and the number of concepts each plugin consumer must understand.

Acceptance criteria

• The existing v2-to-v3 page is retained as the canonical guide and expanded rather than replaced by a competing document.
• A staged checklist covers preflight, install, code migration, data/schema checks, behavioral verification, production verification, and cleanup.
• Version instructions consume the compatibility contract from [v3 install] Publish and test the companion-version compatibility contract #174 and show both stable and prerelease installation paths.
• Provider examples reflect [v3 DX] Make zero-customization StackProvider usage unambiguous #171 and never imply that empty override blocks activate plugins.
• Auth examples reflect [v3 auth] Preserve application identity types across client and server auth #172 and [v3 auth] Make can() a typed full-stack authorization contract #173, including a typed shared identity/policy and an authoritative request-scoped server check.
• The guide links [v3 RC2] CommentThread ignores delete permission and surfaces failed owner action #169's corrected behavior or resulting documentation so first-party permission-sensitive controls and backend denials are presented consistently.
• The request-aware Next.js example includes incoming headers/session resolution and explains how dedicated wrapper pages can delegate to the same page factory.
• Embedded component migration explicitly covers comments, form rendering/direct submission hooks, and read-only cards or counts outside the main pages layout.
• Per-instance loginHref precedence and resource-specific return URLs/anchors are called out as behavior to preserve.
• Better Auth integration states that nextCookies() must be last when other plugins may set cookies and explains the observable failure mode.
• Backend migration distinguishes thrown hook denial from transformed return values and uses the supported v3 hook names.
• The verification matrix includes anonymous, regular-user, and privileged-user checks for both rendered controls and backend responses.
• The production checklist includes optimized build/start, SSR, SSG/ISR, direct navigation, refresh, back/forward, console errors, hydration, and 404/error-boundary behavior.
• A clean-room migration or generated fixture follows the guide without undocumented edits; any failure feeds back into the guide before the next RC is published.
• Documentation links and code samples are covered by the docs build and any available snippet/typecheck validation.

Blocked by

• [v3 RC2] CommentThread ignores delete permission and surfaces failed owner action #169
• [v3 DX] Make zero-customization StackProvider usage unambiguous #171
• [v3 auth] Preserve application identity types across client and server auth #172
• [v3 auth] Make can() a typed full-stack authorization contract #173
• [v3 install] Publish and test the companion-version compatibility contract #174