@arbajit_sen/backend-pod-cli

Backend Pod CLI (node-pod)

A powerful, lightweight scaffolding CLI to spin up a fully-configured, production-ready Node.js, Express, and TypeScript application in seconds.

The generated project comes pre-equipped with essential architectural utilities like a custom memory-optimized rate limiter, global async controller wrappers, standardized JSON response handlers, security middleware, and a structured logging setup.

---

Quick Start

You can scaffold a new project instantly using npx without installing the package globally:

npx @arbajit_sen/backend-pod-cli <project-name>

For example:

npx @arbajit_sen/backend-pod-cli my-awesome-api

---

Global Installation

Alternatively, you can install the CLI globally on your system to use the node-pod command anytime:

npm install -g @arbajit_sen/backend-pod-cli

Once installed, simply run:

node-pod my-awesome-api

---

Features Included in the Template

Every project generated by node-pod includes:

• TypeScript Core: Strict mode configurations, paths, and build scripts.
• Custom Optimized Rate Limiter:
  • An in-memory, fixed-window rate limiter designed to work out-of-the-box.
  • Automatically appends standard rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset).
  • Proactive background cleanup sweeps to automatically prune expired entries, avoiding memory leaks.
• Global Controller Wrapper:
  • Eliminates the need to write try-catch blocks inside every route handler.
  • Handles synchronous and asynchronous controller errors, automatically routing them to the global error middleware.
• Standardized API Responses:
  • successResponse and errorResponse helpers that guarantee a predictable payload structure across all endpoints.
• Structured Error Handling:
  • A centralized error middleware that formats and logs exceptions.
• Advanced Security & Middleware:
  • Pre-configured helmet (security headers), cors (Cross-Origin Resource Sharing), and cookie-parser.
• Winston Logger:
  • Pre-configured for daily rolling files and console output with distinct formatting for development and production environments.

---

Generated Project Structure

├── .husky/              # Git hooks configuration
├── src/
│   ├── configs/
│   │   └── wrappers/
│   │       ├── controllerWrapper.ts   # Error-catching controller wrapper
│   │       └── responseWrapper.ts     # Standardized JSON success/error response helpers
│   ├── controllers/
│   │   └── healthController.ts        # Sample health controller demonstrating wrappers
│   ├── middleware/
│   │   ├── errorHandler.ts            # Global express error handler using response wrapper
│   │   ├── rateLimiter.ts             # Custom memory-safe rate limiter middleware
│   │   └── requestLogger.ts           # HTTP request logger middleware
│   ├── routes/
│   │   ├── healthRoutes.ts            # Routes for healthcheck
│   │   └── index.ts                   # Router registry
│   ├── services/
│   │   └── healthService.ts           # Health check business logic
│   ├── utils/
│   │   └── logger.ts                  # Winston rolling file logger setup
│   ├── app.ts                         # Express application setup and global middleware mounts
│   └── server.ts                      # Server bootstrap & graceful shutdown handler
├── .env.example                       # Base environment variables
├── .eslintrc.json                     # Code quality configuration
├── .prettierrc                        # Code formatting configuration
├── nodemon.json                       # Live-reloading configuration
├── tsconfig.json                      # Compiler configurations
└── package.json                       # Scripts and project dependencies

---

Developed Scripts

After generating the project and navigating into its directory (cd <project-name>), you can run the following scripts:

Command	Description
npm run dev	Starts the server in development mode with active file-watching and hot-reloads via nodemon.
npm run build	Compiles the TypeScript source files inside /src to JavaScript files inside /dist.
npm run start	Boots the compiled production application located in the /dist directory.
npm run lint	Runs ESLint check across all TypeScript source files.
npm run lint:fix	Audits the codebase and automatically fixes all auto-repairable ESLint issues.
npm run format	Enforces unified styling by formatting all files with Prettier.

---

How the Architecture Works

1. Global Controller Wrapper (controllerWrapper)

Avoid adding try-catch blocks to every async controller function. Wrap your handler with controllerWrapper, and any rejected Promise will automatically be caught and passed to the Express error middleware:

import { Request, Response } from "express";
import { controllerWrapper } from "../configs/wrappers/controllerWrapper";
import { successResponse } from "../configs/wrappers/responseWrapper";

export const getUserProfile = controllerWrapper(async (req: Request, res: Response) => {
  const user = await database.findUser(req.params.id);
  
  if (!user) {
    throw { statusCode: 404, message: "User not found" };
  }
  
  successResponse(res, user, "User profile retrieved successfully");
});

2. Standardized Response Format

Success payloads conform to:

{
  "success": true,
  "message": "User profile retrieved successfully",
  "data": { ... }
}

Error payloads (including global 404s and unhandled server errors) conform to:

{
  "success": false,
  "message": "User not found"
}

3. Custom Rate Limiter

The rate limiter operates without external dependencies (no express-rate-limit or Redis package required). Memory leaks are prevented via a periodic background cleanup routine:

import { CustomRateLimiter } from "./middleware/rateLimiter";

// Create custom threshold
const limiter = new CustomRateLimiter({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // Limit each IP to 100 requests per window
  message: "Too many requests, please try again later."
});

app.use(limiter.middleware());

---

License

This CLI and scaffolded codebase is open-source and licensed under the ISC License.