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.
This guide covers @btst/better-auth-ui@2.0.0 alongside BTST 3.0.2. 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 companion reference defines the supported package group.
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:
| Package | Compatible version |
|---|---|
@btst/better-auth-ui | 2.0.0 |
better-auth, @better-auth/core | 1.6.16 |
@better-auth/api-key, @better-auth/passkey | 1.6.16 |
@better-auth/utils | 0.4.1 |
@better-fetch/fetch | 1.2.2 |
better-call | 1.3.6 |
These are compatibility pins for this release, not a claim that they are the newest versions of each package. In particular, the companion's supported configuration does not combine this group with Better Auth 1.7. If an existing app already uses another Better Auth version, assess that compatibility before changing its backend dependency tree.
Generate or install the supported configuration#
From a clean commit in an existing supported framework project, explicitly select the companion:
npx @btst/codegen@0.2.1 init --plugins better-auth-ui
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@2.0.0 \
better-auth@1.6.16 @better-auth/core@1.6.16 \
@better-auth/api-key@1.6.16 @better-auth/passkey@1.6.16 \
@better-auth/utils@0.4.1 @better-fetch/fetch@1.2.2 better-call@1.3.6
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 2.0.0. 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. Optional data integrations also have their own subpaths and peers; avoid importing one merely to remove an unrelated installation error.
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@2.0.0 peerDependencies peerDependenciesMeta --json
npm ls 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. npm documents this behavior in its installation reference. 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.