Authentication system

The authentication system is handled by the Better Auth library, which provides most features you will ever need, plus some more.

Better-auth is heavily plugin-based, we propose a few guides on how to add some specific features like organizations, admin, etc.

❓ How it works

Better-auth is using your database to store all of its data. Depending on the ORM you use, you might need to create some entities to store the data.

We use MikroORM in this boilerplate, and you can find the entities in the auth module.

The boilerplate ships a custom MikroORM adapter for Better Auth (see auth-db.adapter.ts), replacing the community better-auth-mikro-orm package. It includes a CLI integration to auto-generate entity code via pnpm --filter=api auth:generate:

pnpm --filter=api auth:generate   # auth generate --config src/modules/auth/auth.cli.mts --yes

When adding a Better Auth plugin:

1. Add the plugin in auth.config.ts
2. Run pnpm --filter=api auth:generate to scaffold missing entities/fields
3. Move the generated code into the entity files and register them in db.config.ts
4. Run pnpm --filter=api db:migrate:create to create the MikroORM migration
5. Run auth tests to verify alignment

Note

It’s a good practise to keep all entities related to better-auth in the auth module!

📝 How to use

Better-auth provides server and client methods, see the Better Auth documentation for more details.

Better-auth provides a OpenAPI schema and a live documentation of your API endpoints. You can find it at http://localhost:3000/api/auth/reference by default.

Note

It’s good practice to prefix better-auth related entities table names with auth_ to keep them organized. Just make sure to update the table names in the entity decorators accordingly.

🧹 How to remove

Caution

Removing Better Auth from the project is a bit more work than removing other features. It’s not recommended.

Deleting the auth module is not enough. Example modules (posts, comments, ai-example), API tests and helpers, seeders, and the frontend auth pages also import it. Strip those references — or remove the examples first — or the project will not compile.

1. Delete the auth module from apps/api/src/modules/auth
2. Remove the AuthModule from apps/api/src/app.module.ts
3. Remove the following dependencies from apps/api/package.json:

"better-auth",
"auth"

4. Remove the following dependencies from the frontend apps

"better-auth",

5. Remove the following env variables from apps/api/.env, apps/api/.env.example, and the BETTER_AUTH_SECRET field from apps/api/src/config/env.config.ts:

BETTER_AUTH_SECRET=

6. Remove leftover auth imports from example modules, apps/api/src/test/helpers/, seeders, apps/web-spa/app/features/auth, apps/web-spa/app/lib/auth-client.ts, and the matching routes in apps/web-spa/app/routes.ts.