lucia

A simple and flexible authentication library

weekly downloads98K

versionv3.2.2

licenseMIT

categoryauth

lucialucia-authauthenticationauth

Overview

Lucia is a TypeScript-first authentication library that provides low-level primitives for building custom authentication systems in Node.js applications. Unlike high-level solutions that abstract away authentication details, Lucia gives you direct control over user management, session handling, and authentication flows while remaining framework-agnostic. It works seamlessly with SvelteKit, Next.js, Express, and other JavaScript frameworks through middleware adapters.

The library implements session-based authentication by storing session IDs in secure, httpOnly cookies and validating them against database records. It supports multiple database backends through official adapters for Prisma, Drizzle ORM, MySQL, PostgreSQL, SQLite, and Redis. Lucia's key management system allows users to authenticate through multiple methods—email/password, OAuth providers, magic links—all tied to a single user account through a flexible "key" abstraction.

With nearly 100,000 weekly downloads, Lucia has gained traction among developers who need more control than all-in-one solutions provide but don't want to build authentication from scratch. However, it's important to note that as of October 2024, the maintainers announced Lucia v3 will be deprecated by March 2025, with core maintenance limited to critical bug fixes. The adapter ecosystem will be deprecated by end of 2024, though the library remains functional and widely used in production applications.

Despite the deprecation notice, Lucia remains relevant for understanding session-based authentication patterns and continues to be featured in recent tutorials and production codebases. Developers should evaluate whether to adopt it for new projects given the deprecation timeline, though existing implementations remain stable and the concepts translate well to alternative solutions.

Quick Start

typescript

import { lucia } from 'lucia';
import { betterSqlite3 } from '@lucia-auth/adapter-sqlite';
import sqlite from 'better-sqlite3';

const db = sqlite('auth.db');

db.exec(`
  CREATE TABLE IF NOT EXISTS user (
    id TEXT PRIMARY KEY,
    email TEXT UNIQUE NOT NULL
  );
  CREATE TABLE IF NOT EXISTS session (
    id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL,
    expires_at INTEGER NOT NULL,
    FOREIGN KEY (user_id) REFERENCES user(id)
  );
`);

const auth = lucia({
  adapter: betterSqlite3(db, {
    user: 'user',
    session: 'session'
  }),
  env: 'DEV',
  getUserAttributes: (data) => {
    return {
      email: data.email
    };
  }
});

async function registerUser(email, password) {
  const user = await auth.createUser({
    key: {
      providerId: 'email',
      providerUserId: email.toLowerCase(),
      password
    },
    attributes: {
      email
    }
  });
  return user;
}

async function loginUser(email, password) {
  const key = await auth.useKey('email', email.toLowerCase(), password);
  const session = await auth.createSession({
    userId: key.userId,
    attributes: {}
  });
  return { session, userId: key.userId };
}

async function validateSession(sessionId) {
  const { session, user } = await auth.validateSession(sessionId);
  if (!session) return null;
  return { session, user };
}

const newUser = await registerUser('user@example.com', 'securePassword123');
const { session } = await loginUser('user@example.com', 'securePassword123');
const validated = await validateSession(session.sessionId);
console.log('Authenticated user:', validated.user.email);

Use Cases

Custom authentication flows for SaaS applications: Build multi-tenant authentication systems where you need granular control over session lifetimes, user attributes, and authentication methods. Lucia's low-level primitives let you implement complex requirements like organization-scoped sessions or role-based session attributes that high-level libraries can't easily accommodate.

Multi-provider authentication portals: Create applications where users can link multiple authentication methods (email/password, GitHub, Google, magic links) to a single account. Lucia's key management system treats each auth method as a separate "key" linked to the user, making it straightforward to add or remove providers without restructuring your database.

Microservice architectures with shared sessions: Implement session validation across multiple Node.js services using a shared Redis or database backend. Lucia's framework-agnostic design and explicit session management make it suitable for distributed systems where authentication state needs to be accessible from multiple services.

Learning and prototyping authentication systems: Understand how session-based authentication works at a fundamental level without the abstraction layers of tools like Passport or Auth.js. Lucia's explicit API makes authentication mechanics transparent, making it valuable for educational purposes or when building proof-of-concept authentication systems.

Applications requiring custom session storage logic: Build systems with specialized session requirements like geographic session pinning, device fingerprinting, or custom session refresh logic. Lucia's direct database access and session primitive give you full control over how sessions are created, validated, and invalidated.

Pros & Cons

Pros

+Full control over authentication logic with minimal abstraction—no magic, just explicit session and user management primitives
+Framework-agnostic design works with any Node.js framework through middleware adapters, not locked to Next.js or specific ecosystems
+Type-safe TypeScript API with strong inference for user attributes, session data, and database schemas
+Flexible key system supports multiple authentication methods per user without complex schema changes
+Lightweight core with no unnecessary dependencies—you only add what you need through adapter packages

Cons

−Official deprecation announced for March 2025 with adapter support ending December 2024—not recommended for new long-term projects
−Requires manual database schema setup and understanding of session mechanics—steeper learning curve than high-level alternatives
−No built-in UI components or ready-made OAuth flows—you implement all frontend logic yourself
−Limited community ecosystem compared to mature solutions like Passport or Auth.js, with fewer third-party integrations
−Documentation gaps for advanced use cases and the deprecation timeline creates uncertainty about future support

Alternatives

better-authv1.4.18

The most comprehensive authentication framework for TypeScript.

authauthoauth

1.2M / week

next-authv4.24.13

Authentication for Next.js

authreactnodejs

2.6M / week

passportv0.7.0

Simple, unobtrusive authentication for Node.js.

authexpressconnect

5.7M / week

Comparisons

Install

bash

npm install lucia

bash

pnpm add lucia

bash

bun add lucia

Overview

Quick Start

typescript

import { lucia } from 'lucia';
import { betterSqlite3 } from '@lucia-auth/adapter-sqlite';
import sqlite from 'better-sqlite3';

const db = sqlite('auth.db');

db.exec(`
  CREATE TABLE IF NOT EXISTS user (
    id TEXT PRIMARY KEY,
    email TEXT UNIQUE NOT NULL
  );
  CREATE TABLE IF NOT EXISTS session (
    id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL,
    expires_at INTEGER NOT NULL,
    FOREIGN KEY (user_id) REFERENCES user(id)
  );
`);

const auth = lucia({
  adapter: betterSqlite3(db, {
    user: 'user',
    session: 'session'
  }),
  env: 'DEV',
  getUserAttributes: (data) => {
    return {
      email: data.email
    };
  }
});

async function registerUser(email, password) {
  const user = await auth.createUser({
    key: {
      providerId: 'email',
      providerUserId: email.toLowerCase(),
      password
    },
    attributes: {
      email
    }
  });
  return user;
}

async function loginUser(email, password) {
  const key = await auth.useKey('email', email.toLowerCase(), password);
  const session = await auth.createSession({
    userId: key.userId,
    attributes: {}
  });
  return { session, userId: key.userId };
}

async function validateSession(sessionId) {
  const { session, user } = await auth.validateSession(sessionId);
  if (!session) return null;
  return { session, user };
}

const newUser = await registerUser('user@example.com', 'securePassword123');
const { session } = await loginUser('user@example.com', 'securePassword123');
const validated = await validateSession(session.sessionId);
console.log('Authenticated user:', validated.user.email);

Use Cases

Pros & Cons

Pros

+Full control over authentication logic with minimal abstraction—no magic, just explicit session and user management primitives
+Framework-agnostic design works with any Node.js framework through middleware adapters, not locked to Next.js or specific ecosystems
+Type-safe TypeScript API with strong inference for user attributes, session data, and database schemas
+Flexible key system supports multiple authentication methods per user without complex schema changes
+Lightweight core with no unnecessary dependencies—you only add what you need through adapter packages

Cons

−Official deprecation announced for March 2025 with adapter support ending December 2024—not recommended for new long-term projects
−Requires manual database schema setup and understanding of session mechanics—steeper learning curve than high-level alternatives
−No built-in UI components or ready-made OAuth flows—you implement all frontend logic yourself
−Limited community ecosystem compared to mature solutions like Passport or Auth.js, with fewer third-party integrations
−Documentation gaps for advanced use cases and the deprecation timeline creates uncertainty about future support