Auth Kit - App Router JWT, OAuth, 2FA

Prerequisites

- Node.js 20+

- PostgreSQL 14+

- Optional: Google Cloud OAuth app, GitHub OAuth app, SMTP provider

1. Install

npm install

cp .env.example .env

2. Environment variables

Variable | Required | Description

----------|----------|-------------

DATABASE_URL | Yes | Postgres connection string. Use a dedicated DB name (e.g. auth_kit)

JWT_SECRET | Yes | Min 32 characters; signs access JWTs and encrypts 2FA secrets

NEXT_PUBLIC_APP_URL | Yes | Public origin, no trailing slash, e.g. http://localhost:3000

NEXT_PUBLIC_APP_NAME | Optional | Shown in 2FA QR issuer label

SKIP_EMAIL_VERIFICATION | Yes | false = send verify email on signup (when SMTP is set). true = skip verify and log in immediately.

SIGNUPS_OPEN | Optional | false blocks new signups without code changes

SMTP_HOST | Email | SMTP server hostname

SMTP_PORT | Email | Usually 587

SMTP_SECURE | Email | true for port 465, else false

SMTP_USER | Email | SMTP login

SMTP_PASS | Email | SMTP password

SMTP_FROM | Email | Must be an address your provider allows (often same as SMTP_USER)

SMTP_FROM_NAME | Email | Display name in From header

GOOGLE_CLIENT_ID/SECRET | Optional | Google OAuth

GITHUB_CLIENT_ID/SECRET | Optional | GitHub OAuth

Email behavior

Flow | When SMTP is configured | Without SMTP (development)

------|-------------------------|----------------------------

Signup verify | Email to /verify-email?token=... | Token shown on signup success UI

Forgot password | Email to /reset-password?token=... | Token shown on reset page

Change email | Email to /confirm-email-change?token=... | Confirm link shown in settings

Reset and email-change tokens are single-use. Password reset rejects reusing your current password.

3. Database

Local Postgres: create the database first

Prisma db push / migrate only apply the schema. They do not create the empty database on your server. For a local Postgres install, run:

npm run db:create

npm run db:push

npm run db:create runs scripts/create-db.mjs. It:

1. Reads DATABASE_URL from .env

2. Connects to the admin database (postgres) on the same host

3. Runs CREATE DATABASE for the name in your URL (e.g. auth_kit)

4. Exits safely if the database already exists

Requirements:

- Postgres must be running (localhost:5432 or whatever your URL uses)

- DATABASE_URL must use a dedicated database name - not postgres (the script refuses that on purpose)

- Your Postgres user must be allowed to create databases (default local postgres user usually can)

Example .env:

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/auth_kit"

Cloud Postgres (Neon, Supabase, etc.)

Create the database in the provider dashboard, paste the connection string into DATABASE_URL, then skip db:create:

npm run db:push

Troubleshooting db:create