create-express-kickstart

A configurable CLI tool to scaffold a solid Express API foundation with sane defaults for routing, middleware, error handling, auth starters, and Docker support.

Quick Start

npx create-express-kickstart@latest my-app

What is create-express-kickstart?

The Purpose: Whenever developers start a new Node.js & Express.js project, they often spend the first couple of hours writing the same setup code: configuring express, setting up cors, managing environment variables, writing global error handlers, standardizing API responses, and wiring database connections. create-express-kickstart exists to remove that repetitive setup so you can move straight into business logic with a consistent starter.

What It Does: It is an interactive CLI framework scaffolding generator. Upon running the command, it asks you a series of simple questions regarding the architecture of your new API (e.g., Do you want MongoDB? Do you want JWT Auth Boilerplate? Docker? Jest for testing?). Based on your exact answers, it instantly generates a fully configured, running codebase tailored exclusively to your project's needs.

How It Works: Under the hood, the CLI runs dynamically directly from NPM via npx executing a Node.js compiler script:

1. Interactive Prompting: The CLI polls for your configurations in real-time.
2. Selective Templating: It recursively copies a pre-configured, highly modular src application design into your directory.
3. Selective Scaffolding: If you opt out of specific modules like CORS, Pino, or Mongoose, the generator removes those pieces from the generated app so you do not start with unused code.
4. Dependency Bootstrapping: It writes a project-specific package.json, installs the selected dependencies with your chosen package manager (npm, yarn, pnpm, or bun), and pins installed versions when the install completes successfully.

What is Inside (The Architecture): The generated Express template champions the MVC (Model-View-Controller) pattern with robust modern Node.js Path Aliasing bindings enabled out of the box:

• /src/controllers - Functional logic handlers.
• /src/routes - Isolated Express routers mapping precise endpoints to controllers.
• /src/middlewares - Pre-configured intercepts including a robust Global errorHandler.
• /src/utils - Core toolkit items mapped globally across the codebase. Highlights include:
  • ApiResponse structure class for predictable and formatted JSON HTTP payloads.
  • ApiError extension class for standardizing HTTP error interceptions.
  • asyncHandler functional wrapper intercepting promise rejections seamlessly to avoid repetitive try-catch blocks in your controllers!
• Optional Add-ons - JWT + Mongo auth starter routes, generated cryptographic helpers (bcryptjs and jsonwebtoken), Docker templates, and Jest healthcheck tests.

Getting Started

You do not need to clone this repository, install dependencies manually, or write an initial configuration yourself. Use npx (which comes with npm 5.2+) to instantly generate your backend boilerplate!

1. Initialize a New Project

We highly recommend using the @latest tag to ensure you are always downloading the most recent version of our CLI tool dynamically, bypassing any local caching issues!

Run the following command anywhere in your terminal:

npx create-express-kickstart@latest <your-project-name>

Example:

npx create-express-kickstart@latest my-awesome-api

2. What happens under the hood?

1. Scaffolding: It instantly generates your API boilerplate with built-in errorHandler, ApiResponse, and asyncHandler classes/utilities.
2. Setup: It automatically configures .env, path resolutions, and modern ES setups inside package.json.
3. Selected Dependencies: It installs the dependencies you chose for that project, including Express middleware, MongoDB support, Docker assets, or JWT auth scaffolding when requested.

3. Run Your Application

Navigate into your newly created folder and fire up the development server!

cd my-awesome-api
npm run dev

Features

• Modern JavaScript: ES6 Modules (import/export) enabled by default.
• Robust Error Handling: Centralized error management using custom ApiError and errorHandler middleware.
• Standardized Responses: Consistent API responses using the ApiResponse utility class.
• No Try-Catch Hell: asyncHandler wrapper to effortlessly catch unhandled promise rejections.
• Security First: Pre-configured with helmet, cors, and express-rate-limit.
• Database Ready: Built-in support and structural setup for MongoDB with mongoose.
• Developer Experience: Hot reloading with nodemon and request logging with pino.
• Path Aliasing Native: Pre-configured subpath imports (#utils/...).

Core Utilities Built-In

This template shines in its standardized utilities available out of the box for you:

ApiResponse

Guarantees a standard format for all successful payload JSON responses.

import { ApiResponse } from "#utils/ApiResponse.js";

const getUserInfo = asyncHandler(async (req, res) => {
    const data = { id: 1, name: "Alice" };
    return res.status(200).json(new ApiResponse(200, data, "User retrieved successfully"));
});

ApiError & errorHandler

Throw operational errors anywhere, and the global errorHandler will format them predictably for the client.

import { ApiError } from "#utils/ApiError.js";

const restrictedRoute = asyncHandler(async (req, res) => {
    // Automatically caught by the async handler and forwarded to the error handler
    throw new ApiError(403, "You do not have permission to view this content.");
});

asyncHandler

A wrapper for your async route handlers that eliminates the need for repetitive try-catch blocks.

jwt.util.js & hash.util.js

If you choose the JWT auth starter, the generated app includes Mongoose-backed auth routes, secure password hashing utilities, JWT helpers, and placeholder environment configuration for secrets.

import { hashData, compareData } from "#utils/hash.util.js";
import { generateToken, verifyToken } from "#utils/jwt.util.js";

const registerUser = asyncHandler(async (req, res) => {
    const hashedPassword = await hashData("supersecret123");
    // Store hashedPassword...
});

const loginUser = asyncHandler(async (req, res) => {
    const isMatch = await compareData("supersecret123", user.hashedPassword);
    
    // Generate JWT natively hooked up to process.env.JWT_SECRET
    const token = generateToken({ id: user._id, role: "user" });
    return res.json({ token });
});

Contributing & Repository

Love this tool? Want to add a feature or fix a bug? Feel free to open an issue or submit a pull request on our GitHub Repository!

GitHub Repository: https://github.com/aasifashraf/create-express-kickstart

NPM Package: https://www.npmjs.com/package/create-express-kickstart