Basic Better Auth setup with PostgreSQL
To set up Better Auth with PostgreSQL, import betterAuth and Pool from pg, then create an auth instance with a database configuration passing a Pool instance with a connectionString from environment variables.
better auth/installation
30 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Generating database schema with CLI
Use the CLI to generate database schema. For the default database adapter, run 'npx auth migrate' to create the schema. For other database adapters like Prisma or Drizzle, run 'npx auth generate' to create the schema for your ORM, then run migration with an external tool.
BETTER_AUTH_API_KEY environment variable
The `BETTER_AUTH_API_KEY` environment variable is required for production environments. It must be obtained from the Better Auth Infrastructure dashboard and is used to configure the dash() and sentinel() plugins.
@better-auth/infra package installation
The Better Auth Infrastructure package is installed using `@better-auth/infra`. This package provides plugins and clients for infrastructure features like analytics, audit logging, and security.
Email service installation and imports
The email service is included in the @better-auth/infra package. Import sendEmail and createEmailSender functions from "@better-auth/infra".
Auth instance file locations
Create a file named auth.ts in one of these locations: project root, lib/ folder, utils/ folder, or nested under src/, app/, or server/ folders (e.g., src/lib/auth.ts, app/lib/auth.ts, server/lib/auth.ts). Export the auth instance with the variable name 'auth' or as a default export.
Create Better Auth instance with betterAuth function
Import the betterAuth function from 'better-auth' and call it with a configuration object to create and export your auth instance. The basic structure is: `export const auth = betterAuth({ // configuration });`
CLI command to generate database schema
Run `npx auth@latest generate` to generate an ORM schema or SQL migration file. If using Kysely, you can apply the migration directly. Use generate only if you plan to apply the migration manually.
Better Auth handler API path default
The default API path for Better Auth handlers is `/api/auth/*`. You can configure a different base path but the handler should be set up to accept all requests to this path.
CLI command to migrate database
Run `npx auth@latest migrate` to create the required tables directly in the database. This command is available only for the built-in Kysely adapter.
Install Better Auth package
Install Better Auth by running the package installation command for the better-auth package. If using a separate client and server setup, install Better Auth in both parts of the project.
BETTER_AUTH_SECRET environment variable requirements
The BETTER_AUTH_SECRET environment variable is a secret value used for encryption and hashing. It must be at least 32 characters long and generated with high entropy. You can generate one using `openssl rand -base64 32` or use a generation tool provided in the documentation.
BETTER_AUTH_URL environment variable
Set the BETTER_AUTH_URL environment variable to the base URL of your application, for example `http://localhost:3000`.
Secret rotation with BETTER_AUTH_SECRETS
To rotate your secret later without invalidating existing data, use the BETTER_AUTH_SECRETS (plural) option instead of BETTER_AUTH_SECRET. See the secrets option in the reference documentation for details.
Convex integration prerequisites
To use Better Auth with Convex, create a Convex project using `npm create convex@latest` and when prompted choose 'none' for user authentication. Run `npx convex dev` during setup to initialize the Convex deployment and keep it running to keep generated types current.
Create Better Auth Convex client instance
Create `lib/auth-client.ts` with the Better Auth client for the client side. Use convexClient() plugin and createAuthClient. Example: import { convexClient } from '@convex-dev/better-auth/client/plugins'; import { createAuthClient } from 'better-auth/react'; export const authClient = createAuthClient({ plugins: [convexClient()], });
Configure Next.js server helpers for Convex
Create `lib/auth-server.ts` exporting helper functions from convexBetterAuthNextJs() with convexUrl (NEXT_PUBLIC_CONVEX_URL) and convexSiteUrl (NEXT_PUBLIC_CONVEX_SITE_URL). Exported functions are: handler, preloadAuthQuery, isAuthenticated, getToken, fetchAuthQuery, fetchAuthMutation, fetchAuthAction.
Mount Better Auth handlers in Convex
Create `convex/http.ts` that registers Better Auth route handlers: import { httpRouter } from 'convex/server'; import { authComponent, createAuth } from './betterAuth/auth'; const http = httpRouter(); authComponent.registerRoutes(http, createAuth); export default http; Then set up route handlers in `app/api/auth/[...all]/route.ts` to proxy auth requests: import { handler } from '@/lib/auth-server'; export const { GET, POST } = handler;
Set up Convex client provider
Create `components/ConvexClientProvider.tsx` that wraps ConvexBetterAuthProvider with a ConvexReactClient and authClient, accepting children and initialToken props. In `app/layout.tsx`, wrap the app with this provider, passing initialToken from getToken().
Convex integration packages
Install Better Auth and the Convex component using `npm install better-auth @convex-dev/better-auth`. The `@convex-dev/better-auth` package is maintained by Convex.
Convex integration environment variables setup
Generate a BETTER_AUTH_SECRET using `npx convex env set BETTER_AUTH_SECRET=$(openssl rand -base64 32)` or `npx auth secret`. Set SITE_URL using `npx convex env set SITE_URL http://localhost:3000`. Add these to `.env.local`: CONVEX_DEPLOYMENT (from setup), NEXT_PUBLIC_CONVEX_URL (Convex cloud URL), NEXT_PUBLIC_CONVEX_SITE_URL (same as NEXT_PUBLIC_CONVEX_URL but ends in .site), and NEXT_PUBLIC_SITE_URL (local site URL like http://localhost:3000). Environment variables used by the auth instance (like BETTER_AUTH_SECRET, GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET) should be configured through the Convex CLI or dashboard, not in `.env.local`.
Convex auth.config.ts setup
Create `convex/auth.config.ts` with the following content to configure Better Auth as an authentication provider: import { getAuthConfigProvider } from '@convex-dev/better-auth/auth-config'; import type { AuthConfig } from 'convex/server'; export default { providers: [getAuthConfigProvider()], } satisfies AuthConfig;
Convex Better Auth component definition
Create `convex/betterAuth/convex.config.ts` to define the component as a locally installed Convex component. This signals to Convex that `convex/betterAuth` is a component directory. Content: import { defineComponent } from 'convex/server'; const component = defineComponent('betterAuth'); export default component;
Register Better Auth Convex component
Register the Better Auth component in `convex/convex.config.ts` by importing the component and calling app.use(betterAuth). Example: import { defineApp } from 'convex/server'; import betterAuth from './betterAuth/convex.config'; const app = defineApp(); app.use(betterAuth); export default app;
Create Better Auth Convex instance
Create `convex/betterAuth/auth.ts` with a Better Auth instance. Export authComponent created with createClient, createAuthOptions function that returns BetterAuthOptions with appName, baseURL, secret, database adapter, emailAndPassword enabled, and convex plugin, the options export for CLI, and createAuth function. Then run `npx auth generate --config ./convex/betterAuth/auth.ts --output ./convex/betterAuth/schema.ts` to generate the schema.
Export Better Auth Convex adapter functions
Create `convex/betterAuth/adapter.ts` that exports adapter functions: create, findOne, findMany, updateOne, updateMany, deleteOne, deleteMany. These are created by calling createApi(schema, createAuthOptions).
Encore integration setup
To integrate Better Auth with Encore, first install the Encore CLI and create a new TypeScript project using 'encore app create my-app --example=ts/hello-world', then install better-auth with 'npm install better-auth'.
Electron integration installation packages
To integrate Better Auth with Electron, install better-auth and @better-auth/electron packages in each project (server, Electron app, and web client).
Electron version support policy
Better Auth supports two major versions behind the latest stable major release of Electron, keeping aligned with Electron's version support policy that includes security updates.
Better Auth CLI schema generation
Run npx auth generate --config server/utils/auth.ts to update the Prisma schema with Better Auth required models. The --config flag specifies the path to the file where the Better Auth instance is created.