express-ts-api-starter 1.2.0 → 1.3.0

package/.env.example

@@ -0,0 +1,23 @@
+# Environment Configuration
+NODE_ENV=development
+
+# Server Configuration
+PORT=5000
+BASIC_API_URL=/api/v1
+
+# Database Configuration
+DB_CONNECTION=mongodb://localhost:27017/
+DB_NAME=testDB
+
+# Authentication
+JWT_SECRET=your-super-secret-jwt-key-change-in-production
+
+# Email Configuration (if using email features)
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=your-email@gmail.com
+SMTP_PASSWORD=your-app-password
+
+# Optional: Third-party APIs
+# API_KEY=your-api-key
+# EXTERNAL_SERVICE_URL=https://api.example.com

package/.gitignore

@@ -0,0 +1,136 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# vitepress build output
+**/.vitepress/dist
+
+# vitepress cache directory
+**/.vitepress/cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*

package/README.md

@@ -13,34 +13,48 @@
 
 ## 📌 Quick Demo
 
-```typescript
-// Your API is ready with authentication, validation, and error handling out of the box!
-import app from 'express-ts-api-starter';
-
-// Start building your endpoints immediately
-app.get('/api/v1/users', (req, res) => {
-  // Request ID automatically attached: req.headers['x-request-id']
-  // Error handling: Global middleware catches all errors
-  // Validation: Built-in express-validator ready
-  res.json({ message: 'API is running!' });
-});
+**Create a new project in seconds:**
+
+```bash
+npx express-ts-api-starter my-api
+cd my-api
+npm install
+npm run dev
 ```
 
+Your API is ready with authentication, validation, and error handling out of the box!
+
 ---
 
 ## 🚀 Quick Start
 
-### Install
+### Option 1: Using CLI (Recommended)
+
+Create a new project with a single command:
+
+```bash
+npx express-ts-api-starter my-api
+```
+
+This will:
+- ✅ Create a new project directory
+- ✅ Copy all template files and folder structure
+- ✅ Set up configuration files
+- ✅ Create `.env` file from `.env.example`
+
+Then:
 
 ```bash
-npm install express-ts-api-starter
+cd my-api
+npm install
+npm run dev
 ```
 
-### Launch Your Project
+### Option 2: Manual Installation
 
 ```bash
 # Clone the repository
-git clone https://github.com/nikhilpktcr/express-ts-starter.git my-api
+git clone https://github.com/nikhilpktcr/express-ts-api-starter.git my-api
 cd my-api
 
 # Install dependencies
@@ -92,6 +106,20 @@ npm run dev
 | **TypeScript** | Sometimes | ✅ **100% TypeScript with strict mode** |
 | **Documentation** | Minimal | ✅ **Well-documented with examples** |
 | **Testing** | Sometimes | ✅ **Jest with test examples included** |
+| **CLI Tool** | Sometimes | ✅ **Built-in CLI generator** |
+
+### vs. NestJS
+
+| Feature | NestJS | express-ts-api-starter |
+|---------|--------|------------------------|
+| **Setup Time** | 10-15 minutes | ⚡ **2 minutes** |
+| **Learning Curve** | High (new framework) | ✅ **Low (Express knowledge)** |
+| **Bundle Size** | ~200KB+ | ✅ **~50KB (lightweight)** |
+| **Flexibility** | Framework-driven | ✅ **High (minimal abstraction)** |
+| **Request Tracking** | Manual setup | ✅ **Built-in request IDs** |
+| **Security (Out of Box)** | Manual config | ✅ **Pre-configured** |
+
+📖 **[See detailed NestJS comparison →](COMPARISON-NESTJS.md)**
 
 ---
 
@@ -152,6 +180,7 @@ npm run dev
 
 ### Developer Experience
 
+- ✅ **CLI Tool** - Generate projects with one command
 - ✅ **Hot reload** - See changes instantly
 - ✅ **TypeScript declarations** - Full IntelliSense support
 - ✅ **Pre-configured scripts** - dev, build, test, lint
@@ -349,7 +378,7 @@ Free for personal and commercial use! ✨
 ## 💬 Support
 
 - **Email**: nikhil.pk.connect@gmail.com
-- **GitHub Issues**: [Report bugs](https://github.com/nikhilpktcr/express-ts-starter/issues)
+- **GitHub Issues**: [Report bugs](https://github.com/nikhilpktcr/express-ts-api-starter/issues)
 - **GitHub**: [@nikhilpktcr](https://github.com/nikhilpktcr)
 
 ---
@@ -381,7 +410,7 @@ If this boilerplate helps your project:
 **Ready to build?** Start your next API project in minutes:
 
 ```bash
-npm install express-ts-api-starter
+npx express-ts-api-starter my-api
 ```
 
 **Happy coding!** 🎉

package/bin/cli.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+// Get __dirname equivalent in ES modules
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Colors for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  red: '\x1b[31m',
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function getProjectName() {
+  const args = process.argv.slice(2);
+  if (args.length > 0) {
+    return args[0];
+  }
+  return 'my-express-api';
+}
+
+function isValidProjectName(name) {
+  return /^[a-z0-9-]+$/.test(name) && name.length > 0;
+}
+
+function copyDirectory(src, dest) {
+  if (!fs.existsSync(src)) {
+    return;
+  }
+
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      // Skip node_modules and dist directories
+      if (entry.name === 'node_modules' || entry.name === 'dist') {
+        continue;
+      }
+      copyDirectory(srcPath, destPath);
+    } else {
+      // Skip certain files
+      if (
+        entry.name === 'package-lock.json' ||
+        entry.name === '.env' ||
+        entry.name === 'eslint-report.json'
+      ) {
+        continue;
+      }
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function updatePackageJson(projectPath, projectName) {
+  const packageJsonPath = path.join(projectPath, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    return;
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  
+  // Update package name
+  packageJson.name = projectName;
+  
+  // Remove bin field if it exists (not needed in generated project)
+  delete packageJson.bin;
+  
+  // Remove prepublishOnly script
+  delete packageJson.scripts.prepublishOnly;
+  
+  fs.writeFileSync(
+    packageJsonPath,
+    JSON.stringify(packageJson, null, 2) + '\n',
+    'utf8'
+  );
+}
+
+function createEnvFile(projectPath) {
+  const envExamplePath = path.join(projectPath, '.env.example');
+  const envPath = path.join(projectPath, '.env');
+
+  if (fs.existsSync(envExamplePath) && !fs.existsSync(envPath)) {
+    fs.copyFileSync(envExamplePath, envPath);
+    log('✓ Created .env file from .env.example', 'green');
+  }
+}
+
+function main() {
+  log('\n🚀 Express TypeScript API Starter', 'bright');
+  log('=====================================\n', 'cyan');
+
+  const projectName = getProjectName();
+
+  if (!isValidProjectName(projectName)) {
+    log('❌ Error: Invalid project name!', 'red');
+    log('   Project name should only contain lowercase letters, numbers, and hyphens.\n', 'yellow');
+    process.exit(1);
+  }
+
+  const currentDir = process.cwd();
+  const projectPath = path.join(currentDir, projectName);
+
+  // Check if directory already exists
+  if (fs.existsSync(projectPath)) {
+    log(`❌ Error: Directory "${projectName}" already exists!`, 'red');
+    log('   Please choose a different name or remove the existing directory.\n', 'yellow');
+    process.exit(1);
+  }
+
+  log(`📦 Creating project: ${projectName}...\n`, 'blue');
+
+  try {
+    // Get the template directory (where this package is installed)
+    const templateDir = path.resolve(__dirname, '..');
+
+    // Create project directory
+    fs.mkdirSync(projectPath, { recursive: true });
+    log(`✓ Created directory: ${projectName}`, 'green');
+
+    // Copy template files
+    log('📋 Copying template files...', 'blue');
+    
+    // Copy src directory
+    const srcDir = path.join(templateDir, 'src');
+    if (fs.existsSync(srcDir)) {
+      copyDirectory(srcDir, path.join(projectPath, 'src'));
+      log('  ✓ Copied src/ directory', 'green');
+    }
+
+    // Copy scripts directory
+    const scriptsDir = path.join(templateDir, 'scripts');
+    if (fs.existsSync(scriptsDir)) {
+      copyDirectory(scriptsDir, path.join(projectPath, 'scripts'));
+      log('  ✓ Copied scripts/ directory', 'green');
+    }
+
+    // Copy configuration files
+    const configFiles = [
+      'tsconfig.json',
+      'eslint.config.js',
+      'jest.config.ts',
+      '.env.example',
+      '.gitignore',
+      'README.md',
+      'LICENSE',
+    ];
+
+    for (const file of configFiles) {
+      const srcFile = path.join(templateDir, file);
+      if (fs.existsSync(srcFile)) {
+        fs.copyFileSync(srcFile, path.join(projectPath, file));
+        log(`  ✓ Copied ${file}`, 'green');
+      }
+    }
+
+    // Update package.json
+    updatePackageJson(projectPath, projectName);
+    log('  ✓ Updated package.json', 'green');
+
+    // Create .env file
+    createEnvFile(projectPath);
+
+    log('\n✅ Project created successfully!\n', 'green');
+
+    // Next steps
+    log('📝 Next steps:', 'bright');
+    log(`   cd ${projectName}`, 'cyan');
+    log('   npm install', 'cyan');
+    log('   npm run dev', 'cyan');
+    log('\n🎉 Happy coding!\n', 'green');
+
+  } catch (error) {
+    log(`\n❌ Error: ${error.message}`, 'red');
+    // Clean up on error
+    if (fs.existsSync(projectPath)) {
+      fs.rmSync(projectPath, { recursive: true, force: true });
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/eslint.config.js

@@ -0,0 +1,22 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config({
+  ignores: ['dist/**'],
+},
+{
+  extends: [
+    js.configs.recommended,
+    ...tseslint.configs.recommended,
+  ],
+  files: ['**/*.{ts,js,cjs,mjs}'],
+  languageOptions: {
+    ecmaVersion: 2020,
+    globals: globals.browser,
+  },
+  rules: {
+    '@typescript-eslint/no-unused-vars': 'off',
+    '@typescript-eslint/no-explicit-any': "off"
+  },
+});

package/jest.config.ts

@@ -0,0 +1,9 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testPathIgnorePatterns: ['/dist/'],
+};
+
+export default config;

package/package.json

@@ -1,13 +1,24 @@
 {
   "name": "express-ts-api-starter",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Production-ready Express.js + TypeScript boilerplate with MVC architecture, JWT auth, MongoDB, security, validation, and testing—build scalable REST APIs fast",
   "main": "dist/server.js",
   "types": "dist/server.d.ts",
+  "bin": {
+    "express-ts-api-starter": "./bin/cli.mjs"
+  },
   "files": [
+    "src",
     "dist",
     "!dist/**/*.test.js",
     "!dist/**/*.spec.js",
+    "scripts",
+    "bin",
+    "tsconfig.json",
+    "eslint.config.js",
+    "jest.config.ts",
+    ".env.example",
+    ".gitignore",
     "README.md",
     "LICENSE"
   ],

package/scripts/eslint-report.js

@@ -0,0 +1,65 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+// Emulate __dirname in ES modules
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const reportPath = path.resolve(process.cwd(), 'eslint-report.json');
+
+// Step 1: Run ESLint and generate report
+try {
+  console.log(chalk.blue('🔍 Running ESLint...'));
+  execSync('npx eslint . --ext .ts,.js --format json -o eslint-report.json', { stdio: 'inherit' });
+} catch (err) {
+  console.error(chalk.red('❌ ESLint execution failed.'));
+  process.exit(1);
+}
+
+// Step 2: Read and display the report
+if (!fs.existsSync(reportPath)) {
+  console.error(chalk.red('❌ ESLint report not found.'));
+  process.exit(1);
+}
+
+const report = JSON.parse(fs.readFileSync(reportPath, 'utf-8'));
+
+let totalErrors = 0;
+let totalWarnings = 0;
+let passedFiles = 0;
+
+console.log(chalk.bold('\nTest Suites: ESLint Report\n'));
+
+report.forEach((file) => {
+  const fileName = path.relative(process.cwd(), file.filePath);
+  const errors = file.errorCount;
+  const warnings = file.warningCount;
+
+  totalErrors += errors;
+  totalWarnings += warnings;
+
+  if (errors === 0 && warnings === 0) {
+    passedFiles++;
+    console.log(chalk.green(`✓ ${fileName}`));
+  } else {
+    console.log(chalk.red(`✖ ${fileName}`));
+    file.messages.forEach((msg) => {
+      const severity = msg.severity === 2 ? chalk.red('error') : chalk.yellow('warning');
+      console.log(`  ${chalk.gray(msg.ruleId || 'unknown')} - ${severity}: ${msg.message}`);
+    });
+  }
+});
+
+console.log('\n' + chalk.bold('Summary:'));
+console.log(chalk.green(`  Passed files: ${passedFiles}/${report.length}`));
+console.log(chalk.red(`  Total Errors: ${totalErrors}`));
+console.log(chalk.yellow(`  Total Warnings: ${totalWarnings}\n`));
+
+if (totalErrors === 0) {
+  console.log(chalk.green.bold('✔ All files passed linting!\n'));
+} else {
+  console.log(chalk.red.bold('✖ Linting issues detected.\n'));
+}

package/src/app.ts

@@ -0,0 +1,56 @@
+import express, { Application, Request } from "express";
+import cors from "cors";
+import morgan from "morgan";
+import { env } from "./config/envConfig";
+import routes from "./routes";
+import helmet from "helmet";
+// import { limiterConfig } from "./config/rateLimitConfig";
+import connectDB from "./config/dbConfig";
+import {
+  globalErrorHandler,
+  notFoundHandler,
+} from "./middleware/errorMiddleware";
+import { sendErrorResponse } from "./utils/responseUtil";
+import { StatusCodes } from "http-status-codes";
+import { requestIdMiddleware } from "./middleware/requestIdMiddleware";
+
+const app: Application = express();
+
+// ===== Middleware =====
+// app.use(limiterConfig);
+app.use(helmet());
+app.use(cors());
+app.use(express.json());
+app.use(express.urlencoded({ extended: true }));
+connectDB();
+
+// ===== Request ID Middleware =====
+app.use(requestIdMiddleware);
+
+// ===== Morgan Logging with Request ID =====
+
+morgan.token("id", (req: Request) => {
+  const requestId = req.headers["x-request-id"];
+  return typeof requestId === "string"
+    ? requestId
+    : Array.isArray(requestId)
+      ? requestId[0]
+      : "unknown";
+});
+
+app.use(
+  morgan(
+    "🧾 requestId=:id 🚀 :method :url 📦 status=:status ⏱️ :response-time ms"
+  )
+);
+
+// ===== API Routes =====
+app.use(env.BASIC_API_URL, routes);
+
+// ===== Un handled Routes =====
+app.use(notFoundHandler);
+
+// ===== Global Error Handler =====
+app.use(globalErrorHandler);
+
+export default app;

package/src/config/dbConfig.ts

@@ -0,0 +1,17 @@
+import mongoose from "mongoose";
+import { env } from "./envConfig";
+import messages from "../messages";
+
+const connectDB = async (): Promise<void> => {
+  try {
+    await mongoose.connect(env.DB_CONNECTION, {
+      dbName: env.DB_NAME,
+    });
+    console.log(`${env.DB_NAME} ${messages.DB_CONNECT_SUCESS}`);
+  } catch (error) {
+    console.error(`${env.DB_NAME} ${messages.DB_CONNECT_FAILED}`, error);
+    process.exit(1);
+  }
+};
+
+export default connectDB;

package/src/config/envConfig.ts

@@ -0,0 +1,18 @@
+import dotenv from "dotenv";
+dotenv.config();
+
+function getEnvVar(key: string, fallback?: string): string {
+  const value = process.env[key];
+  if (!value && fallback === undefined) {
+    throw new Error(`Missing required environment variable: ${key}`);
+  }
+  return value || fallback!;
+}
+
+export const env = {
+  PORT: getEnvVar("PORT", "5000"),
+  BASIC_API_URL: getEnvVar("BASIC_API_URL", "/api/v1"),
+  DB_NAME: getEnvVar("DB_NAME", "testDB"),
+  JWT_SECRET: getEnvVar("JWT_SECRET", "supersecret"),
+  DB_CONNECTION: getEnvVar("DB_CONNECTION", "mongodb://localhost:27017/"),
+};

package/src/config/rateLimitConfig.ts

@@ -0,0 +1,7 @@
+import { rateLimit } from "express-rate-limit";
+
+export const limiterConfig = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  limit: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes).
+  legacyHeaders: false, // Disable the `X-RateLimit-*` headers.
+});