Registration Kit

A full-stack authentication starter designed for modern web applications. It ships a working React client, an Express API, and a MongoDB data layer — all connected and ready to customise.

What's Included

• Registration with OTP — user signs up, receives a one-time code by email, activates the account
• Login — credential-based login with JWT; token validity configurable via JWT_EXPIRES_IN
• Two-Factor Authentication — TOTP setup via QR code (compatible with Authenticator apps), backup codes included
• Forgot / Reset Password — email OTP flow for secure password recovery
• User Profile — read and update profile data, change password, enable/disable 2FA
• Mock Provider — set VITE_PROVIDER=mock to run the full client without a backend; every flow works with simulated responses
• Provider Pattern — swap auth/user implementations via a single env variable; drop in your own API without touching UI code

Tech Stack

Client

• React 18 + TypeScript
• Material-UI v7
• Valtio (state management)
• React Hook Form
• React Router v6
• Vite 8

Server

• Express 4 + TypeScript
• Mongoose / MongoDB
• JWT authentication
• Nodemailer (email OTP)

Shared

• DTOs and types shared between client and server via @shared path alias
• Zod validation on shared schemas

Getting Started

# 1. Install dependencies
pnpm install

# 2. Configure environment
cp server/.env.example server/.env
cp client/.env.example client/.env

# 3. Start development (client + server)
pnpm dev

Open http://localhost:5173 for the client and http://localhost:3000 for the API.

No backend yet? Set VITE_PROVIDER=mock in client/.env and start only the client. All auth flows simulate correctly without a running server.

Prerequisites

• Node.js 20+
• pnpm
• MongoDB (local or Atlas) — only needed when running the server
• SMTP credentials (for real email OTP) — Mailtrap or similar works for development

Project Structure

registration-kit/
├── client/          # React + Vite frontend
│   └── src/
│       ├── api/     # auth + user providers (live & mock)
│       ├── components/
│       ├── pages/
│       └── store/
├── server/          # Express + TypeScript API
│   └── src/
│       ├── controllers/
│       ├── services/
│       ├── models/
│       └── routes/
├── shared/          # DTOs and types shared between client and server
└── package.json

Auth Flows

Registration

1. User submits email + password
2. Server creates an inactive account and sends a 6-digit OTP
3. User enters the OTP → account activated

Login

• Standard: returns a JWT
• With 2FA enabled: returns a challenge token, prompts for TOTP code, then issues the JWT

Two-Factor Authentication

• Setup via QR code scan in any Authenticator app (Google Authenticator, Authy, etc.)
• On setup confirmation, server returns one-time backup codes
• Disable 2FA from the profile page at any time

Password Reset

1. User requests a reset code sent to their email
2. Enters the code + new password → password updated

Configuration

Key variables in server/.env:

MONGODB_URI=mongodb://localhost:27017/registration-kit
JWT_SECRET=your-secret
JWT_EXPIRES_IN=15d
SMTP_HOST=smtp.mailtrap.io
SMTP_PORT=587
SMTP_USER=...
SMTP_PASS=...

Key variables in client/.env:

VITE_API_URL=http://localhost:3000
VITE_PROVIDER=live   # or 'mock' for no-backend dev

License

Registration Kit ships under a commercial license with three tiers — Developer, Team, and Extended. See the license page for full terms and what each tier allows.