create-express-modular 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 levi9111
+
+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,88 @@
+```markdown
+# 🚀 Create Express Modular
+
+> A powerful interactive CLI to scaffold a scalable, database‑agnostic Express + TypeScript server — inspired by NestJS structure, but lightweight and flexible.
+
+[![npm version](https://img.shields.io/npm/v/create-express-modular.svg)](https://www.npmjs.com/package/create-express-modular)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Stop copying boilerplate manually. Define your modules once, and let `create-express-modular` generate a production‑ready, strictly typed Express application in seconds.
+
+## ✨ Why use this?
+
+- **Interactive Scaffolding** – The CLI asks for your module names (e.g. `User, Product, Order`) and builds the entire folder structure and initial files automatically.
+- **Database Agnostic** – No ORM is forced. Works equally well with MongoDB (Mongoose), PostgreSQL (Prisma/TypeORM), MySQL, or plain SQL.
+- **NestJS‑inspired Modular Design** – Each module contains its own controller, service, routes, model, interface, and validation — separation of concerns out of the box.
+- **Auto‑wired Routing** – Your custom modules are automatically imported and registered in `src/app/routes/index.ts`. No manual wiring required.
+- **Production‑ready DX** – TypeScript strict mode, ESLint (v8), Prettier, and `ts-node-dev` for instant hot‑reload during development.
+
+## 📦 Quick Start
+
+You don't need to install anything globally. Use `npx` to run the latest version:
+
+```bash
+npx create-express-modular
+```
+
+The CLI will guide you through two simple steps:
+1. **Project name** – Choose a name for your new backend.
+2. **Module names** – List the feature modules you need (e.g. `Auth, Receipt, Property`).
+
+Once finished, your project is ready with all dependencies installed and Git initialised.
+
+## 📂 Generated Project Structure
+
+After generating a project with a `User` module, your `src` directory will look like this:
+
+```
+src/
+├── app/
+│   ├── builder/
+│   ├── config/
+│   ├── constants/
+│   ├── errors/
+│   ├── interface/
+│   ├── middlewares/
+│   ├── modules/
+│   │   └── User/                    # ✨ Generated module
+│   │       ├── user.controller.ts
+│   │       ├── user.interface.ts
+│   │       ├── user.model.ts
+│   │       ├── user.route.ts
+│   │       ├── user.service.ts
+│   │       ├── user.utils.ts
+│   │       └── user.validation.ts
+│   ├── routes/
+│   │   └── index.ts                 # ✨ Auto‑wired with your modules
+│   └── utils/
+├── app.ts
+└── server.ts
+```
+
+> **Tip:** The architecture is domain‑driven and easily extensible — perfect for growing APIs.
+
+## 📜 Built‑in Scripts
+
+Inside your generated project, you can run:
+
+| Command               | Description                                               |
+|-----------------------|-----------------------------------------------------------|
+| `npm run start:dev`   | Starts the dev server with hot‑reload (`ts-node-dev`)     |
+| `npm run build`       | Compiles TypeScript to JavaScript (`dist/`)               |
+| `npm start`           | Runs the compiled app in production                       |
+| `npm run lint`        | Lints the codebase with ESLint                            |
+| `npm run lint:fix`    | Automatically fixes linting issues                        |
+| `npm run prettier`    | Formats all files using Prettier                          |
+
+## 🧩 Customisation & Extensibility
+
+Because the tool generates standard Express + TypeScript code, you can easily add any middleware, ORM, or utility library. The structure is designed to stay out of your way while keeping everything organised.
+
+## 🤝 Contributing
+
+We welcome contributions! Feel free to open an issue or submit a pull request on [GitHub](https://github.com/Levi9111/npm-create-express-modular).
+
+## 📄 License
+
+This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).
+

package/bin/cli.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const {
+    execSync
+} = require('child_process');
+const readline = require('readline');
+
+const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+});
+
+const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
+
+async function runCLI() {
+    console.log('\n🚀 Welcome to Create Express Modular!\n');
+
+    // 1. Get Project Name
+    let projectName = process.argv[2];
+    if (!projectName) {
+        projectName = await askQuestion('📦 What is your project named? (e.g., my-api): ');
+    }
+
+    if (!projectName) {
+        console.error('❌ Project name is required.');
+        process.exit(1);
+    }
+
+    // 2. Ask for Modules
+    const modulesInput = await askQuestion(
+        '🛠️  Which modules should we generate? (comma-separated, e.g., User,Product,Order): '
+    );
+
+    rl.close();
+
+    const currentPath = process.cwd();
+    const projectPath = path.join(currentPath, projectName);
+    const templatePath = path.join(__dirname, '../template');
+
+    // 3. Create Project Directory
+    try {
+        fs.mkdirSync(projectPath);
+    } catch (err) {
+        if (err.code === 'EEXIST') {
+            console.error(`❌ Directory '${projectName}' already exists.`);
+        } else {
+            console.error(err);
+        }
+        process.exit(1);
+    }
+
+    // Helper to copy the base template
+    function copyFolderSync(from, to) {
+        fs.mkdirSync(to, {
+            recursive: true
+        });
+        fs.readdirSync(from).forEach((element) => {
+            const fromPath = path.join(from, element);
+            const toPath = path.join(to, element);
+            if (fs.lstatSync(fromPath).isFile()) {
+                fs.copyFileSync(fromPath, toPath);
+            } else {
+                copyFolderSync(fromPath, toPath);
+            }
+        });
+    }
+
+    console.log(`\n📂 Scaffolding base architecture...`);
+    copyFolderSync(templatePath, projectPath);
+
+    // 4. Rename gitignore to .gitignore
+    const gitignorePath = path.join(projectPath, 'gitignore');
+    if (fs.existsSync(gitignorePath)) {
+        fs.renameSync(gitignorePath, path.join(projectPath, '.gitignore'));
+    }
+
+    // 5. Update the new package.json with the user's project name
+    const packageJsonPath = path.join(projectPath, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+        packageJson.name = projectName.toLowerCase().replace(/\s+/g, '-');
+        fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
+    }
+
+    // 6. Dynamically Generate the Modules based on user input
+    const modulesToCreate = modulesInput
+        .split(',')
+        .map((m) => m.trim())
+        .filter((m) => m.length > 0);
+
+    if (modulesToCreate.length > 0) {
+        console.log(`\n🧩 Generating custom modules...`);
+
+        const modulesBaseDir = path.join(projectPath, 'src/app/modules');
+        if (!fs.existsSync(modulesBaseDir)) fs.mkdirSync(modulesBaseDir, {
+            recursive: true
+        });
+
+        let routeImports = '';
+        let routeArray = 'const moduleRoutes = [\n';
+
+        modulesToCreate.forEach((mod) => {
+            const moduleName = mod.charAt(0).toUpperCase() + mod.slice(1);
+            const fileName = mod.toLowerCase();
+            const modulePath = path.join(modulesBaseDir, moduleName);
+
+            fs.mkdirSync(modulePath, {
+                recursive: true
+            });
+
+            // Create the 7 standard files for each module
+            const fileTypes = ['controller', 'interface', 'model', 'route', 'service', 'utils', 'validation'];
+            fileTypes.forEach((type) => {
+                fs.writeFileSync(
+                    path.join(modulePath, `${fileName}.${type}.ts`),
+                    `// TODO: Implement ${moduleName} ${type}\n`
+                );
+            });
+
+            console.log(`  - Created ${moduleName} module`);
+
+            // Prepare data for the routes/index.ts file
+            routeImports += `import { ${moduleName}Routes } from '../modules/${moduleName}/${fileName}.route';\n`;
+            routeArray += `  { path: '/${fileName}s', route: ${moduleName}Routes },\n`;
+        });
+
+        routeArray += '];\n';
+
+        // 7. Generate src/app/routes/index.ts to wire up the router automatically
+        const routesDir = path.join(projectPath, 'src/app/routes');
+        if (!fs.existsSync(routesDir)) fs.mkdirSync(routesDir, {
+            recursive: true
+        });
+
+        const routeFileContent = `import { Router } from 'express';\n\n${routeImports}\nconst router = Router();\n\n${routeArray}\nmoduleRoutes.forEach((route) => router.use(route.path, route.route));\n\nexport default router;\n`;
+        fs.writeFileSync(path.join(routesDir, 'index.ts'), routeFileContent);
+    }
+
+    // 8. Install Dependencies
+    console.log('\n📦 Installing dependencies (this takes a minute)...');
+    try {
+        execSync('npm install', {
+            cwd: projectPath,
+            stdio: 'inherit'
+        });
+    } catch (error) {
+        console.error('\n❌ Failed to install dependencies.');
+    }
+
+    console.log(`\n✅ Success! Your Express architecture is ready.`);
+    console.log(`\nNext steps:`);
+    console.log(`  cd ${projectName}`);
+    console.log(`  npm run start:dev\n`);
+}
+
+runCLI();

package/package.json

@@ -0,0 +1,38 @@
+{
+    "name": "create-express-modular",
+    "version": "1.0.0",
+    "description": "Scaffold a modular Express TS server",
+    "bin": {
+        "create-express-modular": "./bin/cli.js"
+    },
+    "files": [
+        "bin",
+        "template",
+        "README.md",
+        "package.json",
+        "LICENSE"
+    ],
+    "scripts": {
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "keywords": [
+        "express",
+        "typescript",
+        "modular",
+        "scaffold",
+        "cli"
+    ],
+    "author": "levi9111",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Levi9111/npm-create-express-modular.git"
+    },
+    "bugs": {
+        "url": "https://github.com/Levi9111/npm-create-express-modular/issues"
+    },
+    "homepage": "https://github.com/Levi9111/npm-create-express-modular#readme",
+    "dependencies": {
+        "http-status-codes": "^2.3.0"
+    }
+}

package/template/.eslintignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+.env

package/template/.eslintrc.json

@@ -0,0 +1,27 @@
+{
+  "env": {
+    "browser": true,
+    "es2021": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "prettier"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint"],
+  "rules": {
+    "no-unused-vars": "error",
+    "no-unused-expressions": "error",
+    "prefer-const": "error",
+    "no-console": "warn",
+    "no-undef": "error"
+  },
+  "globals": {
+    "process": "readonly"
+  }
+}

package/template/.prettierrc.json

@@ -0,0 +1,12 @@
+{
+    "semi": true,
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "all",
+    "printWidth": 80,
+    "jsxSingleQuote": true,
+    "jsxBracketSameLine": false,
+    "arrowParens": "always",
+    "bracketSpacing": true,
+    "endOfLine": "auto"
+}

package/template/gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+.env
+.env.local
+*.log

package/template/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "template",
+    "version": "1.0.0",
+    "main": "src/server.ts",
+    "scripts": {
+        "build": "npm install && tsc",
+        "start": "node dist/server.js",
+        "start:dev": "ts-node-dev --respawn --transpile-only src/server.ts",
+        "lint": "eslint src --ignore-path .eslintignore --ext .ts",
+        "lint:fix": "eslint src --fix --ignore-path .eslintignore --ext .ts",
+        "prettier": "prettier --ignore-path .gitignore --write \"./src/**/*.{js,ts,json}\"",
+        "prettier:fix": "prettier --write src"
+    },
+    "dependencies": {
+        "cors": "^2.8.5",
+        "dotenv": "^16.3.1",
+        "express": "^4.18.2"
+    },
+    "devDependencies": {
+        "@types/cors": "^2.8.13",
+        "@types/express": "^4.17.17",
+        "@types/node": "^20.4.5",
+        "@typescript-eslint/eslint-plugin": "^6.2.0",
+        "@typescript-eslint/parser": "^6.2.0",
+        "eslint": "^8.45.0",
+        "eslint-config-prettier": "^8.8.0",
+        "prettier": "^3.0.0",
+        "ts-node-dev": "^2.0.0",
+        "typescript": "^5.1.6"
+    }
+}

package/template/src/app/errors/AppError.ts

@@ -0,0 +1,12 @@
+class AppError extends Error {
+  public statusCode: number;
+
+  constructor(statusCode: number, message: string, stack: string = '') {
+    super(message);
+    this.statusCode = statusCode;
+    if (stack) this.stack = stack;
+    else Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export default AppError;

package/template/src/app/middlewares/globalErrorhandler.ts

@@ -0,0 +1,26 @@
+import { ErrorRequestHandler } from 'express';
+import AppError from '../errors/AppError';
+
+const globalErrorHandler: ErrorRequestHandler = (err, req, res, next) => {
+  let statusCode = 500;
+  let message = 'Something went wrong!';
+  let errorMessages: { path: string | number; message: string }[] = [];
+
+  if (err instanceof AppError) {
+    statusCode = err.statusCode;
+    message = err.message;
+    errorMessages = err.message ? [{ path: '', message: err.message }] : [];
+  } else if (err instanceof Error) {
+    message = err.message;
+    errorMessages = err.message ? [{ path: '', message: err.message }] : [];
+  }
+
+  res.status(statusCode).json({
+    success: false,
+    message,
+    errorMessages,
+    stack: process.env.NODE_ENV !== 'production' ? err.stack : undefined,
+  });
+};
+
+export default globalErrorHandler;

package/template/src/app/middlewares/notFound.ts

@@ -0,0 +1,15 @@
+/* eslint-disable no-unused-vars */
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+import { NextFunction, Request, Response } from 'express';
+import httpStatus from 'http-status-codes';
+
+const notFound = (req: Request, res: Response, next: NextFunction) => {
+  return res.status(httpStatus.NOT_FOUND).json({
+    success: false,
+    message: 'API Not Found !!',
+    error: '',
+  });
+};
+
+export default notFound;

package/template/src/app/routes/index.ts

@@ -0,0 +1,5 @@
+import { Router } from 'express';
+
+const router = Router();
+
+export default router;

package/template/src/app.ts

@@ -0,0 +1,23 @@
+import cors from 'cors';
+import express, { Application, Request, Response } from 'express';
+import router from './app/routes/index';
+import notFound from './app/middlewares/notFound';
+import globalErrorHandler from './app/middlewares/globalErrorhandler';
+
+const app: Application = express();
+
+//parsers
+app.use(express.json());
+app.use(cors());
+
+// application routes
+app.use('/api/v1', router);
+
+app.get('/', (_req: Request, res: Response) => {
+  res.send('Welcome to Express Modular Server!');
+});
+
+app.use(globalErrorHandler);
+app.use(notFound);
+
+export default app;

package/template/src/server.ts

@@ -0,0 +1,15 @@
+import app from './app';
+
+const port = 5000;
+
+async function bootstrap() {
+  try {
+    app.listen(port, () => {
+      console.log(`Server is running on port ${port}`);
+    });
+  } catch (err) {
+    console.log(err);
+  }
+}
+
+bootstrap();

package/template/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules"]
+}