Auth

Typebase uses better-auth for authentication. It supports email/password, social logins (Google, GitHub, etc.), and more, all configured through a simple TypeScript file.

The defineAuth function in Typebase is a thin wrapper around better-auth, so anything you can do with better-auth you can do here. If you need features not covered in these docs (plugins, advanced session config, multi-factor auth, and more), the better-auth documentation is the full reference.

Overview

Adding authentication to a Typebase project involves four steps:

1. Create an auth.ts file in your typebase/ directory to configure authentication.
2. Run npx typebase-io-cli auth generate to add the required authentication tables to your database schema.
3. Push the schema to your database with npx typebase-io-cli db dev push (or npx typebase-io-cli deploy dev, which pushes as part of deploying).
4. Create an auth client on the frontend to handle sign-up, sign-in, and session management.

Step 1: Configure authentication

Create an auth.ts file in the root of your typebase/ directory:

import { defineAuth } from 'typebase-io/server';

export const auth = defineAuth({
  trustedOrigins: ['http://localhost:3000'],
  emailAndPassword: {
    enabled: true,
  },
});

defineAuth options

The defineAuth function accepts all better-auth configuration options except database (Typebase handles that for you). Here are some common options:

Social providers example

import { defineAuth } from 'typebase-io/server';

export const auth = defineAuth({
  trustedOrigins: ['http://localhost:3000'],
  emailAndPassword: {
    enabled: true,
  },
  socialProviders: {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    },
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    },
  },
});

Step 2: Generate auth tables

Run the auth generate command to automatically add the required authentication tables (users, sessions, accounts, verifications) to your database schema:

npx typebase-io-cli auth generate

This command does two things:

1. Appends tables to db/schema.ts: adds the users, sessions, accounts, and verifications tables.
2. Updates db/relations.ts: registers the new tables and their relationships.

After running the command, your schema will include something like this:

// ... your existing tables ...

export const users = p.pgTable('users', {
  id: p.text('id').primaryKey(),
  name: p.text('name').notNull(),
  email: p.text('email').notNull().unique(),
  emailVerified: p.boolean('email_verified').default(false).notNull(),
  image: p.text('image'),
  createdAt: p.timestamp('created_at').defaultNow().notNull(),
  updatedAt: p
    .timestamp('updated_at')
    .defaultNow()
    .$onUpdate(() => new Date())
    .notNull(),
});

export const sessions = p.pgTable('sessions', {
  /* ... */
});
export const accounts = p.pgTable('accounts', {
  /* ... */
});
export const verifications = p.pgTable('verifications', {
  /* ... */
});

Step 3: Push the schema to your database

npx typebase-io-cli auth generate only edits source files. It doesn't create the tables in Postgres, so push the schema to your dev database before trying to sign in:

npx typebase-io-cli db dev push

npx typebase-io-cli deploy dev also runs a schema push as part of deploying, so if you're about to deploy you can skip the explicit db push.

Step 4: Set up the auth client

Setting up the auth client depends on your frontend framework. Check the integrations section for detailed instructions on sign up, sign in, sign out, server-side sessions, and route protection for your framework.

Protecting actions with auth middleware

Once authentication is set up, you can create protected actions that require a valid session. See the Middleware page for details on creating authenticated actions.

Environment variables

Typebase uses these auth-related environment variables:

You can also manage provider-side variables manually with the npx typebase-io-cli env command.