Lucia — Lightweight Authentication Library for Web Applications

Introduction

Lucia is a server-side authentication library written in TypeScript that focuses on session management. Rather than providing a full authentication framework with built-in UI and social login, Lucia gives you the session layer and lets you build your own login flows. This design makes it database-agnostic and framework-agnostic while keeping the codebase small and auditable.

What Lucia Does

• Creates, validates, and invalidates user sessions stored in any database
• Manages secure session cookies with configurable attributes (expiry, domain, SameSite)
• Provides adapters for popular databases including PostgreSQL, MySQL, SQLite, MongoDB, and Drizzle/Prisma ORMs
• Handles session renewal and idle timeout detection automatically
• Works with any Node.js-compatible framework (Next.js, SvelteKit, Astro, Express, Hono)

Architecture Overview

Lucia's core is a single Lucia class that takes a database adapter and configuration options. The adapter implements a standard interface for session CRUD operations. When a request arrives, you call lucia.validateSession(sessionId) to check the cookie-provided session against the database. Lucia returns the session and user data or null. The library does not handle password hashing, OAuth, or email verification directly, but its documentation provides patterns for integrating these using companion libraries like oslo and arctic.

Self-Hosting & Configuration

• Install lucia and a database adapter package matching your stack
• Define your user and session table schema according to Lucia's documented structure
• Instantiate Lucia with the adapter and configure session cookie options
• In your request handler middleware, read the session cookie and call validateSession()
• For OAuth flows, use the arctic library alongside Lucia for provider integration

Key Features

• Zero framework lock-in; works anywhere you can set cookies and query a database
• Small core with no hidden network calls, background jobs, or external service dependencies
• Fully typed TypeScript API with generic type parameters for user attributes
• Clear separation between session management and authentication logic
• Extensive documentation with framework-specific guides for Next.js, SvelteKit, Astro, and more

Comparison with Similar Tools

• NextAuth / Auth.js — higher-level auth solution with built-in OAuth providers and database adapters; more features but more opinionated
• Better Auth — framework-agnostic auth with built-in email/password and social login; more batteries-included than Lucia
• Passport.js — strategy-based Express middleware for authentication; flexible but callback-heavy and less TypeScript-friendly
• Supabase Auth — managed auth service tied to Supabase; zero self-hosting effort but vendor-locked
• Clerk — fully managed authentication SaaS; easiest to set up but no self-hosting option

FAQ

Q: Does Lucia handle OAuth login? A: Lucia itself does not implement OAuth. The recommended approach is to use the arctic library for OAuth provider integration and Lucia for session management after authentication.

Q: Which databases does Lucia support? A: Lucia supports any database through adapters. Official adapters exist for PostgreSQL, MySQL, SQLite, MongoDB, Prisma, Drizzle, and others. You can write a custom adapter by implementing the session interface.

Q: Is Lucia still maintained? A: Lucia v3 is stable and widely used. The author recommends using the lower-level oslo libraries for new projects, but Lucia v3 continues to work and receive security fixes.

Q: Can I use Lucia with a serverless deployment? A: Yes. Lucia works in serverless environments like Vercel Edge, Cloudflare Workers, and AWS Lambda. Use a database adapter compatible with your serverless database (e.g., Turso, PlanetScale, Neon).

Sources

• https://github.com/lucia-auth/lucia
• https://lucia-auth.com/