Merge pull request #281 from better-stack-ai/upgrade/upstream-auth-20260929

Upgrade BTST to Better Auth 1.7 and companion UI 3

Author: olliethedev

.github/actions/pack-auth-ui/action.yml

@@ -0,0 +1,29 @@
+name: Pack Better Auth UI
+description: Build the pinned companion source for coordinated release consumers.
+outputs:
+  tarball:
+    description: Absolute path to the packed companion.
+    value: ${{ steps.pack.outputs.tarball }}
+runs:
+  using: composite
+  steps:
+    - name: Checkout Better Auth UI
+      uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      with:
+        repository: better-stack-ai/better-auth-ui
+        ref: 29e8dd41b50f1382f968078630aa00f15137a8ab # 3.0.0 companion candidate
+        path: .packed-consumer/better-auth-ui
+    - name: Install and build Better Auth UI
+      shell: bash
+      working-directory: .packed-consumer/better-auth-ui
+      run: |
+        corepack pnpm@10.26.2 install --ignore-workspace --frozen-lockfile
+        corepack pnpm@10.26.2 build
+    - name: Pack Better Auth UI
+      id: pack
+      shell: bash
+      working-directory: .packed-consumer/better-auth-ui
+      run: |
+        mkdir -p "$RUNNER_TEMP/better-auth-ui"
+        tarball="$(npm pack --quiet --pack-destination "$RUNNER_TEMP/better-auth-ui")"
+        echo "tarball=$RUNNER_TEMP/better-auth-ui/$tarball" >> "$GITHUB_OUTPUT"

.github/workflows/init.yml

@@ -43,11 +43,16 @@ jobs:
       - name: Verify historical Next.js migration hashes
         run: pnpm --filter @btst/codegen legacy-next-hashes:check
 
+      - name: Pack pinned Better Auth UI
+        id: pack-auth-ui
+        uses: ./.github/actions/pack-auth-ui
+
       - name: Run init harness
         working-directory: packages/cli
         run: bash scripts/test-init.sh
         timeout-minutes: 20
         env:
+          BTST_AUTH_UI_TARBALL: ${{ steps.pack-auth-ui.outputs.tarball }}
           CI: true
 
       - name: Upload artifacts on failure
@@ -79,9 +84,14 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Pack pinned Better Auth UI
+        id: pack-auth-ui
+        uses: ./.github/actions/pack-auth-ui
+
       - name: Run packed framework fixtures
         run: pnpm --filter @btst/codegen test:better-auth-ui-fixtures
         env:
+          BTST_AUTH_UI_TARBALL: ${{ steps.pack-auth-ui.outputs.tarball }}
           BTST_KEEP_FIXTURES: 1
           CI: true
 

.github/workflows/packed-consumers.yml

@@ -59,13 +59,6 @@ jobs:
       - name: Checkout Better Stack
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
-      - name: Checkout Better Auth UI
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          repository: better-stack-ai/better-auth-ui
-          ref: f5f4f36fdeeb6060c7f95dce6706a3559bdbe5b7 # 2.0.1 companion
-          path: .packed-consumer/better-auth-ui
-
       - name: Setup pnpm
         uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4.1.0
 
@@ -78,19 +71,9 @@ jobs:
       - name: Install Better Stack workspace dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Install and build Better Auth UI
-        working-directory: .packed-consumer/better-auth-ui
-        run: |
-          corepack pnpm@10.26.2 install --ignore-workspace --frozen-lockfile
-          corepack pnpm@10.26.2 build
-
-      - name: Pack Better Auth UI
+      - name: Pack pinned Better Auth UI
         id: pack-auth-ui
-        working-directory: .packed-consumer/better-auth-ui
-        run: |
-          mkdir -p "$RUNNER_TEMP/better-auth-ui"
-          tarball="$(npm pack --quiet --pack-destination "$RUNNER_TEMP/better-auth-ui")"
-          echo "tarball=$RUNNER_TEMP/better-auth-ui/$tarball" >> "$GITHUB_OUTPUT"
+        uses: ./.github/actions/pack-auth-ui
 
       - name: Test harness
         run: pnpm test:packed-consumers

README.md

@@ -52,13 +52,13 @@ Render the generated `<Toaster />` in your root layout and start from a clean co
 Run the released generator from the application root:
 
 ```bash
-pnpm dlx @btst/codegen@0.2.1 init \
+pnpm dlx @btst/codegen@4.0.0 init \
   --framework nextjs \
   --adapter memory \
   --plugins blog
 ```
 
-The generator shows detected-file and conflict prompts before it writes. It installs `@btst/stack@3.0.2`, `next-themes@0.4.6`, registers Blog on the backend and client, mounts the API and page routes, adds the plugin CSS, and wires the shared provider.
+The generator shows detected-file and conflict prompts before it writes. It installs `@btst/stack@4.0.0`, `next-themes@0.4.6`, registers Blog on the backend and client, mounts the API and page routes, adds the plugin CSS, and wires the shared provider.
 
 Set the trusted local origins in `.env.local`:
 

docs/content/docs/breaking-changes.mdx

@@ -10,6 +10,59 @@ This page documents breaking changes between major versions and provides migrati
 
 ---
 
+## v3 → v4: Better Auth 1.7 and Better Auth UI 1.7
+
+BTST v4 uses Better DB 3, rebased onto Better Auth 1.7.6. The optional
+`@btst/better-auth-ui` 3 plugin packages upstream Better Auth UI 1.7.26
+React/shadcn components and connects them to BTST routing and shared services.
+Existing BTST backend plugins and framework entry factories retain their APIs.
+
+Upgrade the packages together:
+
+| Package | Version |
+| --- | --- |
+| `@btst/stack`, `@btst/codegen` | `4.0.0` |
+| `@btst/db`, selected `@btst/adapter-*`, `@btst/cli` | `3.0.0` |
+| Optional `@btst/better-auth-ui` | `3.0.0` |
+| `better-auth`, `@better-auth/core` | `1.7.6` |
+| `@better-auth/utils` | `0.4.2` |
+| `@better-fetch/fetch` | `1.3.2` |
+| `better-call` | `1.4.0` |
+| React and React DOM | `>=19.2.6` |
+| Tailwind CSS and its PostCSS/Vite integration | `>=4.3.2` |
+| `@tanstack/react-query`, `@tanstack/query-core` | `5.102.0` |
+
+For example, a Drizzle application can install the core cohort with:
+
+```bash
+pnpm add --save-exact @btst/stack@4.0.0 @btst/adapter-drizzle@3.0.0 \
+  better-auth@1.7.6 @better-auth/core@1.7.6 \
+  @better-auth/utils@0.4.2 @better-fetch/fetch@1.3.2 better-call@1.4.0
+pnpm add --save-dev --save-exact @btst/codegen@4.0.0
+```
+
+Use Drizzle ORM `^0.45.2` or a compatible 1.0 release candidate supported by
+the adapter. Better Auth moved native joins from `experimental.joins` to
+`advanced.database.joins`; the BTST adapters enable native joins automatically.
+If the application configures this directly on its Better Auth instance, migrate
+that setting too.
+
+Keep React Query and Query Core on the same tested version. The generated
+TanStack Start integration uses `5.102.0`; Query Core `5.104.0` changes hydration
+behavior at the end of its SSR query stream.
+
+The Better Auth UI companion now uses upstream feature plugins. Follow the
+[Better Auth UI companion guide](/plugins/better-auth-ui) to migrate provider
+configuration and select optional features. Applications continue to own their
+Better Auth server, credentials, schema migrations, and authorization policy.
+
+Run the application's typecheck, production build, sign-in/account flows, and
+any enabled organization/admin/billing flows before deployment. Keep the previous
+application artifact and lockfile available while verifying production. The
+older version tables below describe their historical migrations.
+
+---
+
 ## v2 or release candidate → stable v3: production playbook
 
 Use this section as the canonical migration order for a production application.

docs/content/docs/cli.mdx

@@ -13,7 +13,7 @@ BTST has two CLI packages:
 - `@btst/cli` owns low-level DB schema generation and migrations
 
 `@btst/codegen generate` and `@btst/codegen migrate` run the aligned
-`@btst/cli@2.2.4` release in isolation. This avoids adding its dependency graph
+`@btst/cli@3.0.0` release in isolation. This avoids adding its dependency graph
 or competing `btst` binary to the application. The delegated CLI still loads
 the configuration, environment files, aliases, Better Auth adapter, and ORM
 peers from the application directory.
@@ -71,7 +71,7 @@ npx @btst/codegen migrate --config=lib/stack.ts --database-url=postgres://...
 ```
 
 When a delegated command fails, fix the underlying issue and run the equivalent
-`npx @btst/cli@2.2.4 ...` command directly.
+`npx @btst/cli@3.0.0 ...` command directly.
 
 ## About Better DB
 
@@ -83,7 +83,7 @@ For v3 applications, prefer the codegen passthrough commands above. If a v2
 application lists `@btst/cli` in its dependencies, remove it during migration;
 the pinned one-off CLI keeps Better DB dependencies from polluting the consumer
 graph. You can still invoke the low-level CLI directly with
-`npx @btst/cli@2.2.4`.
+`npx @btst/cli@3.0.0`.
 
 ## Parameters
 
@@ -101,13 +101,13 @@ Generate database schemas for your ORM from your BTST `dbSchema`:
 <Tabs items={["prisma", "drizzle", "kysely"]}>
   <Tab value="prisma">
     ```bash
-    npx @btst/cli@2.2.4 generate --config=lib/stack.ts --orm=prisma --output=schema.prisma
+    npx @btst/cli@3.0.0 generate --config=lib/stack.ts --orm=prisma --output=schema.prisma
     ```
   </Tab>
 
   <Tab value="drizzle">
     ```bash
-    npx @btst/cli@2.2.4 generate --config=lib/stack.ts --orm=drizzle --output=src/db/schema.ts
+    npx @btst/cli@3.0.0 generate --config=lib/stack.ts --orm=drizzle --output=src/db/schema.ts
     ```
   </Tab>
 
@@ -117,17 +117,17 @@ Generate database schemas for your ORM from your BTST `dbSchema`:
     **Using DATABASE_URL environment variable:**
 
     ```bash
-    DATABASE_URL=sqlite:./dev.db npx @btst/cli@2.2.4 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql
+    DATABASE_URL=sqlite:./dev.db npx @btst/cli@3.0.0 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql
     ```
 
     **Or using --database-url flag:**
 
     ```bash
-    npx @btst/cli@2.2.4 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql --database-url=sqlite:./dev.db
+    npx @btst/cli@3.0.0 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql --database-url=sqlite:./dev.db
     ```
 
     ```bash
-    npx @btst/cli@2.2.4 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql --database-url=postgres://user:pass@localhost:5432/db
+    npx @btst/cli@3.0.0 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql --database-url=postgres://user:pass@localhost:5432/db
     ```
   </Tab>
 </Tabs>
@@ -140,25 +140,25 @@ Migrate your database schema directly (Kysely only). For Prisma and Drizzle, use
 **Using DATABASE_URL environment variable:**
 
 ```bash
-DATABASE_URL=sqlite:./dev.db npx @btst/cli@2.2.4 migrate --config=lib/stack.ts
+DATABASE_URL=sqlite:./dev.db npx @btst/cli@3.0.0 migrate --config=lib/stack.ts
 ```
 
 **Or using --database-url flag:**
 
 ```bash
-npx @btst/cli@2.2.4 migrate --config=lib/stack.ts --database-url=sqlite:./dev.db
+npx @btst/cli@3.0.0 migrate --config=lib/stack.ts --database-url=sqlite:./dev.db
 ```
 
 ```bash
-npx @btst/cli@2.2.4 migrate --config=lib/stack.ts --database-url=postgres://user:pass@localhost:5432/db
+npx @btst/cli@3.0.0 migrate --config=lib/stack.ts --database-url=postgres://user:pass@localhost:5432/db
 ```
 
 ### Generate SQL to File
 
 Instead of running migrations directly, generate SQL to a file:
 
 ```bash
-npx @btst/cli@2.2.4 migrate --config=lib/stack.ts --output=migrations.sql --database-url=sqlite:./dev.db
+npx @btst/cli@3.0.0 migrate --config=lib/stack.ts --output=migrations.sql --database-url=sqlite:./dev.db
 ```
 
 ## Project config loading
@@ -179,5 +179,5 @@ project context as the application:
 You can still override a value for one command:
 
 ```bash
-SOME_VAR=value npx @btst/cli@2.2.4 generate --config=lib/stack.ts --orm=prisma --output=schema.prisma
+SOME_VAR=value npx @btst/cli@3.0.0 generate --config=lib/stack.ts --orm=prisma --output=schema.prisma
 ```

docs/content/docs/databases/adapters.mdx

@@ -89,7 +89,7 @@ The memory adapter remains useful for local, single-process development where
 the plugin documents serialized access. It is not a production isolation
 substitute. The generated scaffold rejects Form Builder with memory or MongoDB
 and Media with MongoDB; use Prisma, Drizzle, or Kysely for those production
-configurations. `@btst/codegen@0.2.0 init` adds `transaction: true`
+configurations. `@btst/codegen@4.0.0 init` adds `transaction: true`
 automatically for all four atomic-write plugins: AI Chat, Form Builder, Kanban,
 and Media.
 

docs/content/docs/installation.mdx

@@ -25,7 +25,8 @@ choice.
 ### Quickstart prerequisites
 
 - Node.js 22 and an existing Next.js App Router application
-- shadcn/ui initialized with CSS variables and Tailwind configured
+- React and React DOM 19.2.6 or newer
+- shadcn/ui initialized with CSS variables and Tailwind CSS 4.3.2 or newer
 - 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
@@ -56,7 +57,7 @@ below lists them explicitly.
 Run this command from the existing application root:
 
 ```bash
-npx @btst/codegen@0.2.1 init \
+npx @btst/codegen@4.0.0 init \
   --framework nextjs \
   --adapter memory \
   --plugins blog