Application setup
Create a typed Better Auth server configuration with environment-specific URL and secret values.
Better Auth · Type Alias
BetterAuthOptions
BetterAuthOptions describes the configuration object used to create a Better Auth instance. It covers application identity, URLs, databases, authentication features, secrets, and plugins.
How it works
BetterAuthOptions is the configuration shape used to describe a Better Auth instance. Define supported settings such as the application name, base URL, secret, database, authentication methods, and plugins, then pass the checked object to betterAuth.
Syntax
type BetterAuthOptions = { ... }Parameters
| Name | Type | Description |
|---|---|---|
appName | string | Application display name used by Better Auth. |
baseURL | string | object | Application server URL or dynamic host-resolution configuration. |
database | object | Database configuration for the authentication store. |
plugins | array | Additional Better Auth plugins. |
Returns
A Better Auth configuration object accepted by betterAuth.
Key points
- appName gives the application a display identity in Better Auth interfaces and authentication-related contexts.
- baseURL establishes the application server's root address and supports either fixed or request-dependent configuration.
- baseURL accepts a static string for one domain or an object for dynamic resolution across allowed hosts.
- Dynamic base URLs derive and validate the request host before constructing the URL used for that request.
- Some global option behavior can be customized by an individual plugin, such as a two-factor authentication issuer.
Common mistakes
- A path embedded in baseURL overrides Better Auth's default endpoint path.
- Proxy forwarding headers do not affect dynamic base-URL resolution unless explicitly trusted.
Example: Using BetterAuthOptions for configuration
import { betterAuth } from "better-auth";
import type { BetterAuthOptions } from "better-auth";
const options = {
appName: "My App",
baseURL: process.env.SITE_URL,
secret: process.env.BETTER_AUTH_SECRET,
emailAndPassword: { enabled: true },
} satisfies BetterAuthOptions;
export const auth = betterAuth(options);This validates a Better Auth configuration object against BetterAuthOptions before passing it to betterAuth.
When to use it
Database integration
Configure authentication persistence for a PostgreSQL, MySQL, or SQLite-backed application.
Multi-host deployments
Support preview deployments or multiple production domains with request-dependent base URLs.
Plugin-based configuration
Compose built-in and custom authentication behavior through the plugins option.
Interview questions
QWhat is BetterAuthOptions used for?
BetterAuthOptions is the type used to validate the object that configures a Better Auth instance. It can describe settings including appName, baseURL, secret, database, authentication methods, and plugins.
Follow-up: Why use satisfies instead of a broad type assertion? It checks that the object conforms to the options type while preserving useful inference for the object's own properties.
QHow does baseURL work in the options?
baseURL identifies the root URL where the application server is hosted. It may be a static string or an object that resolves a request-specific URL for multiple allowed hosts.
Follow-up: What must be considered when using the object form? Host matching and request-derived URLs should be constrained with allowed hosts, while forwarded headers require explicit trusted-proxy configuration.
QWhich categories of configuration belong in BetterAuthOptions?
The options can include database configuration and authentication features such as email-and-password sign-in. Plugins are supplied through the plugins option, allowing the instance to extend its behavior.
Follow-up: How would you make a configuration reusable across environments? Keep environment-specific values such as baseURL and secret in environment variables while keeping the shared options structure typed.
Related
appNamebaseURLdatabaseadvanced.trustedProxyHeadersallowedHostspluginsbetterAuth