JWT Authentication Boilerplate CLI

1.0.2 · active · verified Wed Apr 22

create-auth-app-cli is a command-line interface tool designed to rapidly scaffold a complete boilerplate for a JWT (JSON Web Token) authentication system. Currently at version 1.0.2, it provides a functional backend API with features such as user registration, login, logout, automatic token refresh, and robust Role-Based Access Control (RBAC). The generated project utilizes Node.js, Express.js, and MongoDB, incorporating security best practices like bcrypt for password hashing and HTTP-only cookies for refresh tokens. This CLI streamlines the setup process for backend authentication services, offering a clean and scalable project structure. Its release cadence is typically driven by updates to the underlying libraries in the generated template, security enhancements, or new features added to the boilerplate, rather than frequent releases of the CLI itself.

Common errors

```
MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017
```
cause The MongoDB server is not running or is inaccessible from the application. The application cannot establish a database connection.

fix Ensure MongoDB is running locally or that the `MONGO_URI` in your `.env` file points to a reachable MongoDB instance.
```
Error: secretOrPrivateKey must have a value
```
cause One of the JWT secrets (`ACCESS_TOKEN_SECRET` or `REFRESH_TOKEN_SECRET`) is not defined in the `.env` file, preventing token generation or verification.

fix Open your `.env` file and provide values for `ACCESS_TOKEN_SECRET` and `REFRESH_TOKEN_SECRET`. These should be strong, unique strings.
```
Error: listen EADDRINUSE: address already in use :::5000
```
cause Another process is already using the port that the Express server (default 5000) is trying to bind to.

fix Change the `PORT` variable in your `.env` file to an unused port (e.g., 3000, 8000), or terminate the process currently using port 5000.

Warnings

gotcha The generated project uses plain JavaScript and not TypeScript. Developers accustomed to TypeScript will need to manually convert the codebase if type safety is desired.
Fix: Consider using tools like `js-to-ts` or manually refactoring the generated code to TypeScript types and interfaces.
gotcha The scaffolded application requires a running MongoDB instance to function. If MongoDB is not accessible, the application will fail to connect and start.
Fix: Ensure MongoDB is installed and running, or update the `MONGO_URI` in the `.env` file to point to a valid MongoDB server.
breaking This is a new CLI tool (version 1.0.2). Future major versions (e.g., v2.0.0) may introduce breaking changes to the generated project structure, dependencies, or API endpoints. Always review the release notes before upgrading the CLI and regenerating projects.
Fix: Pin the CLI version (`npx create-auth-app-cli@1.x.x`) for existing projects, and thoroughly test any generated projects after upgrading the CLI.
gotcha The `.env.example` file provides placeholder secrets for `ACCESS_TOKEN_SECRET` and `REFRESH_TOKEN_SECRET`. These **must** be replaced with strong, unique, randomly generated secrets in production environments to ensure security.
Fix: Use a robust secret generation tool (e.g., `openssl rand -base64 32`) and manage these secrets securely, perhaps via environment variables provided by your hosting platform.

Install

npm install create-auth-app-cli npm
yarn add create-auth-app-cli yarn
pnpm add create-auth-app-cli pnpm

Imports

npx create-auth-app-cli
wrong:
```
import createAuthApp from 'create-auth-app-cli'
```
correct:
```
npx create-auth-app-cli my-auth-project
```
This package is a CLI tool and is executed directly via `npx` or globally installed. It does not export modules for direct programmatic import.
verifyToken
wrong:
```
const verifyToken = require('./src/middleware/auth');
```
correct:
```
import verifyToken from './src/middleware/auth.js';
```
This import is for a middleware *within the project generated by the CLI*, not from the CLI package itself. The generated project uses ES Modules.
authorizeRoles
wrong:
```
const authorizeRoles = require('./src/middleware/rbac');
```
correct:
```
import authorizeRoles from './src/middleware/rbac.js';
```
This import is for a middleware *within the project generated by the CLI*, not from the CLI package itself. The generated project uses ES Modules.

Quickstart

Scaffolds a new JWT authentication project, navigates into it, sets up environment variables, installs dependencies, and starts the development server.

npx create-auth-app-cli my-jwt-auth-backend
cd my-jwt-auth-backend
cp .env.example .env
# IMPORTANT: Fill in your actual secrets and MongoDB URI in .env
# For example:
# MONGO_URI=mongodb://localhost:27017/my-jwt-db
# ACCESS_TOKEN_SECRET=super_secret_jwt_key_123
# REFRESH_TOKEN_SECRET=another_super_secret_key_456
# Then install dependencies and run the server
npm install
npm run dev

view raw JSON →