[v3 stable] Restore the Better Auth UI CLI scaffold and documentation

[olliethedev]

Stable-v3 cohort correction — 2026-08-31

The generated auth-plus-account scaffold must consume the corrected companion candidate from better-auth-ui#22, not @btst/better-auth-ui@2.0.0-rc.3 on Better Auth 1.7.2.

The scaffold and manual-install path must select the exact Better Auth 1.6.16 cohort recorded by #244 and tested by #174 while leaving @btst/db@2.2.3 and the 2.2.3 adapters unchanged. It must configure transaction: true explicitly when generated plugin choices require atomic writes; it still must not generate or own the Better Auth backend or database schema.

The completed better-auth-ui#20 remains the source of the bridge, route, session, and override design. Better-auth-ui#22 changes the supported v3 dependency cohort and publishes the immutable corrected candidate.

---

This was generated by AI during triage.

Current status — 2026-08-31

Both implementation dependencies are satisfied: core #202 is complete, and better-auth-ui#20 shipped through PR #21. RC3 was deliberately published without restoring this optional scaffold.

This issue is now a stable-v3 integration gate, not an RC3 publication blocker. Its product boundary is unchanged:

• optional auth-plus-account generation only;
• one browser Better Auth client pointed at an existing endpoint;
• no generated Better Auth backend, database, schema, providers, migrations, or secrets;
• organization and other features remain explicit opt-ins;
• resolved site routes, inferred overrides, and explicit framework-native session refresh; and
• packed Next.js, React Router, and TanStack consumer builds.

Use the newest candidate artifacts available when implementing the fixtures. #170 closes only after this scaffold/docs path proves the exact public override contract, and #174 may reuse these fixtures for its npm/pnpm packed-install coverage. Historical references below to “packed RC3 artifacts” should be read as the current release-candidate artifacts.

---

Parent

• [v3] Resolve RC3 findings and publish stable v3 #153

What to build

Restore @btst/better-auth-ui as an officially maintained, optional companion in the BTST CLI catalog and documentation after better-stack-ai/better-auth-ui#20 has migrated the package to the final runtime produced by #202.

The generated integration must be deliberately small. Selecting Better Auth UI installs and registers the companion's auth and account client plugins, creates only the browser Better Auth client needed by those plugins, and points the application at an existing Better Auth endpoint. It must not generate, own, or configure a Better Auth backend, database adapter, schema, migrations, authentication providers, secrets, or environment-specific production infrastructure.

This restores the first-class integration removed during the RC2-to-RC3 cleanup without coupling @btst/stack core to Better Auth. Better Auth remains an application prerequisite and @btst/better-auth-ui remains a separately maintained companion repository.

Intended generated boundary

The exact syntax must follow the API that lands in #202, but the generated result must preserve this ownership:

const stack = createClientStack({
  api: { baseURL, basePath: "/api/data" },
  site: { baseURL, basePath: "/pages" },
  queryClient,
  plugins: {
    auth: authClientPlugin(),
    account: accountClientPlugin(),
  },
})

<StackProvider
  stack={stack}
  router={router}
  overrides={{
    auth: {
      authClient,
      onSessionChange: () => refreshThroughTheFramework(),
    },
  }}
>
  {children}
</StackProvider>

The CLI may adapt names and framework helpers to the final #202 surface. It must not reintroduce duplicated API/site/query configuration, a hand-written provider override map, Better Auth-to-BTST identity factories, or Better Auth permission translation.

Required behavior

• Better Auth UI appears as an optional CLI/catalog choice; it is not forced into applications that do not select it.
• The default generated plugin set is auth plus account only.
• Organization, API-key, passkey, multi-session, and other Better Auth extensions are opt-in because they require matching Better Auth server/client plugins.
• The scaffold creates a minimal Better Auth browser client module and connects it to the auth override once.
• The scaffold assumes an existing Better Auth API endpoint. It does not generate the server, database, schema, migrations, environment variables, providers, or secrets.
• Better Auth UI manages its own session and native permissions. BTST authorization remains optional, provider-agnostic, and application-owned.
• Framework-native session synchronization is explicit: Next.js refresh, React Router revalidation, or TanStack Router invalidation. The generated bridge performs no hidden BTST identity refetch.
• Routes and links derive from the [v3 RC3 DX] Centralize client runtime configuration and normalize all plugin interfaces #202 resolved site runtime. The scaffold accepts no independent auth/account route base path that can drift from registration.
• Account avatar customization, when documented, appears only at account.avatar.
• Documentation identifies the companion repository, its release line, Better Auth prerequisite, supported dependency cohort, and optional-adapter peer requirements.

Installation and release-gate fixtures

Add generated clean-install fixtures for all three supported frameworks:

1. Next.js;
2. React Router;
3. TanStack Router/Start, using the repository's supported generated target.

Each fixture must be generated from the maintained CLI/template path, install the packed current candidate artifacts rather than workspace links, and use the exact retained Better Auth 1.6.16 compatibility contract from #174. Exercise both npm and pnpm across the release gate; the division of the package-manager matrix between this issue and #174 may be shared, but the combined gate must cover every generated framework with a clean install and production build.

The fixtures need only prove integration, declarations, routing, bundling, and production builds. They do not need a live Better Auth database or real sign-in flow; post-publication real-project validation is tracked separately and does not block RC3.

Acceptance criteria

• [v3 RC3 DX] Centralize client runtime configuration and normalize all plugin interfaces #202 is merged and the implementation uses its final constructor, runtime, plugin-ID, override-inference, and provider contracts.
• better-stack-ai/better-auth-ui#20 remains the completed bridge/API baseline, and the scaffold consumes the corrected cohort candidate from better-stack-ai/better-auth-ui#22.
• Better Auth UI is restored to the optional CLI/catalog selection and relevant registry/catalog artifacts are reproducible.
• The default scaffold registers only auth and account.
• The generated code creates only a Better Auth browser client and clearly marks the existing Better Auth endpoint seam.
• No Better Auth server, database adapter, schema, migration, provider, secrets, or generic BTST auth adapter is generated or owned by core.
• Organization and other Better Auth extensions are documented and generated only when explicitly selected/configured.
• Generated provider/runtime code follows [v3 RC3 DX] Centralize client runtime configuration and normalize all plugin interfaces #202: shared API/site/query configuration appears once and override types are inferred.
• Better Auth UI's own session/native permission boundary is documented; no removed Better Auth-to-BTST authorization factory appears.
• Session changes use explicit framework-native refresh/revalidation/invalidation examples.
• Route bases derive from the resolved site runtime and avatar is documented only under account.
• Next.js, React Router, and TanStack generated fixtures clean-install, type-check, and production-build from packed artifacts.
• The coordinated npm/pnpm matrix is peer-clean under the definitions in Add packed npm/pnpm compatibility smoke tests #174.
• Docs, CLI help, manual installation instructions, generated examples, and compatibility links tell the same minimal story.
• Full build, typecheck, lint, registry generation/checks, CLI/init smoke tests, and three-framework codegen E2E checks pass.

Out of scope

• Implementing or maintaining Better Auth itself.
• Generating a Better Auth backend, database integration, schema, migration, auth provider, secret, or deployment configuration.
• Adding Better Auth dependencies or provider-specific authorization helpers to @btst/stack core.
• Enabling organization, API-key, passkey, multi-session, or optional data adapters by default.
• Running live authentication or application database validation before publication.

Blocked by

• [v3 RC3 DX] Centralize client runtime configuration and normalize all plugin interfaces #202 — final core client runtime and normalized plugin/provider interface.
• better-stack-ai/better-auth-ui#20 — completed migrated companion bridge and exact override contracts.
• better-stack-ai/better-auth-ui#22 — corrected companion candidate aligned to the retained Better Auth 1.6.16 database cohort.

Real-project validation in Better Stack Web and Bio Mogging starts only after the coordinated RC3 packages are public and does not block this issue or RC3 publication.

[olliethedev]

Completed by PR #252: #252

Final evidence:

• Squash merge: 48324dbfd40000b2906c24d292c4563a1345e224.
• The optional better-auth-ui selection now generates only the auth/account UI seam and one browser client pointed at the existing /api/auth backend; it does not generate a Better Auth backend, database/schema, providers, secrets, or organization runtime.
• Generated Next.js, React Router, and TanStack packed fixtures install with strict peers, compile, and production-build against public @btst/better-auth-ui@2.0.0-rc.4 and the retained Better Auth 1.6.16 cohort.
• Packed fixture workflow passed: https://github.com/better-stack-ai/better-stack/actions/runs/33450708155
• Monorepo CI passed: https://github.com/better-stack-ai/better-stack/actions/runs/33450708033
• All three Codegen E2E jobs passed: https://github.com/better-stack-ai/better-stack/actions/runs/33450708157
• Two independent review passes (spec and repository standards) reported no findings.

Closing as complete.