🧱 NodeAuth: A Production-Ready Auth Starter Kit for Node.js Developers
Talha Bilal
Full Stack Developer
Talha Bilal
5 - 10 min
Tired of rewriting authentication for every Node.js project? NodeAuth is an open-source, production-grade starter kit with JWT, refresh tokens, cookie-based auth, and clean architecture. Built for devs who ship fast and secure.
🧠 Introduction
Every time I kicked off a new Node.js project, I hit the same wall: “ugh, auth again?”You know the drill—set up registration, hashing, login, JWTs, refresh tokens, secure cookies… and somehow make it not suck.
That repetitive grind led me to create NodeAuth—a clean, production-ready authentication starter built with Node.js, MongoDB, Argon2, and JWT-based access & refresh token flow, all wrapped in a well-organized folder structure that doesn’t turn into spaghetti after two routes.
🧱 NodeAuth: A Production-Ready Auth Starter Kit for Node.js Developers | Talha Bilal - Web Development Blog
👨💻 Who’s this for?
Fullstack devs who want a reliable base to build on—no more auth copy-pasta.
Bootstrappers & indie hackers who need auth done right without wasting 3 days reading Medium posts.
Anyone who wants a tested, secure, scalable backend that just works.
❤️ Open Source
I open-sourced this project because auth is a pain point everyone hits. No one should have to reinvent this wheel.
NodeAuth comes with everything you need to hit the ground running with real-world authentication in a Node.js backend. No fluff—just the stuff that matters.
🔑 JWT Access + Refresh Token Flow
Secure, stateless authentication using short-lived access tokens and long-lived refresh tokens to keep users logged in without compromising security.
🧰 Modular Middleware System
Includes clean, reusable middleware functions for:
Auth token validation
Route protection Easily plug them into any Express route or scale with custom logic.
🍪 Cookie-Based Auth (Not localStorage)
Tokens are stored in HTTP-only cookies—so they’re safe from XSS attacks. No weird hacks. No exposing tokens to the frontend.
🧂 Argon2 Password Hashing + MongoDB
Passwords are hashed using Argon2, a modern and secure hashing algorithm, and stored in MongoDB—flexible and production-tested.
🧪 Optional Testing with Vitest + Supertest
Includes setup for writing unit and integration tests using Vitest and Supertest, so you can ship confidently.
🏗️ Project Structure Explained
No one likes digging through spaghetti code or bloated monoliths. That’s why NodeAuth keeps things modular, minimal, and maintainable.
Here’s the folder structure at a glance:
🔍 Folder-by-Folder Breakdown
config/ – Configuration files for database and environment variables
controllers/ – Logic that handles the actual request/response cycle. Keeps your routes thin and your brains sane.
middlewares/ – Reusable functions like authMiddleware for protecting routes and handling common behaviors.
models/ – Mongoose schemas live here. Currently just User, but ready to scale.
routes/ – All your API endpoints are defined here, grouped by feature (auth for now).
tests/ – Vitest + Supertest powered test cases to keep your code legit.
utils/ – Utility functions like token generation and validation.
app.js / server.js – Entry point setup with Express and server boot-up logic.
.env.example – Sample environment variables to help devs get started fast.
🔐 Auth Flow Deep Dive
You’re not just slapping JWTs on a project and calling it a day—this is a full-stack, real-world authentication flow built to handle login, refresh tokens, and logout like a champ.
Here’s the high-level flow:
User Registers → Email + password → hashed with Argon2 → stored in MongoDB
User Logs In → Valid creds → Generate JWT access & refresh tokens → Set as HTTP-only cookies
Access Token Used → Sent with every request → Middleware validates it
Access Token Expires? → Use Refresh Token to get a new one
User Logs Out → Clear cookies → Done securely
🔁 Token Strategy: JWT + Cookies
Access Token: Short-lived (~15 min), used to hit protected routes.
Refresh Token: Long-lived (~7 days), only used to re-issue access tokens.
Both tokens are stored in HTTP-only, Secure cookies — no localStorage hacks, no XSS vulnerabilities.
This isn’t just a pretty boilerplate—it’s battle-tested too. Yup, we’ve got automated tests using Vitest and Supertest to make sure your endpoints don’t break when you sneeze on them.
🧰 The Stack
Vitest – Lightning-fast, Vite-native test runner with a Jest-like API.
Supertest – Makes HTTP assertions on your Express routes a breeze.
▶️ Running Tests
Running your test suite is easy:
npm test
🛠️ How to Extend or Customize
One of the best parts of NodeAuth is how hackable it is. You’re not locked into some black-box package—this is your code, your rules.
Here are a few ways to take it even further:
🔑 Add Google OAuth (or any social login)
Want that sweet, one-click login with Google, GitHub, etc.?
Use Passport.js with a strategy like passport-google-oauth20
Add an endpoint like /api/auth/google/callback
Store the user in your DB if they don’t exist yet
Set the same access + refresh token cookies
🧩 You’ve already got the session/token system built—OAuth just plugs in.
📧 Add Email Verification (with Tokens)
Right now, users register and boom—they’re in. To gate that with email verification:
Generate a unique email token on registration
Store it in DB (expires in X mins)
Send an email with a magic link (/verify-email?token=xyz)
On click → verify the token → mark user as verified: true
Bonus: lock login unless verified === true.
🛡️ Add Role-Based Access Control (RBAC)
Wanna protect admin routes?
Add a role field to your user schema (user, admin, etc.)
Create a custom middleware:
🧠 You’re Not Limited
Other cool ideas:
2FA with TOTP (like Google Authenticator)
Activity logging
Throttling + brute-force protection
Multi-tenant support (for SaaS vibes)
The structure is flexible. Extend it however your project needs.
🤝 . Conclusion & What’s Next
NodeAuth isn’t just a backend starter—it’s a launchpad for fullstack projects, MVPs, and anything that needs rock-solid authentication without reinventing the wheel.
If you're a dev building out a product, bootstrapping your SaaS, or just tired of wiring up the same login flow for the 100th time—this one’s for you.
🚀 What’s Next?
✅ Fastify + TypeScript version (coming soon)
✅ Neon + PostgreSQL integration
✅ NextAuth-compatible backend
✅ Maybe even a full-blown SaaS template
I’m building in public, so everything I ship will be open-source first.
