{"id":10379,"library":"better-auth","title":"Better Auth","description":"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.","status":"active","version":"1.6.5","language":"javascript","source_language":"en","source_url":"https://github.com/better-auth/better-auth","tags":["javascript","auth","oauth","oidc","2fa","social","security","typescript","nextjs"],"install":[{"cmd":"npm install better-auth","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Better Auth is designed for modern JavaScript environments and TypeScript, primarily using ESM imports.","wrong":"const Auth = require('better-auth');","symbol":"Auth","correct":"import { Auth } from 'better-auth';"}],"quickstart":{"code":"import { Auth } from 'better-auth';\nimport { PrismaAdapter } from '@better-auth/adapter-prisma';\nimport { PrismaClient } from '@prisma/client';\n\nconst prisma = new PrismaClient();\n\nexport const auth = new Auth({\n  adapter: PrismaAdapter(prisma),\n  secret: process.env.AUTH_SECRET ?? 'super-secret-dev-key', // IMPORTANT: Use a strong, unique secret in production\n  providers: [], // Configure your authentication providers here\n});\n\n// Example usage (e.g., in a Next.js API route):\n// import { auth } from './auth'; // Adjust path as needed\n// import type { NextApiRequest, NextApiResponse } from 'next';\n//\n// export default async function handler(req: NextApiRequest, res: NextApiResponse) {\n//   const session = await auth.getSession({ req });\n//   if (!session) {\n//     return res.status(401).json({ message: 'Unauthorized' });\n//   }\n//   res.status(200).json({ user: session.user });\n// }","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The `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.","severity":"breaking","affected_versions":">=1.7.0-beta.0"},{"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`.","message":"The `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.","severity":"breaking","affected_versions":">=1.6.2"},{"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.","message":"The `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.","severity":"breaking","affected_versions":">=1.6.0"},{"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.","message":"2FA 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.","severity":"gotcha","affected_versions":"1.6.4"}],"env_vars":null,"last_verified":"2026-04-18T00:00:00.000Z","next_check":"2026-07-17T00:00:00.000Z","problems":[{"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`).","cause":"The required `verified` column for the `twoFactor` table, introduced in v1.6.2, is missing from your database schema.","error":"Column 'verified' does not exist on table 'twoFactor'"},{"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.","cause":"The `AUTH_SECRET` environment variable is not set, which is critical for encrypting and signing session tokens, making the application insecure.","error":"AuthError: AUTH_SECRET is not defined"},{"fix":"Ensure `auth` is properly instantiated and exported. When calling `getSession` server-side, pass the relevant request object, e.g., `await auth.getSession({ req })`.","cause":"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`).","error":"TypeError: auth.getSession is not a function"},{"fix":"Update your `enableTwoFactor` calls to explicitly specify the `method` as either `'otp'` or `'totp'`, e.g., `auth.enableTwoFactor({ method: 'totp' })`.","cause":"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`.","error":"AuthError: Invalid OTP method specified."}],"ecosystem":"npm"}