# Lucia — Lightweight Authentication Library for Web Applications

> Lucia is a TypeScript authentication library that handles session management with any database. It provides the core session and cookie primitives without imposing a specific framework or ORM, giving developers full control over their authentication flow.

## Install

Save as a script file and run:

# Lucia — Lightweight Authentication Library for Web Applications

## Quick Use
```bash
npm install lucia
# Create a Lucia instance with your database adapter:
# import { Lucia } from "lucia";
# const lucia = new Lucia(adapter);
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-9e74f3f5
Author: Script Depot