nodejs-quickstart-structure 1.11.1 → 1.13.0

package/CHANGELOG.md

@@ -5,15 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.13.0] - 2026-03-05
+### Added
+- **Enhanced Health Check System:**
+  - Standardized health logic for both MVC and Clean Architecture.
+  - Deep verification: Automatically pings the selected database (MySQL, PostgreSQL, MongoDB) during health checks and returns a `DOWN` status with 500 code if the connection is lost.
+  - Structured response including `uptime`, `memoryUsage`, `database` connectivity status, and `timestamp`.
+- **Improved Graceful Shutdown:**
+  - Standardized signal handling (`SIGINT`, `SIGTERM`) across all architecture types to ensure clean disposal of database and caching resources.
+  - Integrated proper shutdown sequences for Redis, MySQL, PostgreSQL, and MongoDB.
+
+## [1.12.0] - 2026-03-04
+### Added
+- **Zod Environment Validation:** Replaced manual `dotenv` process calls in server entry points with a centralized schema parser.
+  - Automatically generates `src/config/env.ts` (or `.js`) evaluating `NODE_ENV`, `PORT`, and strictly mapping database, cache, and Kafka connection definitions gracefully crashing the app at startup if missing.
+- **PM2 Deployment Configuration:** Natively supports PM2 ecosystem clustering for VPS and EC2 configurations out-of-the-box.
+  - Generates `ecosystem.config.js` intelligently mapping dynamic environments for Redis, Databases, and Kafka without user prompts.
+  - Modifies `package.json` with an out-of-the-box `npm run deploy` script bound to `pm2 start ecosystem.config.js --env production`.
+  - Upgraded generated README deployment guides for transparent CLI instruction workflows outlining the contrast between running Docker vs PM2.
+
 ## [1.11.1] - 2026-03-03
 ### Fixed
-- Fixed relative import paths in Clean Architecture JS `error.middleware.js` — changed to correct 3-level relative paths (`../../../`).
+- Fixed relative import paths in Clean Architecture JS `errorMiddleware.js` — changed to correct 3-level relative paths (`../../../`).
 
 ## [1.11.0] - 2026-03-02
 ### Added
 - **Centralized Error Handling Mechanism:** All generated projects now include a standardized, predictable error response structure for both REST APIs and GraphQL communication types.
   - New `src/errors/` directory with custom error classes: `ApiError`, `NotFoundError`, `BadRequestError`.
-  - New `error.middleware.{ts|js}` global error handler placed at the end of the Express middleware chain in `src/utils/` (MVC) and `src/utils/` + `src/infrastructure/webserver/middlewares/` (Clean Architecture).
+  - New `error.middleware.{ts|js}` global error handler placed at the end of the Express middleware chain in `src/utils/` (MVC) and `src/utils/` + `src/infrastructure/webserver/middleware/` (Clean Architecture).
   - Integrates `winston` logger to automatically log 500-level errors to persistent log files.
   - All controllers updated to pass errors via `next(error)` instead of manually sending responses.
   - **GraphQL:** Apollo Server `formatError` hook configured with `unwrapResolverError` to intercept resolver errors and map `ApiError` instances to structured GraphQL extension codes.
@@ -23,7 +42,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - Fixed `swagger.js` / `swagger.yml` being incorrectly generated for non-REST API configurations (GraphQL, Kafka). Converted static `swagger.js` to `swagger.js.ejs` in MVC JS and Clean Architecture JS templates so `renderSwaggerConfig` can conditionally control its generation.
 - Fixed `userRoutes.ts` in Clean Architecture TypeScript template not passing `NextFunction` to controller methods, causing `TypeScript TS2554: Expected 3 arguments` compile errors during Docker builds.
-- Fixed incorrect relative import paths (`../../../../`) in Clean Architecture JS `error.middleware.js` — changed to correct 3-level relative paths (`../../../`).
+- Fixed incorrect relative import paths (`../../../../`) in Clean Architecture JS `errorMiddleware.js` — changed to correct 3-level relative paths (`../../../`).
 - Fixed `HTTP_STATUS` being imported without destructuring from `httpCodes.js` (which uses a plain `module.exports = HTTP_STATUS` default export), causing `Cannot read properties of undefined` runtime errors.
 - Fixed `renderErrorMiddleware` in `app-setup.js` deleting from the **template source directory** instead of the generated project's target directory. This caused error middleware templates to disappear from disk after the first test run, breaking all subsequent generations.
 

package/README.md

@@ -34,7 +34,9 @@ We don't just generate boilerplate; we generate **production-ready** foundations
 -   **🧪 Testing Strategy**: Integrated `Jest` and `Supertest` setup for Unit and Integration testing.
 -   **🔄 CI/CD Integration**: Pre-configured workflows for **GitHub Actions**, **Jenkins**, and **GitLab CI**.
 -   **⚓ Git Hooks**: `Husky` and `Lint-Staged` to ensure no bad code is ever committed.
+-   **🤝 Reliability**: Advanced Health Checks (`/health`) with deep database pings and Graceful Shutdown workflows for zero-downtime rollouts.
 -   **🐳 DevOps**: Highly optimized **Multi-Stage Dockerfile** for small, secure production images.
+-   **🚀 Deployment**: Ship confidently with an integrated **PM2 Ecosystem Configuration** for zero-downtime reloads and robust process management.
 
 ## 🧩 240+ Project Combinations
 
@@ -92,7 +94,6 @@ The generated project will include:
 
 -   `src/`: Source code (controllers, routes, services/use-cases).
 -   `src/errors/`: Custom error classes — `ApiError`, `NotFoundError`, `BadRequestError`.
--   `src/utils/error.middleware.{ts|js}`: Global Express error handler (logs 500s, returns `{ statusCode, message }`).
 -   `flyway/sql/`: SQL migration scripts (if SQL database selected).
 -   `docker-compose.yml`: Services configuration for DB, Flyway, and Kafka.
 -   `package.json`: Dependencies and scripts (`start`, `dev`, `build`).

package/bin/index.js

@@ -52,7 +52,7 @@ program
 
             console.log(chalk.green('\n✔ Project generated successfully!'));
             
-            let manualStartInstructions = `\nStart the app manually:\n  cd ${answers.projectName}\n  npm install`;
+            let manualStartInstructions = `\n${chalk.yellow('Development:')}\n  cd ${answers.projectName}\n  npm install`;
             
             const needsInfrastructure = answers.database !== 'None' || answers.caching === 'Redis' || answers.communication === 'Kafka';
             
@@ -67,7 +67,7 @@ program
                 manualStartInstructions += `\n  npm run dev`;
             }
             
-            console.log(chalk.cyan(`\nNext steps:\n  cd ${answers.projectName}\n  npm install\n  docker-compose up\n-----------------------${manualStartInstructions}`));
+            console.log(chalk.cyan(`\nNext steps:\n  cd ${answers.projectName}\n  npm install\n  docker-compose up\n-----------------------${manualStartInstructions}\n\n${chalk.yellow('Production (PM2):')}\n  npm run build\n  npm run deploy\n  npx pm2 logs`));
 
         } catch (error) {
             console.error(chalk.red('Error generating project:'), error);

package/docs/generatorFlow.md

@@ -50,10 +50,10 @@ The `generateProject` function in `lib/generator.js` executes the following step
     *   Processes the entry point file to wire up the selected DB, Architecture, and Communication type.
     *   **GraphQL**: Wires up Apollo Server middleware with `formatError` hook for centralized error handling.
     *   **REST APIs / Kafka**: Registers `app.use(errorMiddleware)` at the end of the Express chain.
-7.  **Render Error Middleware** (`renderErrorMiddleware`):
-    *   Processes `error.middleware.{ts|js}.ejs` template from the target directory's `src/utils/` path.
-    *   Renders to `src/utils/error.middleware.{ts|js}` in the generated project.
-    *   **Clean Architecture**: Also handles `src/infrastructure/webserver/middlewares/error.middleware.{js}` path.
+7.  **Error Middleware setup** (`renderErrorMiddleware`):
+    *   Processes `errorMiddleware.{ts|js}.ejs` template from the target directory's `src/utils/` path.
+    *   Renders to `src/utils/errorMiddleware.{ts|js}` in the generated project.
+    *   **Clean Architecture**: Also handles `src/infrastructure/webserver/middleware/errorMiddleware.{js}` path.
 8.  **Dynamic Component Generation**:
     *   **MVC**: Generates `userController` (imports specific DB service, uses `next(error)`).
     *   **Clean Architecture**: Generates `UserRepository` (infrastructure layer implementation).
@@ -141,7 +141,7 @@ project-name/
 │   ├── models/         # Database models
 │   ├── routes/         # Express routes
 │   ├── utils/
-│   │   ├── error.middleware.{ts|js}  # Global error handler
+│   │   ├── errorMiddleware.{ts|js}  # Global error handler
 │   │   ├── logger.{ts|js}
 │   │   └── httpCodes.{ts|js}
 │   └── index.js|ts     # Entry point (registers errorMiddleware last)
@@ -165,7 +165,7 @@ project-name/
 │   │   └── resolvers/  # user.resolvers (calls controllers, throws errors)
 │   ├── models/
 │   ├── utils/
-│   │   ├── error.middleware.{ts|js}  # Express-level fallback error handler
+│   │   ├── errorMiddleware.{ts|js}  # Express-level fallback error handler
 │   │   └── logger.{ts|js}
 │   └── index.js|ts     # Apollo Server + formatError hook
 └── ...
@@ -205,11 +205,11 @@ project-name/
 │   │   ├── database/           # DB connection & models
 │   │   ├── repositories/       # Data access implementation
 │   │   └── webserver/
-│   │       ├── middlewares/
-│   │       │   └── error.middleware.js  # JS only — Express error handler
+│   │       ├── middleware/
+│   │       │   └── errorMiddleware.js  # JS only — Express error handler
 │   │       └── server.js       # Express app setup
 │   ├── utils/
-│   │   └── error.middleware.ts  # TS — global error handler
+│   │   └── errorMiddleware.ts  # TS — global error handler
 │   └── index.js|ts              # Registers errorMiddleware after Apollo/Express
 └── ...
 ```

package/lib/generator.js

@@ -1,8 +1,8 @@
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { setupProjectDirectory, copyBaseStructure, copyCommonFiles } from './modules/project-setup.js';
-import { renderPackageJson, renderDockerCompose, renderReadme, renderDockerfile, renderProfessionalConfig, setupCiCd, renderTestSample, renderEnvExample } from './modules/config-files.js';
-import { renderIndexFile, renderErrorMiddleware, renderDynamicComponents, renderSwaggerConfig, setupViews as setupSrcViews } from './modules/app-setup.js';
+import { renderPackageJson, renderDockerCompose, renderReadme, renderDockerfile, renderProfessionalConfig, setupCiCd, renderTestSample, renderEnvExample, renderPm2Config } from './modules/config-files.js';
+import { renderIndexFile, renderEnvConfig, renderErrorMiddleware, renderDynamicComponents, renderSwaggerConfig, setupViews as setupSrcViews } from './modules/app-setup.js';
 import { setupDatabase } from './modules/database-setup.js';
 import { setupKafka, setupViews } from './modules/kafka-setup.js';
 import { setupCaching } from './modules/caching-setup.js';
@@ -33,6 +33,9 @@ export const generateProject = async (config) => {
     // 6. Render index file (ts/js)
     await renderIndexFile(templatePath, targetDir, config);
 
+    // 6a. Render Environment Configuration
+    await renderEnvConfig(templatePath, targetDir, config);
+
     // 6a. Render error middleware
     await renderErrorMiddleware(templatePath, targetDir, config);
 
@@ -73,6 +76,9 @@ export const generateProject = async (config) => {
     // 15. Env Example
     await renderEnvExample(templatesDir, targetDir, config);
 
+    // 16. PM2 Configuration
+    await renderPm2Config(templatesDir, targetDir, config);
+
     console.log(`
       ====================================================
              Node.js Project Created Successfully!

package/lib/modules/app-setup.js

@@ -3,28 +3,53 @@ import path from 'path';
 import ejs from 'ejs';
 
 export const renderIndexFile = async (templatePath, targetDir, config) => {
-    const { communication, viewEngine, database, architecture, projectName, language } = config;
+    const { communication, viewEngine, database, architecture, projectName, language, caching } = config;
     const indexFileName = language === 'TypeScript' ? 'index.ts' : 'index.js';
     const indexPath = path.join(targetDir, 'src', indexFileName);
     const indexTemplateSource = path.join(templatePath, 'src', `${indexFileName}.ejs`);
-    
+
     if (await fs.pathExists(indexTemplateSource)) {
         const indexTemplate = await fs.readFile(indexTemplateSource, 'utf-8');
-        const indexContent = ejs.render(indexTemplate, { 
-            communication, 
+        const indexContent = ejs.render(indexTemplate, {
+            communication,
             viewEngine,
             database,
             architecture,
-            projectName
+            projectName,
+            caching
         });
         await fs.writeFile(indexPath, indexContent);
         await fs.remove(path.join(targetDir, 'src', `${indexFileName}.ejs`));
     }
 };
 
+export const renderEnvConfig = async (templatePath, targetDir, config) => {
+    const { language, architecture, database, caching, communication } = config;
+    const envExt = language === 'TypeScript' ? 'ts' : 'js';
+
+    let configDir = path.join(targetDir, 'src', 'config');
+    if (architecture === 'Clean Architecture' && language === 'JavaScript') {
+        configDir = path.join(targetDir, 'src', 'infrastructure', 'config');
+    }
+
+    const envTemplatePath = path.join(configDir, `env.${envExt}.ejs`);
+    const envDestPath = path.join(configDir, `env.${envExt}`);
+
+    if (await fs.pathExists(envTemplatePath)) {
+        const envTemplate = await fs.readFile(envTemplatePath, 'utf-8');
+        const envContent = ejs.render(envTemplate, {
+            database,
+            caching,
+            communication
+        });
+        await fs.writeFile(envDestPath, envContent);
+        await fs.remove(envTemplatePath);
+    }
+};
+
 export const renderErrorMiddleware = async (templatePath, targetDir, config) => {
     const { language, architecture } = config;
-    const errName = language === 'TypeScript' ? 'error.middleware.ts' : 'error.middleware.js';
+    const errName = language === 'TypeScript' ? 'errorMiddleware.ts' : 'errorMiddleware.js';
     const errTemplateName = `${errName}.ejs`;
 
     if (architecture === 'MVC') {
@@ -44,8 +69,8 @@ export const renderErrorMiddleware = async (templatePath, targetDir, config) =>
             await fs.writeFile(utilsDest, await fs.readFile(utilsEjsCopy, 'utf-8'));
             await fs.remove(utilsEjsCopy);
         }
-        // Also render the middlewares version if present (NOT removing from template)
-        const mwDir = path.join(targetDir, 'src/infrastructure/webserver/middlewares');
+        // Also render the middleware version if present (NOT removing from template)
+        const mwDir = path.join(targetDir, 'src/infrastructure/webserver/middleware');
         const mwEjsCopy = path.join(mwDir, errTemplateName);
         const mwDest = path.join(mwDir, errName);
         if (await fs.pathExists(mwEjsCopy)) {
@@ -70,11 +95,11 @@ export const renderDynamicComponents = async (templatePath, targetDir, config) =
             await fs.writeFile(userControllerPath, content);
             await fs.remove(path.join(targetDir, 'src/controllers', `${userControllerName}.ejs`));
         }
-    } 
+    }
     // Clean Architecture Repo
     else if (architecture === 'Clean Architecture') {
         const repoName = language === 'TypeScript' ? 'UserRepository.ts' : 'UserRepository.js';
-        const repoPath = path.join(targetDir, 'src/infrastructure/repositories', repoName); 
+        const repoPath = path.join(targetDir, 'src/infrastructure/repositories', repoName);
         const repoTemplate = path.join(templatePath, 'src/infrastructure/repositories', `${repoName}.ejs`);
 
         if (await fs.pathExists(repoTemplate)) {
@@ -95,22 +120,58 @@ export const renderDynamicComponents = async (templatePath, targetDir, config) =
     }
     // Render Server (Clean Arch JS only)
     if (architecture === 'Clean Architecture' && language === 'JavaScript') {
-         const serverName = 'server.js';
-         const serverPath = path.join(targetDir, 'src/infrastructure/webserver', serverName);
-         const serverTemplate = path.join(templatePath, 'src/infrastructure/webserver', `${serverName}.ejs`);
-         
-         if (await fs.pathExists(serverTemplate)) {
-             const content = ejs.render(await fs.readFile(serverTemplate, 'utf-8'), { communication: config.communication });
-             await fs.writeFile(serverPath, content);
-             await fs.remove(path.join(targetDir, 'src/infrastructure/webserver', `${serverName}.ejs`));
-         }
+        const serverName = 'server.js';
+        const serverPath = path.join(targetDir, 'src/infrastructure/webserver', serverName);
+        const serverTemplate = path.join(templatePath, 'src/infrastructure/webserver', `${serverName}.ejs`);
+
+        if (await fs.pathExists(serverTemplate)) {
+            const content = ejs.render(await fs.readFile(serverTemplate, 'utf-8'), { communication: config.communication, database, caching });
+            await fs.writeFile(serverPath, content);
+            await fs.remove(path.join(targetDir, 'src/infrastructure/webserver', `${serverName}.ejs`));
+        }
+    }
+
+    // Cleanup REST routes if GraphQL or Kafka is selected
+    if (config.communication !== 'REST APIs') {
+        if (architecture === 'MVC') {
+            await fs.remove(path.join(targetDir, 'src/routes'));
+        } else if (architecture === 'Clean Architecture') {
+            await fs.remove(path.join(targetDir, 'src/interfaces/routes'));
+        }
+    }
+
+    // Advanced Health Check Route Modularization
+    const healthExt = language === 'TypeScript' ? 'ts' : 'js';
+    const healthTemplatePath = path.join(templatePath, '../../common/health', healthExt, `healthRoute.${healthExt}.ejs`);
+
+    if (await fs.pathExists(healthTemplatePath)) {
+        let routeDestDir = path.join(targetDir, 'src', 'routes');
+        if (architecture === 'Clean Architecture') {
+            routeDestDir = path.join(targetDir, 'src', 'interfaces', 'routes');
+        }
+        await fs.ensureDir(routeDestDir);
+
+        const healthRouteContent = ejs.render(await fs.readFile(healthTemplatePath, 'utf-8'), { database, architecture });
+        await fs.writeFile(path.join(routeDestDir, `healthRoute.${healthExt}`), healthRouteContent);
+    }
+
+    // Advanced Graceful Shutdown Modularization
+    const shutdownExt = language === 'TypeScript' ? 'ts' : 'js';
+    const shutdownTemplatePath = path.join(templatePath, '../../common/shutdown', shutdownExt, `gracefulShutdown.${shutdownExt}.ejs`);
+
+    if (await fs.pathExists(shutdownTemplatePath)) {
+        let utilsDestDir = path.join(targetDir, 'src', 'utils');
+        await fs.ensureDir(utilsDestDir);
+
+        const shutdownContent = ejs.render(await fs.readFile(shutdownTemplatePath, 'utf-8'), { database, architecture, caching, communication: config.communication });
+        await fs.writeFile(path.join(utilsDestDir, `gracefulShutdown.${shutdownExt}`), shutdownContent);
     }
 
     // GraphQL Setup
     if (config.communication === 'GraphQL') {
         const ext = language === 'TypeScript' ? 'ts' : 'js';
         let graphqlInternalPath = architecture === 'MVC' ? 'src/graphql' : 'src/interfaces/graphql';
-        
+
         const sourceGraphqDir = path.join(templatePath, graphqlInternalPath);
         const targetGraphqlDir = path.join(targetDir, graphqlInternalPath);
 
@@ -145,27 +206,18 @@ export const renderDynamicComponents = async (templatePath, targetDir, config) =
         let graphqlInternalPath = architecture === 'MVC' ? 'src/graphql' : 'src/interfaces/graphql';
         await fs.remove(path.join(targetDir, graphqlInternalPath));
     }
-
-    // Cleanup REST routes if GraphQL or Kafka is selected
-    if (config.communication !== 'REST APIs') {
-        if (architecture === 'MVC') {
-            await fs.remove(path.join(targetDir, 'src/routes'));
-        } else if (architecture === 'Clean Architecture') {
-            await fs.remove(path.join(targetDir, 'src/interfaces/routes'));
-        }
-    }
 };
 
 export const renderSwaggerConfig = async (templatesDir, targetDir, config) => {
     const { communication, projectName, architecture, language } = config;
-    
+
     // Check for Swagger config template (typically in src/config/swagger.ts.ejs)
     const swaggerTsTemplate = path.join(targetDir, 'src', 'config', 'swagger.ts.ejs');
     // MVC JS uses swagger.js.ejs in src/config/
     const swaggerJsTemplate = path.join(targetDir, 'src', 'config', 'swagger.js.ejs');
     // Clean Arch JS uses swagger.js.ejs in src/infrastructure/webserver/
     const swaggerJsCleanTemplate = path.join(targetDir, 'src', 'infrastructure', 'webserver', 'swagger.js.ejs');
-    
+
     // Ensure config directory exists
     let configDir = path.join(targetDir, 'src', 'config');
     if (architecture === 'Clean Architecture' && language === 'JavaScript') {
@@ -197,7 +249,7 @@ export const renderSwaggerConfig = async (templatesDir, targetDir, config) => {
             await fs.writeFile(path.join(targetDir, 'src', 'infrastructure', 'webserver', 'swagger.js'), content);
         }
     }
-    
+
     // Always remove the .ejs template after processing (or if non-REST, just delete it)
     if (await fs.pathExists(swaggerTsTemplate)) await fs.remove(swaggerTsTemplate);
     if (await fs.pathExists(swaggerJsTemplate)) await fs.remove(swaggerJsTemplate);
@@ -215,7 +267,7 @@ export const setupViews = async (templatesDir, targetDir, config) => {
     if (architecture === 'MVC' && viewEngine && viewEngine !== 'None') {
         const viewsSource = path.join(templatesDir, 'common', 'views', viewEngine.toLowerCase());
         if (await fs.pathExists(viewsSource)) {
-             await fs.copy(viewsSource, path.join(targetDir, 'src/views'));
+            await fs.copy(viewsSource, path.join(targetDir, 'src/views'));
         }
     }
 };

package/lib/modules/config-files.js

@@ -59,6 +59,21 @@ export const renderDockerfile = async (templatesDir, targetDir, config) => {
     await fs.writeFile(path.join(targetDir, 'Dockerfile'), dockerfileContent);
 };
 
+export const renderPm2Config = async (templatesDir, targetDir, config) => {
+    const { projectName, database, dbName, communication, language, caching } = config;
+    const pm2ConfigPath = path.join(targetDir, 'ecosystem.config.js');
+    const pm2Template = await fs.readFile(path.join(templatesDir, 'common', 'ecosystem.config.js.ejs'), 'utf-8');
+    const pm2Content = ejs.render(pm2Template, {
+        projectName,
+        database,
+        dbName,
+        communication,
+        language,
+        caching
+    });
+    await fs.writeFile(pm2ConfigPath, pm2Content);
+};
+
 export const renderProfessionalConfig = async (templatesDir, targetDir, language) => {
     const eslintTemplate = await fs.readFile(path.join(templatesDir, 'common', 'eslint.config.mjs.ejs'), 'utf-8');
     const eslintContent = ejs.render(eslintTemplate, { language });
@@ -98,7 +113,8 @@ export const renderTestSample = async (templatesDir, targetDir, language) => {
 
 export const renderEnvExample = async (templatesDir, targetDir, config) => {
     const { database, dbName, communication, projectName, caching } = config;
-    const envPath = path.join(targetDir, '.env.example');
+    const envExamplePath = path.join(targetDir, '.env.example');
+    const envPath = path.join(targetDir, '.env');
     const envTemplate = await fs.readFile(path.join(templatesDir, 'common', '.env.example.ejs'), 'utf-8');
     
     const envContent = ejs.render(envTemplate, {
@@ -109,5 +125,6 @@ export const renderEnvExample = async (templatesDir, targetDir, config) => {
         caching
     });
     
+    await fs.writeFile(envExamplePath, envContent);
     await fs.writeFile(envPath, envContent);
 };

package/lib/modules/kafka-setup.js

@@ -55,25 +55,14 @@ export const setupKafka = async (templatesDir, targetDir, config) => {
         // Cleanup old services folder
         await fs.remove(path.join(targetDir, 'src/services'));
         
-        // Remove src/config if it was only for Kafka and not needed by other parts
-        // But Database setup might assume src/config existence in some templates (though moved to infrastructure/database for clean arch)
-        // Safest to leave src/config if non-empty, or remove if empty. 
-        // For now, mirroring original logic: remove specific REST folders
-        
-        // Remove REST-specific folders (Interfaces)
-        await fs.remove(path.join(targetDir, 'src/interfaces/routes'));
+        // Remove REST-specific folders (Interfaces) - Note: routes is kept for health endpoint
         await fs.remove(path.join(targetDir, 'src/interfaces/controllers'));
         
-        // Original logic removed src/config entirely for clean arch kafka? 
-        // Let's check original logic: 
-        // await fs.remove(path.join(targetDir, 'src/config'));
-        // Yes, it did.
-         await fs.remove(path.join(targetDir, 'src/config'));
-
+        // Original logic removed src/config entirely, but now we use it for Zod env validation in TS.
+        // We will no longer delete it.
     } else if (architecture === 'MVC' && (!config.viewEngine || config.viewEngine === 'None')) {
-        // MVC Cleanup for Kafka Worker (No views)
+        // MVC Cleanup for Kafka Worker (No views) - Note: routes is kept for health endpoint
         await fs.remove(path.join(targetDir, 'src/controllers'));
-        await fs.remove(path.join(targetDir, 'src/routes'));
     }
 };
 
@@ -84,29 +73,5 @@ export const setupViews = async (templatesDir, targetDir, config) => {
         if (await fs.pathExists(publicDir)) {
             await fs.copy(publicDir, path.join(targetDir, 'public'));
         }
-        
-        // Copy views mapping
-        // Logic handled in database-setup (part of db config block in original) but functionally belongs here or separate.
-        // Original: if (viewEngine && viewEngine !== 'None') await fs.copy(...) inside the DB block for MVC.
-        // We moved it to database-setup.js to match flow, but let's double check if we missed it there.
-        // Checked database-setup.js: It copies views ONLY if database !== 'None' OR if database === 'None'
-        // So it is covered. Ideally it should be here, but for now strict refactor keeps it effectively in DB/structure setup phase.
-        // To be cleaner, we should move the VIEW copying here.
-        
-        // Moving View Copying Check here for better separation:
-        // We need to verify if database-setup.js ALREADY does this. 
-        // In my prev step for database-setup.js, I included logic:
-        // if (architecture === 'MVC') { if (viewEngine...) copy views }
-        // So duplication might occur if I add it here too. 
-        // Let's relies on this module ONLY for public assets for now, or ensure idempotency.
-        
-        // Actually, let's keep it clean. database-setup.js shouldn't handle views. 
-        // I will assume I can update database-setup.js to remove view copying if I put it here?
-        // OR just leave it there for this iteration to avoid breaking changes in flow order.
-        // Let's stick to the original flow where possible, but this module is 'kafka-and-views'.
-        
-        // The original logic had view copying inside the "Database Config" block.
-        // My database-setup.js preserved that. 
-        // So this logic here only handles 'public' folder copying which was Step 8 in original.
     }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodejs-quickstart-structure",
-  "version": "1.11.1",
+  "version": "1.13.0",
   "type": "module",
   "description": "A CLI to scaffold Node.js microservices with MVC or Clean Architecture",
   "main": "bin/index.js",

package/templates/clean-architecture/js/src/index.js.ejs

@@ -4,8 +4,6 @@ const logger = require('./infrastructure/log/logger');
 const { connectKafka, sendMessage } = require('./infrastructure/messaging/kafkaClient');
 <% } -%>
 
-const PORT = process.env.PORT || 3000;
-
 <%_ if (database !== 'None') { -%>
 // Database Sync
 const syncDatabase = async () => {
@@ -21,7 +19,7 @@ const syncDatabase = async () => {
             <%_ } -%>
             logger.info('Database synced');
             // Start the web server after DB sync
-            startServer(PORT);
+            startServer();
             <%_ if (communication === 'Kafka') { -%>
             // Connect Kafka
             connectKafka().then(async () => {
@@ -42,7 +40,7 @@ const syncDatabase = async () => {
 };
 syncDatabase();
 <%_ } else { -%>
-startServer(PORT);
+startServer();
 <%_ if (communication === 'Kafka') { -%>
 // Connect Kafka
 connectKafka().then(async () => {

package/templates/clean-architecture/js/src/infrastructure/config/env.js.ejs

@@ -0,0 +1,47 @@
+const { z } = require('zod');
+const logger = require('../log/logger');
+
+if (process.env.NODE_ENV !== 'production') {
+  require('dotenv').config();
+}
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z.string().transform(Number).default('3000'),
+<%_ if (database !== 'None') { -%>
+  DB_HOST: z.string(),
+<%_ if (database === 'MySQL') { -%>
+  DB_USER: z.string(),
+  DB_PASSWORD: z.string(),
+  DB_NAME: z.string(),
+  DB_PORT: z.string().transform(Number),
+<%_ } else if (database === 'PostgreSQL') { -%>
+  DB_USER: z.string(),
+  DB_PASSWORD: z.string(),
+  DB_NAME: z.string(),
+  DB_PORT: z.string().transform(Number),
+<%_ } else if (database === 'MongoDB') { -%>
+  DB_NAME: z.string(),
+  DB_PORT: z.string().transform(Number),
+<%_ } -%>
+<%_ } -%>
+<%_ if (caching === 'Redis') { -%>
+  REDIS_HOST: z.string(),
+  REDIS_PORT: z.string().transform(Number),
+  REDIS_PASSWORD: z.string().optional(),
+<%_ } -%>
+<%_ if (communication === 'Kafka') { -%>
+  KAFKA_BROKER: z.string(),
+<%_ } -%>
+});
+
+const _env = envSchema.safeParse(process.env);
+
+if (!_env.success) {
+  logger.error('❌ Invalid environment variables:', _env.error.format());
+  process.exit(1);
+}
+
+const env = _env.data;
+
+module.exports = { env };

package/templates/clean-architecture/js/src/infrastructure/webserver/{middlewares/error.middleware.js → middleware/errorMiddleware.js}

@@ -2,7 +2,8 @@ const logger = require('../../log/logger');
 const { ApiError } = require('../../../errors/ApiError');
 const HTTP_STATUS = require('../../../utils/httpCodes');
 
-const errorMiddleware = (err, req, res, _) => {
+// eslint-disable-next-line no-unused-vars
+const errorMiddleware = (err, req, res, next) => {
   let error = err;
 
   if (!(error instanceof ApiError)) {

package/templates/clean-architecture/js/src/infrastructure/webserver/server.js.ejs

@@ -1,11 +1,11 @@
 const express = require('express');
 const cors = require('cors');
-require('dotenv').config();
 const logger = require('../log/logger');
 const morgan = require('morgan');
-const { errorMiddleware } = require('./middlewares/error.middleware');
-<%_ if (communication === 'REST APIs') { -%>const apiRoutes = require('../../interfaces/routes/api');<%_ } -%>
+const { errorMiddleware } = require('./middleware/errorMiddleware');
+const healthRoutes = require('../../interfaces/routes/healthRoute');
 <%_ if (communication === 'REST APIs') { -%>
+const apiRoutes = require('../../interfaces/routes/api');
 const swaggerUi = require('swagger-ui-express');
 const swaggerSpecs = require('./swagger');
 <%_ } -%>
@@ -19,7 +19,11 @@ const { typeDefs, resolvers } = require('../../interfaces/graphql');
 const { gqlContext } = require('../../interfaces/graphql/context');
 <%_ } -%>
 
-const startServer = async (port) => {
+const { env } = require('../config/env');
+
+const startServer = async () => {
+    // Determine port using the validated env
+    const port = env.PORT;
     const app = express();
 
     app.use(cors());
@@ -33,7 +37,7 @@ const startServer = async (port) => {
     <%_ } -%>
     <%_ if (communication === 'GraphQL') { -%>
     // GraphQL Setup
-    const server = new ApolloServer({
+    const apolloServer = new ApolloServer({
         typeDefs,
         resolvers,
         plugins: [ApolloServerPluginLandingPageLocalDefault({ embed: true })],
@@ -57,18 +61,28 @@ const startServer = async (port) => {
             return formattedError;
         },
     });
-    await server.start();
-    app.use('/graphql', expressMiddleware(server, { context: gqlContext }));
+    await apolloServer.start();
+    app.use('/graphql', expressMiddleware(apolloServer, { context: gqlContext }));
     <%_ } -%>
-    app.get('/health', (req, res) => {
-        res.json({ status: 'UP' });
-    });
+    app.use('/health', healthRoutes);
 
     app.use(errorMiddleware);
 
-    app.listen(port, () => {
+    const server = app.listen(port, () => {
         logger.info(`Server running on port ${port}`);
+<%_ if (communication === 'Kafka') { -%>
+        const { connectKafka, sendMessage } = require('../../infrastructure/messaging/kafkaClient');
+        connectKafka().then(() => {
+          logger.info('Kafka connected');
+          sendMessage('test-topic', 'Hello Kafka from Clean Arch JS!');
+        }).catch(err => {
+          logger.error('Failed to connect to Kafka:', err);
+        });
+<%_ } -%>
     });
+
+    const setupGracefulShutdown = require('../../utils/gracefulShutdown');
+    setupGracefulShutdown(server);
 };
 
 module.exports = startServer;

package/templates/clean-architecture/js/src/interfaces/graphql/resolvers/user.resolvers.js.ejs

@@ -12,7 +12,10 @@ const userResolvers = {
     createUser: async (_, { name, email }) => {
       return await userController.createUser({ name, email });
     }
-  }
+  }<%_ if (database === 'MongoDB') { -%>,
+  User: {
+    id: (parent) => parent.id || parent._id
+  }<%_ } %>
 };
 
 module.exports = { userResolvers };