BTST Better Auth UI: Resolve Peer Dependencies with Compatible Versions
Use the stable companion dependency cohort, distinguish required declaration peers from enabled features, and verify a clean installation.
An authentication UI can fail to install before your app ever sends a sign-in request. When npm reports incompatible peers, start with the package versions in the dependency tree. Changing routes, cookies, or providers cannot resolve an installation conflict.
Updated October 1, 2026: this guide covers @btst/better-auth-ui@3.0.1 alongside BTST 4.2.0. The companion adds auth and account pages to an application that already runs Better Auth. Its version number is independent of the core stack's version. The published 3.0.1 manifest defines its peer requirements. If your app still uses companion 2.x and Stack 3, review the version 3 migration guide before changing the dependency tree.
Identify the package before following an example#
@btst/better-auth-ui, @btst/stack, and other packages named Better Auth UI are different dependencies. Check the exact import and package name in the error. An example written for another package or an earlier BTST release may have different provider props, imports, and peer requirements.
For this companion release, retain these versions together:
@btst/better-auth-ui: 3.0.1.@btst/stack: 4.2.0 in this guide; the companion accepts^4.0.0.better-authand@better-auth/core: 1.7.6.@better-auth/api-keyand@better-auth/passkey: 1.7.6.@better-auth/utils: 0.4.2.@better-fetch/fetch: 1.3.2.better-call: 1.4.0.
These are the auth pins used by Codegen 4.2.0, not a claim that every package is the newest available. Companion 3.0.1 requires Better Auth 1.7.6 exactly; do not substitute 1.6.x or another 1.7 patch merely because the version looks close. Stack 4 uses @btst/db and BTST database adapters 3.0.0. Review the adapter migration before changing an existing database integration.
The companion also requires React and React DOM at least 19.2.6, Tailwind CSS at least 4.3.2, @btst/yar compatible with ^1.3.2, and both React Query and Query Core at least 5.101.2. This guide checked React/React DOM 19.2.8 and both TanStack Query packages at 5.102.0. Version numbers across these projects do not need to match each other.
Generate or install the supported configuration#
From a clean commit in an existing supported framework project, explicitly select the companion:
npx @btst/codegen@4.2.0 init --framework nextjs --plugins better-auth-ui
This command selects Next.js; use your framework's generator option for React Router or TanStack Start. Review the generated diff before committing it. The generator includes the pinned auth packages and registers the auth and account client plugins. It assumes the Better Auth backend already exists. Backend setup, migrations, providers, email delivery, and secrets remain application responsibilities; Better Auth's installation guide covers that separate setup.
For a manual integration, the auth portion of the installation is:
pnpm add @btst/better-auth-ui@3.0.1 \
better-auth@1.7.6 @better-auth/core@1.7.6 \
@better-auth/api-key@1.7.6 @better-auth/passkey@1.7.6 \
@better-auth/utils@0.4.2 @better-fetch/fetch@1.3.2 better-call@1.4.0
Use it in a compatible Stack 4 application with the React, Tailwind and Query requirements above already resolved. This command supplements the existing BTST and component-library dependencies. It is not a complete empty-project installation. Consult the published manifest for React, React Query, Zod, and UI peers, and keep React and React DOM compatible with each other.
Required peers do not enable optional features#
The companion's declaration types expose API-key and passkey surfaces, so those packages are required peers in version 3.0.1. Their presence in the lockfile does not mean the generated app has enabled API keys or passkeys.
The minimal generated integration registers auth and account pages. Organization management and other extensions require the matching server and browser-client configuration before their UI is enabled. Version 3 has optional peers for integrations such as SSO, Stripe and OAuth provider. Install and configure one when your app needs it; do not add optional services simply to suppress unrelated warnings. The old companion /tanstack, /instantdb and /triplit entry points were removed in version 3. Do not carry those imports into this release.
Inspect the actual dependency tree#
For an npm project, these read-only commands identify the published requirements and why packages are present:
npm view @btst/better-auth-ui@3.0.1 peerDependencies peerDependenciesMeta --json
npm ls @btst/stack @btst/better-auth-ui better-auth @better-auth/core react react-dom
npm explain better-auth
Read the first conflicting dependency chain in the resolver output. An error mentioning React Email or React DOM may come from a transitive dependency, rather than the package named in your original install command. Preserve the error and lockfile while diagnosing it.
Verify the corrected manifest and lockfile with your package manager's clean-install workflow in a disposable checkout. For an npm project with a current lockfile, npm ci --strict-peer-deps makes peer conflicts fail the check. Use a lockfile created without options that bypass peer validation; npm documents clean installs in its npm ci reference. For pnpm, use pnpm install --frozen-lockfile --strict-peer-dependencies with the corrected lockfile. Avoid treating a forced resolution as evidence that the integration is compatible.
An installation check establishes dependency resolution. A typecheck establishes that your imports and provider props agree. Neither proves a working sign-in flow. Finish with the Next.js integration guide or your framework's generated wiring, then test sign-in, session refresh, account access, and sign-out against your test backend.
The Codegen 4.2.0 package list records the auth pins above. These checks resolve package compatibility; upgrading from companion 2 also changes provider options, extension registration and some page URLs. Follow the migration guide before treating an install as a completed upgrade.