Portfolio Project · Authentication Boilerplate

Next.js Authentication Boilerplate

A production-leaning authentication boilerplate built with Next.js, TypeScript, JWT, and Tailwind CSS.

Easy to use and swap database repositories to switch between databases such as MongoDb and PostgreSQL, or any other database as needed. Email provider is also easy to swap, to ensure compatibility with any future projects

Real-world Auth

Email + password login, JWT access and refresh tokens, HttpOnly cookies, protected routes, and password reset flow wired end to end.

Clean Architecture

Separation between UI, services, domain logic, and infrastructure: repositories, email providers, rate limiting, and environment handling.

Tested & CI Ready

Vitest unit tests for core modules and a GitHub Actions workflow that runs the test suite on every push and pull request.

Tech Stack

Built with a modern, production-oriented stack:

Next.js (App Router)TypeScriptTailwind CSSJWT (access + refresh)ZodVitestESLint (flat config)PrettierGitHub Workflows

Architecture at a Glance

The project is structured to be easy to extend into a real product:

Auth & Domain

  • src/lib/auth/domain – auth service, JWT handling, password hashing
  • UserRepository abstraction with in-memory implementation for testing, as well as mongoDb implementation, easy to switch between repositories.
  • Password reset tokens + pluggable email provider

API & Middleware

  • REST-style route handlers under `/api/auth/*`
  • Shared error handler and rate limiter for consistent responses
  • Middleware-protected routes for `/dashboard` and auth-only pages

For a deeper, more technical breakdown of the architecture, visit the About page.

How to Explore This Demo

  1. Register a new account using the registration page.
  2. Log in and navigate to the dashboard to see a protected page.
  3. Try logging out and visiting the dashboard again to test the middleware.
  4. Trigger the forgot/reset password flow. Check your email for a link with resetToken, enter the link and reset your password.

Services / Use Cases

This boilerplate was designed for me to learn JWT and practice with the technologies listed, showcase to employers as part of my portfolio, and create a boilerplate for future projects that may utilize authentication, role-based access control, and clean architecture. This boilerplate is easy to extend, and database and email provider are easy to swap

Contact

Want to work together or see more of my work? Feel free to reach out via email or connect through the links in the footer.