Getting Started#

Get AuthHero running in under 5 minutes. This guide covers three installation methods, database setup, Redis, email configuration, and your first API request.

Prerequisites#

Requirement	Version	Check Command
`Node.js`	>= 18.0.0	node --version
`PostgreSQL`	Any recent version	psql --version
`Redis`	Any recent version	redis-cli ping
`npm or bun`	Latest	npm --version

Option 1: CLI Scaffolder (Recommended)#

The fastest way to get started. Creates a complete project with auto-generated secrets.

Terminal

npx create-authhero my-auth-server
cd my-auth-server

What the CLI does#

Clones the AuthHero template into your project directory
Generates cryptographic secrets automatically (JWT keys, MFA encryption key)
Creates a .env file from .env.example with secrets pre-filled
Installs all npm dependencies
Initializes a fresh git repository

After scaffolding#

Terminal

# 1. Edit .env — set your DATABASE_URL, EMAIL_USER, EMAIL_PASS
#    (secrets are already generated for you)

# 2. Run database migrations
npx prisma migrate dev --name init

# 3. Start the server
npm run dev

# 4. In a separate terminal, start the email worker
npm run worker

Option 2: npm Package#

Install

Terminal

npm install @nandalalshukla/auth-hero express

Copy the Prisma schema

AuthHero ships its Prisma schema inside the package. Copy it to your project:

Terminal

mkdir -p prisma
cp node_modules/@nandalalshukla/auth-hero/prisma/schema.prisma prisma/schema.prisma

Create your .env file

Terminal

cp node_modules/@nandalalshukla/auth-hero/.env.example .env

Generate secrets

Each secret should be a 64-character hex string. Run this command once for each secret:

Terminal

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Fill in ACCESS_TOKEN_SECRET, REFRESH_TOKEN_SECRET, MFA_ENCRYPTION_KEY, and MFA_TEMP_TOKEN_SECRET in your .env.

Run migrations

Terminal

npx prisma migrate dev --name init

Create your entry file

src/index.ts

import "dotenv/config";
import { createAuthHero } from "@nandalalshukla/auth-hero";

async function main() {
  const auth = await createAuthHero();

  auth.app.listen(3000, () => {
    console.log("🔐 AuthHero running on http://localhost:3000");
  });

  // Graceful shutdown
  process.on("SIGTERM", async () => {
    await auth.shutdown();
    process.exit(0);
  });
}

main();

Run

Terminal

npx tsx src/index.ts

Option 3: Clone the Repository#

For full source code access and customization.

Terminal

git clone https://github.com/nandalalshukla/authhero.git my-auth-server
cd my-auth-server
npm install
cp .env.example .env
# Fill in your .env values
npx prisma migrate dev --name init
npm run dev        # Start the server (with hot reload)
npm run worker     # Start the email worker (separate terminal)

Database Setup#

AuthHero uses PostgreSQL. You need a running PostgreSQL instance.

Local PostgreSQL#

Terminal

# macOS (Homebrew)
brew install postgresql@16
brew services start postgresql@16

# Ubuntu/Debian
sudo apt install postgresql
sudo systemctl start postgresql

# Windows / Docker
docker run -d --name postgres -e POSTGRES_PASSWORD=password -p 5432:5432 postgres:16

Create the database#

psql

CREATE DATABASE authhero;

Connection string#

Set in your .env:

.env

DATABASE_URL=postgresql://postgres:password@localhost:5432/authhero

Format: postgresql://USER:PASSWORD@HOST:PORT/DATABASE

Run migrations#

Terminal

npx prisma migrate dev --name init

This creates all the required tables: User, Session, EmailVerification, PasswordReset, OAuthAccount, MFASecret.

✅Prisma Studio

Run npx prisma studio to open a visual database browser at http://localhost:5555.

Redis Setup#

Redis is used for rate limiting, job queues (BullMQ email worker), and OAuth one-time codes.

Terminal

# macOS
brew install redis && brew services start redis

# Ubuntu/Debian
sudo apt install redis-server && sudo systemctl start redis

# Windows / Docker
docker run -d --name redis -p 6379:6379 redis:7

Verify: redis-cli ping → should return PONG

.env

REDIS_HOST=localhost
REDIS_PORT=6379

Email Configuration#

AuthHero sends transactional emails for:

Email verification — after registration
Password reset — when user requests it
Resend verification — when an unverified user tries to log in

Gmail (easiest for development)#

Go to Google App Passwords
Generate an app password for "Mail"
Set in your .env:

.env

EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=465
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-16-char-app-password

⚠️2FA Required

You need 2-Step Verification enabled on your Google account to create app passwords.

Start the email worker#

Emails are processed asynchronously via BullMQ. Run the worker in a separate terminal:

Terminal

npm run worker

Why a separate worker? This prevents email sending from blocking HTTP responses. If the SMTP server is slow, your API responses remain fast. It also enables retry logic for failed emails.

Verify It Works#

Health check#

Terminal

curl http://localhost:5000/health

Response

{
  "status": "ok",
  "timestamp": "2026-02-27T12:00:00.000Z"
}

Register a user#

Terminal

curl -X POST http://localhost:5000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "fullname": "John Doe",
    "email": "john@example.com",
    "password": "MySecure@Pass1"
  }'

Response

{
  "success": true,
  "message": "Registration successful. Please verify your email.",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "fullname": "John Doe",
    "email": "john@example.com",
    "emailVerified": false,
    "mfaEnabled": false,
    "createdAt": "2026-02-27T12:00:00.000Z"
  }
}

Terminal

curl -X POST http://localhost:5000/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "john@example.com",
    "password": "MySecure@Pass1"
  }'

💡Email verification required

You'll get a 403 with errorCode: "EMAIL_NOT_VERIFIED" until the email is verified. A new verification link is automatically sent.

Available Scripts#

Script	Command	Description
`dev`	bun --watch src/server.ts	Dev server with hot reload
`worker`	bun --watch src/workers/email.worker.ts	Email worker with hot reload
`build`	tsup	Build for production (ESM + DTS)
`start`	node dist/server.js	Run production build
`db:migrate`	npx prisma migrate dev	Run database migrations
`db:generate`	npx prisma generate	Regenerate Prisma client
`db:studio`	npx prisma studio	Open Prisma visual browser
`test`	vitest run	Run all tests
`test:watch`	vitest	Run tests in watch mode
`test:coverage`	vitest run --coverage	Run tests with coverage report
`typecheck`	tsc --noEmit	Check types without emitting
`lint`	eslint src/	Lint source code
`format`	prettier --write "src/*/.ts"	Format code

Getting Started#

Get AuthHero running in under 5 minutes. This guide covers three installation methods, database setup, Redis, email configuration, and your first API request.

Prerequisites#

Requirement	Version	Check Command
`Node.js`	>= 18.0.0	node --version
`PostgreSQL`	Any recent version	psql --version
`Redis`	Any recent version	redis-cli ping
`npm or bun`	Latest	npm --version

Option 1: CLI Scaffolder (Recommended)#

The fastest way to get started. Creates a complete project with auto-generated secrets.

Terminal

npx create-authhero my-auth-server
cd my-auth-server

What the CLI does#

Clones the AuthHero template into your project directory
Generates cryptographic secrets automatically (JWT keys, MFA encryption key)
Creates a .env file from .env.example with secrets pre-filled
Installs all npm dependencies
Initializes a fresh git repository

After scaffolding#

Terminal

# 1. Edit .env — set your DATABASE_URL, EMAIL_USER, EMAIL_PASS
#    (secrets are already generated for you)

# 2. Run database migrations
npx prisma migrate dev --name init

# 3. Start the server
npm run dev

# 4. In a separate terminal, start the email worker
npm run worker

Option 2: npm Package#

Install

Terminal

npm install @nandalalshukla/auth-hero express

Copy the Prisma schema

AuthHero ships its Prisma schema inside the package. Copy it to your project:

Terminal

mkdir -p prisma
cp node_modules/@nandalalshukla/auth-hero/prisma/schema.prisma prisma/schema.prisma

Create your .env file

Terminal

cp node_modules/@nandalalshukla/auth-hero/.env.example .env

Generate secrets

Each secret should be a 64-character hex string. Run this command once for each secret:

Terminal

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Fill in ACCESS_TOKEN_SECRET, REFRESH_TOKEN_SECRET, MFA_ENCRYPTION_KEY, and MFA_TEMP_TOKEN_SECRET in your .env.

Run migrations

Terminal

npx prisma migrate dev --name init

Create your entry file

src/index.ts

import "dotenv/config";
import { createAuthHero } from "@nandalalshukla/auth-hero";

async function main() {
  const auth = await createAuthHero();

  auth.app.listen(3000, () => {
    console.log("🔐 AuthHero running on http://localhost:3000");
  });

  // Graceful shutdown
  process.on("SIGTERM", async () => {
    await auth.shutdown();
    process.exit(0);
  });
}

main();

Run

Terminal

npx tsx src/index.ts

Option 3: Clone the Repository#

For full source code access and customization.

Terminal

git clone https://github.com/nandalalshukla/authhero.git my-auth-server
cd my-auth-server
npm install
cp .env.example .env
# Fill in your .env values
npx prisma migrate dev --name init
npm run dev        # Start the server (with hot reload)
npm run worker     # Start the email worker (separate terminal)

Database Setup#

AuthHero uses PostgreSQL. You need a running PostgreSQL instance.

Local PostgreSQL#

Terminal

# macOS (Homebrew)
brew install postgresql@16
brew services start postgresql@16

# Ubuntu/Debian
sudo apt install postgresql
sudo systemctl start postgresql

# Windows / Docker
docker run -d --name postgres -e POSTGRES_PASSWORD=password -p 5432:5432 postgres:16

Create the database#

psql

CREATE DATABASE authhero;

Connection string#

Set in your .env:

.env

DATABASE_URL=postgresql://postgres:password@localhost:5432/authhero

Format: postgresql://USER:PASSWORD@HOST:PORT/DATABASE

Run migrations#

Terminal

npx prisma migrate dev --name init

This creates all the required tables: User, Session, EmailVerification, PasswordReset, OAuthAccount, MFASecret.

✅Prisma Studio

Run npx prisma studio to open a visual database browser at http://localhost:5555.

Redis Setup#

Redis is used for rate limiting, job queues (BullMQ email worker), and OAuth one-time codes.

Terminal

# macOS
brew install redis && brew services start redis

# Ubuntu/Debian
sudo apt install redis-server && sudo systemctl start redis

# Windows / Docker
docker run -d --name redis -p 6379:6379 redis:7

Verify: redis-cli ping → should return PONG

.env

REDIS_HOST=localhost
REDIS_PORT=6379

Email Configuration#

AuthHero sends transactional emails for:

Email verification — after registration
Password reset — when user requests it
Resend verification — when an unverified user tries to log in

Gmail (easiest for development)#

Go to Google App Passwords
Generate an app password for "Mail"
Set in your .env:

.env

EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=465
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-16-char-app-password

⚠️2FA Required

You need 2-Step Verification enabled on your Google account to create app passwords.

Start the email worker#

Emails are processed asynchronously via BullMQ. Run the worker in a separate terminal:

Terminal

npm run worker

Why a separate worker? This prevents email sending from blocking HTTP responses. If the SMTP server is slow, your API responses remain fast. It also enables retry logic for failed emails.

Verify It Works#

Health check#

Terminal

curl http://localhost:5000/health

Response

{
  "status": "ok",
  "timestamp": "2026-02-27T12:00:00.000Z"
}

Register a user#

Terminal

curl -X POST http://localhost:5000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "fullname": "John Doe",
    "email": "john@example.com",
    "password": "MySecure@Pass1"
  }'

Response

{
  "success": true,
  "message": "Registration successful. Please verify your email.",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "fullname": "John Doe",
    "email": "john@example.com",
    "emailVerified": false,
    "mfaEnabled": false,
    "createdAt": "2026-02-27T12:00:00.000Z"
  }
}

Terminal

curl -X POST http://localhost:5000/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "john@example.com",
    "password": "MySecure@Pass1"
  }'

💡Email verification required

You'll get a 403 with errorCode: "EMAIL_NOT_VERIFIED" until the email is verified. A new verification link is automatically sent.

Available Scripts#

Script	Command	Description
`dev`	bun --watch src/server.ts	Dev server with hot reload
`worker`	bun --watch src/workers/email.worker.ts	Email worker with hot reload
`build`	tsup	Build for production (ESM + DTS)
`start`	node dist/server.js	Run production build
`db:migrate`	npx prisma migrate dev	Run database migrations
`db:generate`	npx prisma generate	Regenerate Prisma client
`db:studio`	npx prisma studio	Open Prisma visual browser
`test`	vitest run	Run all tests
`test:watch`	vitest	Run tests in watch mode
`test:coverage`	vitest run --coverage	Run tests with coverage report
`typecheck`	tsc --noEmit	Check types without emitting
`lint`	eslint src/	Lint source code
`format`	prettier --write "src/*/.ts"	Format code