Lucia

Authentication, simple and clean.

Lucia is an auth library for TypeScript that abstracts away the complexity of handling users and sessions. It works alongside your database to provide an API that's easy to use, understand, and extend.

Get started

Motivation

Auth providers are expensive and too rigid. Libraries like Auth.js are too bloated and opinionated. Building your own from scratch is hard and full of pitfalls. What if you can implement your own auth without worrying about the small details?

It just works

Forget endless configuration and callbacks - just write code. Works with all major JS runtimes, including Node.js, Deno, Bun, and Cloudflare Workers.

CREATE TABLE user (
	id TEXT NOT NULL PRIMARY KEY
);

CREATE TABLE user_key (
    id TEXT NOT NULL PRIMARY KEY,
    user_id TEXT NOT NULL REFERENCES user(id),
    hashed_password TEXT
);

CREATE TABLE user_session (
    id TEXT NOT NULL PRIMARY KEY,
    user_id TEXT NOT NULL REFERENCES user(id),
    active_expires INTEGER NOT NULL,
    idle_expires INTEGER NOT NULL
);

Set up your database

Create 3 basic, minimum tables for Lucia. You can add columns to the user table to store custom attributes.

import { lucia } from "lucia";
import { express } from "lucia/middleware";
import { betterSqlite3 } from "@lucia-auth/adapter-sqlite";
import { db } from "./db.js";

export const auth = lucia({
	adapter: betterSqlite3(db),
	middleware: express(),
	env: "DEV"
});

Initialize Lucia

Initialize Lucia using one of the many provided adapters and middleware to use it with your database and framework of choice.

import { auth } from "./auth.js";

const user = await auth.createUser({
	// user identified with their username
	key: {
		providerId: "username",
		providerUserId: username,
		password
	},
	attributes: {}
});
const session = await auth.createSession({
	userId: user.userId,
	attributes: {}
});
const sessionCookie = auth.createSessionCookie(session);

Start building

And that's it! Use Lucia's API to handle basic tasks like creating and validating sessions, and you always have the option to fallback to raw database queries when you need more.

Free and open source

Lucia is a free and open source project made possible by our contributors! Thank you to everyone who has helped with the development!

Let's get started

But a small disclaimer...what makes Lucia great is that it doesn't try to do everything. This means Lucia is intended for a specific audience. If you're looking for something quick and easy, Lucia might not be for you. Experience with backend development is a must too!

Still interested? Dive right in!

Tip: Lucia is pronounced loo-shya