RFC: Remove adapter packages

[pilcrowonpaper]

Database adapters have been a fundamental part of Lucia from the very start. It allows Lucia to work with any databases and Lucia provides adapter packages to make the integration easier. But is this correct approach?

I've... actually never considered that. It just made sense when starting, especially since that's how libraries like NextAuth did it. But now I have a definite answer. The adapter model is fine but we shouldn't provide any built-in adapters.

The ready-made adapters are a pain to work with and has the domino effect of making Lucia core bloated. From the start, it's been a struggle make each adapter flexible while keeping the API simple. Take for example the many SQL adapters. We have to dynamically create prepared statements based on custom attributes and escape the table and column names. And it affects the core as well. I don't think anybody likes getUserAttributes() and define module. These API had to be included to provide flexibility and type-inference. But is it worth it? We added all these layers of abstractions so that so devs don't have to manually write queries, but really that's probably the easiest thing for web devs to do.

I'm now convinced that it's a bad idea to create libraries around database drivers and ORMs if you want to provide any sort of flexibility.

So if Lucia doesn't write your queries for you, what can the next version of Lucia look like?

// auth.ts
import { Lucia } from "lucia";
import { db } from "./db.js";

import type { DatabaseAdapter, SessionAndUser } from "lucia";

const adapter: DatabaseAdapter<Session, User> = {
    getSessionAndUser: (sessionId: string): SessionAndUser<Session, User> => {
        const row = db.queryRow(
            "SELECT session.id, session.user_id, session.expires_at, session.login_at, user.id, user.username FROM session INNER JOIN user ON user.id = session.user_id WHERE session.id = ?",
            [sessionId]
        );
        if (row === null) {
            return { session: null, user: null };
        }
        const session: Session = {
            id: row[0],
            expiresAt: new Date(row[2] * 1000),
            loginAt: new Date(row[3] * 1000),
        };
        const user: User = {
            id: row[4],
            username: row[5],
        };
        return { session, user };
    },
    deleteSession: (sessionId: string): void => {
        db.execute("DELETE FROM session WHERE id = ?", [sessionId]);
    },
    updateSessionExpiration: (sessionId: string, expiresAt: Date): void => {
        db.execute("UPDATE session SET expires_at = ? WHERE id = ?", [
            expiresAt,
            sessionId,
        ]);
    },
};

export const lucia = new Lucia(adapter, {
    sessionCookie: {
        secure: false,
    },
});

export interface User {
    id: string;
    username: string;
}

export interface Session extends LuciaSession {
    userId: string;
    loginAt: Date;
}

const { session, user } = await lucia.validateSession(sessionId);
if (session === null) {
    throw new Error("Invalid session");
}
const username = user.username;

The biggest and obvious change is that you have to manually define your adapter. I've used a SQL driver as an example so it's a bit verbose (also see the very clean Prisma adapter), but the queries aren't that complicated at all. We could add sample code for popular drivers and ORMs in the docs, which would make the setup easier too.

From an API design perspective, I think this is beautiful. For starters, minimal generic usage and config options. But I really love the most is that LuciaSession is just an interface that your custom session object needs to satisfy. No more getSessionAttributes() or declare module funkiness. This also means that discriminated unions just works for both sessions and users

const adapter: DatabaseAdapter<Session, User> = {
    /* ... */
};

type Session = SessionA | SessionB;

export interface SessionA extends LuciaSession {
    a: any;
}

export interface SessionB extends LuciaSession {
    b: any;
}

For creating session, just write a single query. We'll provide the utilities for generating IDs and calculating expirations.

import { lucia, generateSessionIdWithWebCrypto } from "lucia";
import { db } from "./db.js";

export async function createSession(userId: string): string {
    const sessionId = generateSessionIdWithWebCrypto();
    const expiresAt = lucia.getNewSessionExpiration();
    db.execute(
        "INSERT INTO session (id, expires_at, user_id, login_at) VALUES (?, ?, ?)",
        [sessionId, expiresAt, userId, Math.floor(new Date().getTime() / 1000)]
    );
    return sessionId;
}

At this point, why keep the user handling? I've thought about this for quite a while, and the simple answer is that it's better to have an API that works with one thing (user + session) rather than two things (user + session or session). If you just need any more flexible than this - just build your own. It's likely that whatever API we provide won't be enough. I think it's fine for Lucia to have some opinions and this feels like the place to draw the line.

On a final note, this could allow us to bring back framework-specific APIs. I don't have the appetite to deal with the mess of JS frameworks, but maybe :D

This will be part of Lucia v4, which will probably be released late this year or early next year. It's very possible that v4 will be our last major update.

[OllieJT]

...and by version 7, Lucia will just be a README on how to setup auth. 😅 (jk)

This makes a lot of sense to me.

[lutefd]

This makes a lot of sense, previously at work I had to rewrite the drizzle adapter, which was a little pain because of the typing, just to change the users queries to query a junction table along with it. This suggested approach would've made that job a lot easier, although it might steep up the learning curve for inexperienced developers that aren't that comfortable with SQL yet, but even that could be a good thing if the docs has a basic guide/example on how to build adapters, creating an opportunity for them to learn.

[bhavishya-sahdev]

My experience with the Drizzle adapter has been fine so far but I appreciate this change, having more control over how the queries work would be great.

[Giggiux]

Would providing some adapters for "simple"/"base" uses makes sense? Maybe not in the core Lucia, but under different packages?

If I need just a "quick" user authentication with Drizzle without any "customization," could we still have the adapter?

To avoid copying/pasting eventual examples?

But I agree with whoever came before me: having more control is very nice and allows devs to have more control, even if there is a little bit of a cost in terms of speed.

[pilcrowonpaper]

@lutefd Fortunately the adapter code is going to be significantly simpler for ORM users. Like for Prisma:

const result = await this.sessionModel.findUnique({
  where: {
    id: sessionId
  },
  include: {
    user: true
  }
);
if (result === null) {
  return { session: null, user: null };
}
const { user, ...session } = result;

[pilcrowonpaper]

@Giggiux For Prisma and Drizzle maybe, though I think it'll be just easier to copy-paste the code from the docs. Unlike the SQL drivers, you won't need to edit the code for a basic setup.

[mirorauhala]

Consider creating an init command like npx lucia-auth@latest init --provider=discord and it would scaffold the correct files in place.

This command would plop in place the fully written out auth code, allowing the dev to focus more on the app while retaining the access to edit the adapter code if need be.

Similar to how shadcn/ui does UI components, could be done for auth.

[pilcrowonpaper]

For Prisma, this will just work with full type inference. I'm guessing something similar is possible with drizzle

import type { Session, User } from "@prisma/client";
import type { DatabaseAdapter, SessionAndUser } from "lucia";

const adapter: DatabaseAdapter<Session, User> = {
    getSessionAndUser: async (
        sessionId: string
    ): Promise<SessionAndUser<Session, User>> => {
        const result = await client.session.findUnique({
            where: {
                id: sessionId,
            },
            include: {
                user: true,
            },
        });
        if (result === null) {
            return { session: null, user: null };
        }
        const { user, ...session } = result;
        return { session, user };
    },
    deleteSession: async (sessionId: string): Promise<void> => {
        await client.session.delete({
            where: {
                id: sessionId,
            },
        });
    },
    updateSessionExpiration: async (
        sessionId: string,
        expiresAt: Date
    ): Promise<void> => {
        await client.session.update({
            where: {
                id: sessionId,
            },
            data: {
                expiresAt,
            },
        });
    },
};

[theorib]

This makes a lot of sense, it's so much better to empower users to create their own database queries, wether through an ORM or not and have total control over that aspect of things.

Giving users a clear API on how to build an adapter is a much better approach and I'm very happy with the proposal!

One of side effect of using Lucia is having ownership and clarity over the whole auth process and I believe this is another step in that direction.

[pilcrowonpaper]

@mirorauhala I've considered that on numerous occasions but I'm not sure how well that'd work. I'd love to see a PoC tho.

[lutefd]

@pilcrowonpaper I think the drizzle one will be pretty similar to what you've shared, the current way already works well like this, so I guess it should work in the new way with complete type inference, the snippet you proposed looks way cleaner as well.

export class DrizzleSQLiteAdapter implements Adapter {
	private db: BaseSQLiteDatabase<any, any, typeof schema>;
	private sessionTable: SQLiteSessionTable;
	private userTable: SQLiteUserTable;

	constructor(
		db: BaseSQLiteDatabase<any, any, any>,
		sessionTable: SQLiteSessionTable,
		userTable: SQLiteUserTable
	) {
		this.db = db;
		this.sessionTable = sessionTable;
		this.userTable = userTable;
	}

	async deleteSession(sessionId: string): Promise<void> {
		await this.db
			.delete(this.sessionTable)
			.where(eq(this.sessionTable.id, sessionId));
	}

	async deleteUserSessions(userId: string): Promise<void> {
		await this.db
			.delete(this.sessionTable)
			.where(eq(this.sessionTable.userId, userId));
	}
	async getSessionAndUser(
		sessionId: string
	): Promise<[session: DatabaseSession | null, user: DatabaseUser | null]> {
		const result = await this.db.query.sessionTable.findFirst({
			where: eq(this.sessionTable.id, sessionId),
			with: {
				user: {
					with: {
						usersToRoles: {
							with: {
								role: true,
							},
						},
					},
				},
			},
		});

		if (!result?.user) return [null, null];
		const session = {
			id: result.id,
			userId: result.userId,
			expiresAt: result.expiresAt,
			is_oauth: result.is_oauth,
		};
		return [
			transformIntoDatabaseSession(session),
			transformIntoDatabaseUser(result.user),
		];
	}

Building on what @mirorauhala suggested, you'd need to have it prompt the db that's being used to properly set it up, as well if there's an ORM being used and which if so, that would require to have base adapters to all the major DBs, as sometimes the typing changes between them (eg. SQLite), and supported ORMs. It should work but it seems like a ton of work and a bit of a headache to maintain without heavy community support.

Shadcn/ui works because it's already assuming you're using react and from the folder Layout it can detect if it's using Next to add the "use client" directives or not. With auth there's a lot more variables and it seems more complex to set it up, but it's a great idea nonetheless if it had more people interested in maintaining it.

[tomwatkins1994]

I think this makes a tonne of sense. Lucia already gives you a lot of control compared to other Auth libraries so I think users of it will not be put off by writing the database implementation themselves and will probably appreciate it, if anything.

I think it also makes sense because if a library like Drizzle suddenly ships a breaking change then the Drizzle adapter library suddenly has to change too or pin a peer dependency that could stop users of Drizzle from updating, not great either way.

If decent examples were provided on how to set it up that can be copied and pasted into your code base then I'm sure that'd be a great starting point.

[ERmilburn02]

Shadcn/ui works because it's already assuming you're using react and from the folder Layout it can detect if it's using Next to add the "use client" directives or not.

@lutefd Not entirely correct, the shadcn/ui package does try to detect if you're using Next.js, but it's only used to set some default options for the components.json file, which it uses when writing components. It doesn't need to detect the framework, it's just for convenience to make it faster to setup.

[lutefd]

Shadcn/ui works because it's already assuming you're using react and from the folder Layout it can detect if it's using Next to add the "use client" directives or not.

@lutefd Not entirely correct, the shadcn/ui package does try to detect if you're using Next.js, but it's only used to set some default options for the components.json file, which it uses when writing components. It doesn't need to detect the framework, it's just for convenience to make it faster to setup.

@ERmilburn02 Yeah, I've just simplified because that isn't really the point, I never said it needs to, only that it can, usually if you're doing a init that need to be iterated on you'll need to write a config file, @shadcn/ui does prompt you if you're using RSC or not which would be one of the only variables on the way the components are written, other than the file paths that mostly change where they are written to and the style/color variants for the css config.

And even that is in most cases a insertion of the "use client" directive. It detects if it's Next.js because as of now it's the only major framework to use RSC extensively, but when dealing with auth there would be a lot of other variables than that, even in Next.js land the way the oauth callbacks are written would differ if it were written for the Pages router or the App router. Outside of that it would be different for Astro, Sveltekit, Nuxt, etc..

It would also need to have different base inserts, due to session creation, for some dbs due to their column typing, so it would need to prompt that, as it would need to create a base db adapter, if you're using an ORM on top of that it would need to have a different template for each of those frameworks and the list goes on, not even stoping to consider different runtime environments, like vercel's edge, hono, node, which all have their particularities (like edge couldn't really handle drizzle base connection to postgres out of the box last time I've checked), that seems like a nightmare to handle for each Provider as suggested, of course there could always be limits and starting with only a few, but even then it would be complicated.

It would be a large project that should be outside of the main Lucia project scope, even if you limit which frameworks and environments, don't get me wrong it's a great idea and maybe lucia's new design could really make it possible, but it would still require a lot of thought and work.

JS land is just a nightmare.

[maietta]

This looks like a great direction and I welcome this proposed change.