Configuration

This page describes all the configuration available for lucia(). MaybePromise indicates the function can synchronous or asynchronous.

type Configuration = {
	// required
	adapter:
		| InitializeAdapter<Adapter>
		| {
				user: InitializeAdapter<Adapter>;
				session: InitializeAdapter<SessionAdapter>;
		  };
	env: "DEV" | "PROD";

	// optional
	csrfProtection?:
		| boolean
		| {
				allowedSubdomains: "*" | string[];
		  };
	getSessionAttributes?: (databaseSession: SessionSchema) => Record<any, any>;
	getUserAttributes?: (databaseUser: UserSchema) => Record<any, any>;
	middleware?: Middleware<any>;
	passwordHash?: {
		generate: (password: string) => MaybePromise<string>;
		validate: (
			password: string,
			hashedPassword: string
		) => MaybePromise<boolean>;
	};
	sessionCookie?: {
		name?: string;
		attributes?: SessionCookieAttributes;
		expires?: boolean;
	};
	sessionExpiresIn?: {
		activePeriod: number;
		idlePeriod: number;
	};

	// experimental
	experimental?: {
		debugMode?: boolean;
	};
};

Required#

adapter#

An adapter (specifically a function that initializes it) for your database. You can use a different adapter for your sessions (session adapters).

const adapter: InitializeAdapter<Adapter>;

const adapter: {
	user: InitializeAdapter<Adapter>;
	session: InitializeAdapter<SessionAdapter>;
};

env#

Provides Lucia with the current server context.

Optional#

csrfProtection#

true by default. When set to true, AuthRequest.validate() checks if the request is same-origin using the Origin header. You can define trusted subdomains by adding them to csrfProtection.allowedSubdomains. If your app is hosted on https://foo.example.com, adding "bar" will allow https://bar.example.com. You can add null in the array to allow urls without a subdomain.

CSRF protection is applied to all requests except for GET, OPTIONS, HEAD, and TRACE request.

const csrfProtection = boolean | {
	allowedSubdomains?: "*" | (string | null)[]
	host?: string,
	hostHeader?: string
}

getSessionAttributes()#

Generates session attributes for the user. The returned properties will be included in Session as is.

const getSessionAttributes: (
	databaseSession: SessionSchema
) => Record<any, any>;

Parameters#

Returns#

Default#

const getSessionAttributes = () => {
	return {};
};

getUserAttributes()#

Generates user attributes for the user. The returned properties will be included in User as is.

const getUserAttributes: (databaseUser: UserSchema) => Record<any, any>;

Parameters#

Returns#

Default#

const getUserAttributes = () => {
	return {};
};

middleware#

const middleware: Middleware;

Lucia middleware for Auth.handleRequest(). Learn more about middleware.

passwordHash#

By default, passwords are hashed using Scrypt.

const passwordHash: {
	generate: (password: string) => MaybePromise<string>;
	validate: (password: string, hashedPassword: string) => MaybePromise<boolean>;
};

passwordHash.generate()#

Generates a hash for a password synchronously or asynchronously.

Parameters#

Returns#

passwordHash.validate()#

Validates a hash generated using passwordHash.generate() synchronously or asynchronously.

Parameters#

Returns#

sessionCookie#

const sessionCookie: {
	name?: string;
	attributes?: SessionCookieAttributes;
	expires: boolean;
};

type SessionCookieAttributes = {
	sameSite?: "lax" | "strict" | "none"; // default: "lax"
	path?: string; // default "/""
	domain?: string; // default: undefined
};

sessionExpiresIn#

const sessionExpiresIn: {
	activePeriod: number;
	idlePeriod: number;
};

The active period is the span of time sessions are valid for, while the idle period is span of time since the end of the active period that sessions could be reset (extend expiration).

Experimental#

Experimental configurations are available in experimental.

debugMode#

Disabled by default. When debug mode is enabled, Lucia will log key events to the console.