create-express-kickstart 1.0.0

package/.env.example

@@ -0,0 +1,8 @@
+PORT=8000
+MONGODB_URI=mongodb://localhost:27017/
+CORS_ORIGIN=*
+NODE_ENV=development
+
+# Rate Limiting
+RATE_LIMIT_WINDOW_MS=900000 # 15 minutes in milliseconds
+RATE_LIMIT_MAX=100 # Maximum requests per windowMs

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aasif Ashraf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# create-express-kickstart
+
+[![Node.js](https://img.shields.io/badge/Node.js-Production_Ready-339933?style=for-the-badge&logo=node.js)](https://nodejs.org/)
+[![Express.js](https://img.shields.io/badge/Express.js-Backend-000000?style=for-the-badge&logo=express)](https://expressjs.com/)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg?style=for-the-badge)](https://opensource.org/licenses/ISC)
+
+A powerful CLI tool to instantly scaffold a production-ready, feature-rich backend Node.js template specifically tailored for Express API applications. It adheres to modern best practices, providing standard structures for error handling, CORS setups, routing, and middlewares right out of the box.
+
+---
+
+## 🚀 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
+
+Run the following command anywhere in your terminal:
+```bash
+npx create-express-kickstart <your-project-name>
+```
+
+**Example:**
+```bash
+npx create-express-kickstart 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. **Latest Dependencies:** It automatically runs `npm install` and fetches the absolute **latest** stable versions of `express`, `cors`, `helmet`, `mongoose`, `dotenv` and others so you're never starting with outdated software.
+
+### 3. Run Your Application
+
+Navigate into your newly created folder and fire up the development server!
+```bash
+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.
+```javascript
+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.
+```javascript
+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.

package/bin/cli.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import readline from 'readline';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+const question = (query) => new Promise((resolve) => rl.question(query, resolve));
+
+async function init() {
+  const projectNameArg = process.argv[2];
+  
+  let projectName = projectNameArg;
+  if (!projectName) {
+    projectName = await question('\n👉 Project name (e.g. my-awesome-api): ');
+  }
+  
+  if (!projectName) {
+    console.error('\n❌ Error: Project name is required.');
+    process.exit(1);
+  }
+
+  const currentPath = process.cwd();
+  const projectPath = path.join(currentPath, projectName);
+
+  if (fs.existsSync(projectPath)) {
+    console.error(`\n❌ Error: Folder ${projectName} already exists. Please choose a different name.\n`);
+    process.exit(1);
+  }
+
+  const description = await question('👉 Project description: ');
+  const author = await question('👉 Author name: ');
+
+  console.log('\n--- 📦 Select Dependencies ---');
+  console.log('Press Enter for Yes (Y), type "n" for No.\n');
+
+  const deps = {
+    express: true, // Always required
+    mongoose: (await question('Include Mongoose (MongoDB)? [Y/n] ')).toLowerCase() !== 'n',
+    cors: (await question('Include CORS? [Y/n] ')).toLowerCase() !== 'n',
+    helmet: (await question('Include Helmet (Security headers)? [Y/n] ')).toLowerCase() !== 'n',
+    'cookie-parser': (await question('Include cookie-parser? [Y/n] ')).toLowerCase() !== 'n',
+    'pino-http': (await question('Include Pino (HTTP Logger)? [Y/n] ')).toLowerCase() !== 'n',
+    'express-rate-limit': (await question('Include Rate Limiting? [Y/n] ')).toLowerCase() !== 'n',
+    dotenv: (await question('Include dotenv (Environment variables)? [Y/n] ')).toLowerCase() !== 'n',
+    prettier: (await question('Include Prettier (Code formatter)? [Y/n] ')).toLowerCase() !== 'n'
+  };
+
+  let installPinoPretty = false;
+  if (deps['pino-http']) {
+    installPinoPretty = (await question('Include pino-pretty for clean development logs? [Y/n] ')).toLowerCase() !== 'n';
+  }
+
+  rl.close();
+
+  console.log(`\n🚀 Creating a new Node.js Express API in ${projectPath}...`);
+  fs.mkdirSync(projectPath, { recursive: true });
+
+  function copyRecursiveSync(src, dest) {
+    const exists = fs.existsSync(src);
+    const stats = exists && fs.statSync(src);
+    const isDirectory = exists && stats.isDirectory();
+    if (isDirectory) {
+      fs.mkdirSync(dest, { recursive: true });
+      fs.readdirSync(src).forEach((childItemName) => {
+        copyRecursiveSync(path.join(src, childItemName), path.join(dest, childItemName));
+      });
+    } else {
+      fs.copyFileSync(src, dest);
+    }
+  }
+
+  // 1. Copy src directory
+  const sourceDir = path.join(__dirname, '..', 'src');
+  const targetSrcDir = path.join(projectPath, 'src');
+
+  if (!fs.existsSync(sourceDir)) {
+    console.error('\n❌ Error: Could not find "src" directory in the template generator.');
+    process.exit(1);
+  }
+
+  console.log(`📂 Bootstrapping application structure (errorHandler, ApiResponse, async handlers)...`);
+  copyRecursiveSync(sourceDir, targetSrcDir);
+
+  // 2. Copy .env.example
+  console.log(`🔧 Generating environment files...`);
+  const envExamplePath = path.join(__dirname, '..', '.env.example');
+  if (fs.existsSync(envExamplePath)) {
+    fs.copyFileSync(envExamplePath, path.join(projectPath, '.env.example'));
+    fs.copyFileSync(envExamplePath, path.join(projectPath, '.env')); 
+  }
+
+  // 3. Create package.json
+  console.log(`📦 Setting up package.json...`);
+  const packageJsonTemplate = {
+    name: projectName,
+    version: "1.0.0",
+    description: description || "A production-ready Node.js Express API",
+    main: "src/server.js",
+    type: "module",
+    scripts: {
+      "start": "node src/server.js",
+      "dev": "nodemon src/server.js"
+    },
+    imports: {
+      "#*": "./src/*"
+    },
+    keywords: ["express", "node", "api"],
+    author: author || "",
+    license: "ISC"
+  };
+
+  if (deps.prettier) {
+    packageJsonTemplate.scripts.format = "prettier --write \"src/**/*.{js,json}\"";
+  }
+
+  // Remove the readline dependency from the generated boilerplate if mistakenly mixed
+  fs.writeFileSync(
+    path.join(projectPath, 'package.json'), 
+    JSON.stringify(packageJsonTemplate, null, 2)
+  );
+
+  // 4. Install Dependencies
+  const dependenciesToInstall = Object.keys(deps).filter(dep => deps[dep] && dep !== 'prettier');
+  if (deps['pino-http']) {
+    dependenciesToInstall.push('pino');
+  }
+  const depString = dependenciesToInstall.join(' ');
+  
+  const devDependenciesToInstall = ['nodemon'];
+  if (deps.prettier) devDependenciesToInstall.push('prettier');
+  if (installPinoPretty) devDependenciesToInstall.push('pino-pretty');
+  const devDepString = devDependenciesToInstall.join(' ');
+
+  console.log(`\n⏳ Installing selected core dependencies (${dependenciesToInstall.join(', ')}). This might take a minute...`);
+  try {
+    if (depString) {
+      execSync(`npm install ${depString}`, { 
+        cwd: projectPath, 
+        stdio: 'inherit' 
+      });
+    }
+    
+    console.log(`\n⏳ Installing latest dev dependencies (${devDepString})...`);
+    execSync(`npm install ${devDepString} --save-dev`, { 
+      cwd: projectPath, 
+      stdio: 'inherit' 
+    });
+
+    console.log(`\n✅ Success! Created "${projectName}" at ${projectPath}`);
+    console.log('\nInside that directory, you can run several commands:');
+    console.log('\n  npm run dev');
+    console.log('    Starts the development server on localhost.');
+    console.log('\n  npm start');
+    console.log('    Starts the production server.');
+    console.log('\nWe suggest that you begin by typing:');
+    console.log(`\n  cd ${projectName}`);
+    console.log('  npm run dev\n');
+  } catch (err) {
+    console.error('\n❌ Failed to install dependencies. You may need to run npm install manually inside the folder.', err);
+  }
+}
+
+init().catch(err => {
+  console.error('\n❌ Unexpected error occurred:', err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "create-express-kickstart",
+  "version": "1.0.0",
+  "description": "Production-ready CLI starter for Express APIs",
+  "main": "bin/cli.js",
+  "bin": {
+    "create-express-kickstart": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "cli",
+    "create",
+    "express",
+    "nodejs",
+    "starter",
+    "template",
+    "boilerplate"
+  ],
+  "author": "Your Name",
+  "license": "ISC",
+  "type": "module",
+  "dependencies": {
+  }
+}

package/src/app.js

@@ -0,0 +1,75 @@
+import express from "express";
+import cors from "cors";
+import cookieParser from "cookie-parser";
+import helmet from "helmet";
+import pinoHttp from "pino-http";
+import rateLimit from "express-rate-limit";
+import { errorHandler } from "#middlewares/errorHandler.middleware.js";
+
+// Import routers
+import healthcheckRouter from "#routes/healthcheck.routes.js";
+
+const app = express();
+
+// Security HTTP headers
+app.use(helmet());
+
+// Rate Limiting
+const limiter = rateLimit({
+    windowMs: process.env.RATE_LIMIT_WINDOW_MS || 15 * 60 * 1000, // Default 15 minutes
+    limit: process.env.RATE_LIMIT_MAX || 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes)
+    standardHeaders: 'draft-7', // draft-6: `RateLimit-*` headers; draft-7: combined `RateLimit` header
+    legacyHeaders: false, // Disable the `X-RateLimit-*` headers
+    message: "Too many requests from this IP, please try again later"
+});
+app.use("/api", limiter); // Apply rate limiting to all API routes
+
+// Logging
+app.use(pinoHttp({
+    customLogLevel: function (req, res, err) {
+        if (res.statusCode >= 400 && res.statusCode < 500) {
+            return 'warn'
+        } else if (res.statusCode >= 500 || err) {
+            return 'error'
+        } else if (res.statusCode >= 300 && res.statusCode < 400) {
+            return 'silent'
+        }
+        return 'info'
+    },
+    // Dynamically require pino-pretty if in dev and it exists, else undefined
+    transport: process.env.NODE_ENV === "development" ? (function() {
+        try {
+            import("pino-pretty");
+            return {
+                target: 'pino-pretty',
+                options: { colorize: true }
+            };
+        } catch (e) {
+            return undefined;
+        }
+    })() : undefined
+}));
+
+// CORS setup
+app.use(
+    cors({
+        origin: process.env.CORS_ORIGIN || "*", // Fallback to allowing everything
+        credentials: true, // Allow cookies with requests
+    })
+);
+
+// Payload sizes and forms
+app.use(express.json({ limit: "16kb" }));
+app.use(express.urlencoded({ extended: true, limit: "16kb" }));
+app.use(express.static("public")); 
+app.use(cookieParser());
+
+// -------- API ROUTES ---------
+// Mount routers
+app.use("/api/v1/healthcheck", healthcheckRouter);
+
+// Global Error Handler
+// Always add this as the very last middleware
+app.use(errorHandler);
+
+export { app };

package/src/controllers/healthcheck.controller.js

@@ -0,0 +1,17 @@
+import { ApiError } from "#utils/ApiError.js";
+import { ApiResponse } from "#utils/ApiResponse.js";
+import { asyncHandler } from "#utils/asyncHandler.js";
+
+const healthcheck = asyncHandler(async (req, res) => {
+    // Basic health check
+    return res
+        .status(200)
+        .json(new ApiResponse(200, { status: "OK", timestamp: Date.now() }, "App is running smoothly"));
+});
+
+const triggerError = asyncHandler(async (req, res) => {
+    // Dummy route to test the global error handler
+    throw new ApiError(400, "This is a custom error thrown for testing purposes.");
+});
+
+export { healthcheck, triggerError };

package/src/db/index.js

@@ -0,0 +1,14 @@
+import mongoose from "mongoose";
+import { DB_NAME } from "#utils/constants.js";
+
+const connectDB = async () => {
+    try {
+        const connectionInstance = await mongoose.connect(`${process.env.MONGODB_URI}/${DB_NAME}`);
+        console.log(`\n MongoDB connected !! DB HOST: ${connectionInstance.connection.host}`);
+    } catch (error) {
+        console.error("MONGODB connection FAILED ", error);
+        process.exit(1);
+    }
+};
+
+export default connectDB;

package/src/middlewares/errorHandler.middleware.js

@@ -0,0 +1,37 @@
+import { ApiError } from '#utils/ApiError.js';
+
+/**
+ * Global Error Handler Middleware
+ * @param {Error} err
+ * @param {Request} req
+ * @param {Response} res
+ * @param {NextFunction} next
+ */
+const errorHandler = (err, req, res, next) => {
+    let error = err;
+
+    // If the error is not an instance of ApiError, transform it into one
+    if (!(error instanceof ApiError)) {
+        const statusCode = error.statusCode ? error.statusCode : 500;
+        const message = error.message || "Internal Server Error";
+        
+        error = new ApiError(
+            statusCode,
+            message,
+            error?.errors || [], // Pass down any validation errors
+            err.stack // Keep the original stack trace
+        );
+    }
+
+    // Now format the consistent response
+    const response = {
+        ...error,
+        message: error.message,
+        ...(process.env.NODE_ENV === 'development' ? { stack: error.stack } : {})
+    };
+
+    // Send the JSON response
+    return res.status(error.statusCode).json(response);
+};
+
+export { errorHandler };

package/src/models/example-model.js

@@ -0,0 +1,18 @@
+//example-model.js
+import mongoose from "mongoose";
+
+const exampleSchema = new mongoose.Schema({
+    name: {
+        type: String,
+        required: [true, "Name is required"],
+    },
+    age: {
+        type: Number,
+        required: [true, "Age is required"],
+    },
+    email: {
+        type: String,
+        required: [true, "Email is required"],
+        unique: true,
+    },
+});

package/src/routes/healthcheck.routes.js

@@ -0,0 +1,9 @@
+import { Router } from 'express';
+import { healthcheck, triggerError } from '#controllers/healthcheck.controller.js';
+
+const router = Router();
+
+router.route('/').get(healthcheck);
+router.route('/error').get(triggerError);
+
+export default router;

package/src/server.js

@@ -0,0 +1,27 @@
+import dotenv from "dotenv";
+import { app } from "#app.js";
+
+// Load environment variables from .env file
+dotenv.config({
+    path: './.env'
+});
+
+import connectDB from "#db/index.js";
+
+const PORT = process.env.PORT || 8000;
+
+connectDB()
+    .then(() => {
+        app.listen(PORT, () => {
+            console.log(`Server is running at port : ${PORT}`);
+        });
+    })
+    .catch((err) => {
+        console.log("MONGO db connection failed !!! ", err);
+    });
+
+process.on("unhandledRejection", (err) => {
+    console.log("UNHANDLED REJECTION! Shutting down...");
+    console.log(err.name, err.message);
+    process.exit(1);
+});

package/src/utils/ApiError.js

@@ -0,0 +1,23 @@
+class ApiError extends Error {
+    constructor(
+        statusCode,
+        message = "Something went wrong",
+        errors = [],
+        stack = ""
+    ) {
+        super(message);
+        this.statusCode = statusCode;
+        this.data = null;
+        this.message = message;
+        this.success = false;
+        this.errors = errors;
+
+        if (stack) {
+            this.stack = stack;
+        } else {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+
+export { ApiError }

package/src/utils/ApiResponse.js

@@ -0,0 +1,10 @@
+class ApiResponse {
+    constructor(statusCode, data, message = "Success") {
+        this.statusCode = statusCode;
+        this.data = data;
+        this.message = message;
+        this.success = statusCode < 400; // Success is true if status code is not an error level
+    }
+}
+
+export { ApiResponse }

package/src/utils/asyncHandler.js

@@ -0,0 +1,7 @@
+const asyncHandler = (requestHandler) => {
+    return (req, res, next) => {
+        Promise.resolve(requestHandler(req, res, next)).catch((err) => next(err));
+    };
+};
+
+export { asyncHandler };

package/src/utils/constants.js

@@ -0,0 +1 @@
+export const DB_NAME = "my_app_db";