better-auth

library0.0.1b13jsnpmunverified

Better Auth is a comprehensive authentication framework designed for TypeScript applications, supporting various authentication methods like OAuth, OIDC, 2FA, and social logins. The current stable version is 1.6.5, with frequent patch and minor releases, alongside active beta development indicating continuous feature enhancements and bug fixes.

auth-security type-stubs

npm install better-auth

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BETTER-AUTH

better-auth

auth-securityjavascriptv0.0.1b13

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Auth

✓ import { Auth } from 'better-auth';

✗ const Auth = require('better-auth');

Better Auth is designed for modern JavaScript environments and TypeScript, primarily using ESM imports.

This quickstart demonstrates how to initialize Better Auth in a TypeScript project using the Prisma adapter. It sets up the core `Auth` instance with a placeholder secret and hints at basic session retrieval in a server-side context.

import { Auth } from 'better-auth'; import { PrismaAdapter } from '@better-auth/adapter-prisma'; import { PrismaClient } from '@prisma/client'; const prisma = new PrismaClient(); export const auth = new Auth({ adapter: PrismaAdapter(prisma), secret: process.env.AUTH_SECRET ?? 'super-secret-dev-key', // IMPORTANT: Use a strong, unique secret in production providers: [], // Configure your authentication providers here }); // Example usage (e.g., in a Next.js API route): // import { auth } from './auth'; // Adjust path as needed // import type { NextApiRequest, NextApiResponse } from 'next'; // // export default async function handler(req: NextApiRequest, res: NextApiResponse) { // const session = await auth.getSession({ req }); // if (!session) { // return res.status(401).json({ message: 'Unauthorized' }); // } // res.status(200).json({ user: session.user }); // }

Debug

Known issues

breakingThe `enableTwoFactor` function now requires a `method` parameter (`'otp' | 'totp'`) and returns a discriminated response object with a `method` field. If `method: 'otp'` is used, `otpOptions.sendOTP` must be configured on the server.

fix

Update calls to `enableTwoFactor` to provide the `method` parameter and handle the new discriminated return type. Ensure `otpOptions.sendOTP` is configured for OTP method.

affects: >=1.7.0-beta.0

breakingThe `twoFactor` database table now requires a `verified` column. Failing to add this column will prevent TOTP enrollment from working correctly and may lead to schema migration errors.

fix

Add a `verified` column to your `twoFactor` database table. Regenerate and apply your ORM migration (e.g., `npx prisma migrate dev` for Prisma or `npx drizzle-kit push` for Drizzle) and then `npx auth@latest generate`.

affects: >=1.6.2

breakingThe `session.freshAge` calculation now aligns with the session's `createdAt` timestamp instead of `updatedAt`. This change impacts how fresh sessions are determined, potentially affecting session validity logic.

fix

Review any custom logic relying on `session.freshAge`. If you need to disable the fresh session check entirely, set `session: { freshAge: 0 }` in your Auth configuration.

affects: >=1.6.0

gotcha2FA enforcement scope was temporarily reverted in `v1.6.4` to apply only to credential sign-in paths. This meant magic link, email OTP, OAuth, SSO, and passkey flows would bypass 2FA challenges in that version.

fix

This issue was fixed in `v1.7.0-beta.1` and later to apply 2FA across all sign-in paths. Upgrade to the latest stable version or a `v1.7.0-beta.x` release if comprehensive 2FA enforcement is required.

affects: 1.6.4

Errors

Common errors & fixes

Column 'verified' does not exist on table 'twoFactor'

The required `verified` column for the `twoFactor` table, introduced in v1.6.2, is missing from your database schema.

fix

Run `npx auth@latest generate` to update your ORM client, then apply the schema migration using your ORM's command (e.g., `npx prisma migrate dev` or `npx drizzle-kit push`).

AuthError: AUTH_SECRET is not defined

The `AUTH_SECRET` environment variable is not set, which is critical for encrypting and signing session tokens, making the application insecure.

fix

Define the `AUTH_SECRET` environment variable in your application's environment (e.g., `.env` file) with a long, randomly generated string. Do not hardcode secrets in your codebase.

TypeError: auth.getSession is not a function

This error can occur if the `auth` instance is not correctly initialized or if `getSession` is called without the expected request context (e.g., `req`).

fix

Ensure `auth` is properly instantiated and exported. When calling `getSession` server-side, pass the relevant request object, e.g., `await auth.getSession({ req })`.

AuthError: Invalid OTP method specified.

The `enableTwoFactor` function was called without a valid `method` parameter or with an unsupported method, following the breaking change in `v1.7.0-beta.0`.

fix

Update your `enableTwoFactor` calls to explicitly specify the `method` as either `'otp'` or `'totp'`, e.g., `auth.enableTwoFactor({ method: 'totp' })`.

Upgrade

Version history

0.0.1b13latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

52 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/better-auth/better-auth ↗

packagehttps://www.npmjs.com/package/better-auth ↗

homepagehttps://better-auth.com ↗