Express JWT Authentication Router

2.0.3 · active · verified Wed Apr 22

edaten-auth is a plug-and-play JWT authentication router designed for Express applications that utilize MongoDB for data persistence via Mongoose. It provides out-of-the-box functionality for user registration, login, token refreshing, and logout, simplifying the implementation of common authentication flows. The current stable version is 2.0.3. While a specific release cadence isn't explicitly stated, the project appears actively maintained given its current versioning. Its primary differentiator is its "plug-and-play" nature, offering a complete, pre-built solution for JWT authentication with Express and Mongoose, requiring minimal configuration beyond environment variables for secrets and ensuring a MongoDB connection. It manages access tokens and refresh tokens, storing the latter securely in HTTP-only cookies.

Common errors

```
Operation users.insertOne() buffering timed out after 10000ms
```
cause MongoDB connection was not established or was still in a pending state when `edaten-auth` attempted to perform database operations.

fix Verify that `await mongoose.connect(process.env.MONGO_URI);` has completed successfully *before* you mount the `edaten-auth` router with `app.use('/auth', createAuth(...));`.
```
TypeError: app.use is not a function
```
cause The `app` object in your Express application is not correctly initialized as an Express instance before `app.use` is called.

fix Ensure `const app = express();` is properly invoked to create an Express application instance at the start of your server setup.
```
jwt secret must be provided
```
cause The `jwtSecret` or `jwtRefreshSecret` configuration option was omitted or provided with an empty string when calling `createAuth`.

fix Provide valid and secure string values for both `jwtSecret` and `jwtRefreshSecret` in the options object passed to `createAuth`, preferably through environment variables.

Warnings

breaking The MongoDB connection must be fully established *before* initializing the `edaten-auth` router. Failure to do so can lead to 'Operation buffering timed out' errors, as the library attempts database operations before the connection is ready.
Fix: Ensure `await mongoose.connect(process.env.MONGO_URI);` completes successfully before `app.use('/auth', createAuth(...));` is called in your application startup.
gotcha The `cookie-parser` middleware is a mandatory dependency and must be explicitly registered with your Express application *before* `edaten-auth` is used. This is crucial for the refresh token mechanism, which relies on HTTP-only cookies.
Fix: Add `app.use(cookieParser());` to your Express application's middleware chain before `app.use('/auth', createAuth(...));`.
gotcha Both `jwtSecret` and `jwtRefreshSecret` are required configuration options for `createAuth`. Failing to provide these secure strings will prevent the library from initializing and functioning correctly, leading to runtime errors.
Fix: Ensure both `jwtSecret` and `jwtRefreshSecret` are passed in the options object to the `createAuth` function, ideally using environment variables for security (e.g., `jwtSecret: process.env.JWT_SECRET`).

Install

npm install edaten-auth npm
yarn add edaten-auth yarn
pnpm add edaten-auth pnpm

Imports

createAuth
wrong:
```
import { createAuth } from 'edaten-auth'
```
correct:
```
import createAuth from 'edaten-auth'
```
This is the default export, returning an Express router. CommonJS users should use `const createAuth = require('edaten-auth')`.
authMiddleware
wrong:
```
import { authMiddleware } from 'edaten-auth'
```
correct:
```
import { authMiddleware } from 'edaten-auth/middleware'
```
The authentication middleware for protecting routes is a named export from a subpath.
AuthOptions
```
import type { AuthOptions } from 'edaten-auth'
```
Type import for configuration options when using TypeScript.

Quickstart

Demonstrates the basic setup of the `edaten-auth` router within an Express application, including essential middleware and a critical Mongoose connection step.

import express from "express";
import cookieParser from "cookie-parser";
import mongoose from "mongoose";
import createAuth from "edaten-auth";

const app = express();

app.use(express.json());
app.use(cookieParser());

// IMPORTANT: connect MongoDB BEFORE using auth routes
// In a real application, ensure process.env.MONGO_URI is set.
await mongoose.connect(process.env.MONGO_URI ?? 'mongodb://localhost:27017/myauthdb');

app.use("/auth", createAuth({
  jwtSecret: process.env.JWT_SECRET ?? 'supersecretjwtkey',
  jwtRefreshSecret: process.env.JWT_REFRESH_SECRET ?? 'anothersupersecretrefreshkey',
  requiredFields: ["email"],
  loginField: "email"
}));

app.get('/', (req, res) => res.send('Welcome! Auth routes available at /auth'));

app.listen(3000, () => console.log('Server running on port 3000'));

view raw JSON →