Get Started — ModularAuth-Kit

Adding to an Existing Express Project

Step 1 — Download & Install

Download the latest release from GitHub Releases. Extract it and copy the src/auth/ folder into your project's src/ directory. Then install missing dependencies:

terminal

# Only install what you don't already have:
npm install argon2 zod helmet cookie-parser
          

Step 2 — Add SESSION_SECRET

Add one line to your existing .env file. This is the only new environment variable required:

.env

# Generate a random secret:
# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
SESSION_SECRET=paste-your-generated-secret-here
          

Step 3 — Mount

Add 3 lines to your existing Express app. Put it after express.json() and before your routes:

your existing app.ts

// Add this import
import { createConfig, createAuthModule } from './auth/index.js';

// After your existing express.json() and mongoose.connect()...

const config = createConfig({ session: { secure: false } });
app.use('/auth', createAuthModule(config));

// Your existing routes continue to work unchanged

Your MongoDB connection is reused automatically. If you already have mongoose.connect() in your project, the auth module uses it. No extra database setup needed.

Starting a New Project

terminal

# Initialize project
mkdir my-app && cd my-app
npm init -y
npm install express mongoose argon2 helmet cookie-parser zod dotenv
npm install -D typescript tsx @types/express @types/cookie-parser

# Download the auth module from GitHub Releases:
# https://github.com/IamAshrafee/ModularAuth-Kit/releases
# Extract and copy src/auth/ into your src/ folder
          

src/server.ts

import 'dotenv/config';
import express from 'express';
import mongoose from 'mongoose';
import { createConfig, createAuthModule } from './auth/index.js';

async function main() {
  await mongoose.connect(process.env.MONGODB_URI!);

  const app = express();
  app.use(express.json());

  const config = createConfig({
    session: { secure: false },
  });

  app.use('/auth', createAuthModule(config));

  app.listen(3000, () => console.log('http://localhost:3000'));
}

main();
          

.env

MONGODB_URI=mongodb://localhost:27017/myapp
SESSION_SECRET=your-random-64-char-secret-here
          

Let Your AI Agent Do It

If you use an AI coding agent (Cursor, GitHub Copilot, Gemini, etc.), you can automate the entire integration:

Copy the auth folder

Copy src/auth/ from the repository into your project.

Give the AI the prompt

Copy the entire contents of agent-prompt.md and paste it to your AI agent.

Answer a few questions

The AI will analyze your project, ask what features you need, then handle the rest — installing deps, configuring, mounting, and verifying.

Get the AI Prompt →

Verify It Works

terminal

# Start your server
npm run dev

# Register
curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"Test1234!"}' \
  -c cookies.txt

# Login
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"identifier":"test@example.com","password":"Test1234!"}' \
  -c cookies.txt

# Get profile (authenticated)
curl http://localhost:3000/auth/me -b cookies.txt
          

Protect Your Own Routes

Use the requireAuth middleware to protect any route in your app:

your routes

import { requireAuth } from './auth/http/middleware/require-auth.js';

// Protected — only logged-in users
app.get('/api/dashboard', requireAuth, (req, res) => {
  res.json({ userId: req.user!._id });
});

// Public — anyone can access
app.get('/api/health', (req, res) => {
  res.json({ status: 'ok' });
});
          

Enable More Features

When you're ready, enable additional features by adding config options:

full config example

const config = createConfig({
  session: { secure: process.env.NODE_ENV === 'production' },

  // Enable features as needed:
  passwordRecovery: { enabled: true },
  emailVerification: { enabled: true },
  loginHistory: { enabled: true },
  sessionManagement: { enabled: true },

  // Username support:
  registration: {
    fields: { username: { enabled: true, required: true } },
  },
  login: {
    identifiers: ['email', 'username'],
    allowGoogleOAuth: true,
  },

  // Security:
  security: {
    accountLockout: { enabled: true },
  },

  email: { adapter: 'console' }, // 'nodemailer' in prod
});
          

Explore Features → Read the Docs →