nodejs-quickstart-structure 1.16.0 → 1.16.1

package/CHANGELOG.md

@@ -5,6 +5,16 @@ 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.16.1] - 2026-03-17
+
+### Refactored
+- **Top-Level Dynamic Imports**: Moved dynamic `await import()` and `require()` calls to the top-level across all TypeScript and JavaScript templates (MVC & Clean Architecture).
+- **Module Loading Standardization**: Standardized database connections (Mongoose/Sequelize), Kafka services, and graceful shutdown logic for better static analysis and ESM/CJS consistency.
+
+### Fixed
+- **Kafka Service Scope**: Resolved a potential `ReferenceError` in `kafkaService.ts.ejs` by correcting the instantiation order of dynamic consumers.
+- **Health Check Imports**: Optimized `healthRoute.ts.ejs` to use top-level database driver imports.
+
 ## [1.16.0] - 2026-03-14
 
 ### Added

package/README.md

@@ -7,8 +7,6 @@
 
 A powerful CLI tool to scaffold production-ready Node.js microservices with built-in best practices, allowing you to choose between **MVC** or **Clean Architecture**, **JavaScript** or **TypeScript**, and your preferred database.
 
-[![Medium Article](https://img.shields.io/badge/Medium-Read%20Article-black?logo=medium)](https://medium.com/@paudang/nodejs-quickstart-generator-93c276d60e0b)
-
 ![Demo](docs/demo.gif)
 
 ## Features
@@ -24,6 +22,12 @@ A powerful CLI tool to scaffold production-ready Node.js microservices with buil
 - **Database Migrations/Schemas**: Integrated **Flyway** for SQL migrations or **Mongoose** schemas for MongoDB.
 - **Professional Standards**: Generated projects come with highly professional, industry-standard tooling.
 
+## 🌟 Why developers love this?
+
+- **Community Trusted**: Over **3,000+** projects bootstrapped within the first month.
+- **Actively Maintained**: Constant updates and optimizations (30+ versions released) based on real-world developer feedback.
+- **Resilience First**: Unlike basic boilerplates, our generated code focuses on infrastructure stability (Retry logic, Health checks, and Graceful shutdowns).
+
 ## 🏆 Professional Standards (New)
 
 We don't just generate boilerplate; we generate **production-ready** foundations. Every project includes:
@@ -34,7 +38,7 @@ We don't just generate boilerplate; we generate **production-ready** foundations
 -   **🧪 Testing Excellence**: Integrated `Jest` and `Supertest`. Every generated project maintains **>70% Unit Test coverage** for controllers, services, and resolvers out of the box.
 -   **🔄 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.
+-   **🤝 Reliability**: Health Checks (`/health`) with deep database pings, Infrastructure Retry Logic (handling Docker startup delays), and Graceful Shutdown workflows.
 -   **🐳 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.
 
@@ -66,14 +70,13 @@ Once installed, simply run the following command in any directory where you want
 ```bash
 nodejs-quickstart init
 ```
-or
 
 ## Quick Start (Recommended)
 
 You can run the generator directly without installing it globally:
 
 ```bash
-npx nodejs-quickstart-structure init
+npx nodejs-quickstart-structure@latest init
 ```
 
 ### Configuration Options
@@ -111,6 +114,12 @@ npm install
 docker-compose up
 ```
 
+## ❤️ Support the Project
+
+We just hit **3,000 downloads**! If this tool helped you save hours of setup time, please consider:
+- Giving us a ⭐ on [GitHub](https://github.com/paudang/nodejs-quickstart-structure) to help others find it.
+- Following the [Medium Article](https://medium.com/@paudang/nodejs-quickstart-generator-93c276d60e0b) for deep-dive tutorials.
+
 ## License
 
 ISC

package/package.json

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

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

@@ -3,18 +3,23 @@ const logger = require('./infrastructure/log/logger');
 <% if (communication === 'Kafka') { -%>
 const { connectKafka } = require('./infrastructure/messaging/kafkaClient');
 <% } -%>
-
 <%_ if (database !== 'None') { -%>
 // Database Sync
+<%_ if (database !== 'None') { -%>
+<%_ if (database === 'MongoDB') { -%>
+const connectDB = require('./infrastructure/database/database');
+<%_ } else { -%>
+const sequelize = require('./infrastructure/database/database');
+<%_ } -%>
+<%_ } -%>
+
 const syncDatabase = async () => {
     let retries = 30;
     while (retries) {
         try {
             <%_ if (database === 'MongoDB') { -%>
-            const connectDB = require('./infrastructure/database/database');
             await connectDB();
             <%_ } else { -%>
-            const sequelize = require('./infrastructure/database/database');
             await sequelize.sync();
             <%_ } -%>
             logger.info('Database synced');

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

@@ -4,6 +4,7 @@ const logger = require('../log/logger');
 const morgan = require('morgan');
 const { errorMiddleware } = require('./middleware/errorMiddleware');
 const healthRoutes = require('../../interfaces/routes/healthRoute');
+const setupGracefulShutdown = require('../../utils/gracefulShutdown');
 <%_ if (communication === 'REST APIs' || communication === 'Kafka') { -%>
 const apiRoutes = require('../../interfaces/routes/api');
 const swaggerUi = require('swagger-ui-express');
@@ -82,7 +83,6 @@ const startServer = async () => {
 <%_ } -%>
     });
 
-    const setupGracefulShutdown = require('../../utils/gracefulShutdown');
     setupGracefulShutdown(server);
 };
 

package/templates/clean-architecture/js/src/interfaces/controllers/userController.js.ejs

@@ -5,6 +5,9 @@ const UserRepository = require('../../infrastructure/repositories/UserRepository
 const HTTP_STATUS = require('../../utils/httpCodes');
 <% } -%>
 const logger = require('../../infrastructure/log/logger');
+<%_ if (communication === 'Kafka') { -%>
+const { sendMessage } = require('../../infrastructure/messaging/kafkaClient');
+<%_ } -%>
 
 class UserController {
     constructor() {
@@ -28,7 +31,6 @@ class UserController {
         try {
             const user = await this.createUserUseCase.execute(name, email);
 <%_ if (communication === 'Kafka') { -%>
-            const { sendMessage } = require('../../infrastructure/messaging/kafkaClient');
             await sendMessage('user-topic', JSON.stringify({
                 action: 'USER_CREATED',
                 payload: { id: user.id || user._id, email: user.email }
@@ -56,7 +58,6 @@ class UserController {
         try {
             const user = await this.createUserUseCase.execute(name, email);
 <%_ if (communication === 'Kafka') { -%>
-            const { sendMessage } = require('../../infrastructure/messaging/kafkaClient');
             await sendMessage('user-topic', JSON.stringify({
                 action: 'USER_CREATED',
                 payload: { id: user.id || user._id, email: user.email }

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

@@ -110,15 +110,17 @@ const startServer = async () => {
 
 <%_ if (database !== 'None') { -%>
 // Database Sync
+<%_ if (database !== 'None') { -%>
+import <% if (database === 'MongoDB') { %>connectDB<% } else { %>sequelize<% } %> from '@/infrastructure/database/database';
+<%_ } -%>
+
 const syncDatabase = async () => {
     let retries = 30;
     while (retries) {
         try {
             <%_ if (database === 'MongoDB') { -%>
-            const connectDB = (await import('@/infrastructure/database/database')).default;
             await connectDB();
             <%_ } else { -%>
-            const sequelize = (await import('@/infrastructure/database/database')).default;
             await sequelize.sync();
             <%_ } -%>
             logger.info('Database synced');

package/templates/clean-architecture/ts/src/interfaces/controllers/userController.ts.ejs

@@ -6,6 +6,9 @@ import { UserRepository } from '@/infrastructure/repositories/UserRepository';
 import CreateUser from '@/usecases/createUser';
 import GetAllUsers from '@/usecases/getAllUsers';
 import logger from '@/infrastructure/log/logger';
+<%_ if (communication === 'Kafka') { -%>
+import { kafkaService } from '@/infrastructure/messaging/kafkaClient';
+<%_ } -%>
 
 export class UserController {
     private createUserUseCase: CreateUser;
@@ -23,7 +26,6 @@ export class UserController {
             const { name, email } = data;
             const user = await this.createUserUseCase.execute(name, email);
 <%_ if (communication === 'Kafka') { -%>
-            const { kafkaService } = await import('@/infrastructure/messaging/kafkaClient');
             await kafkaService.sendMessage('user-topic', JSON.stringify({
                 action: 'USER_CREATED',
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -54,7 +56,6 @@ export class UserController {
             const { name, email } = req.body;
             const user = await this.createUserUseCase.execute(name, email);
 <%_ if (communication === 'Kafka') { -%>
-            const { kafkaService } = await import('@/infrastructure/messaging/kafkaClient');
             await kafkaService.sendMessage('user-topic', JSON.stringify({
                 action: 'USER_CREATED',
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/templates/common/health/js/healthRoute.js.ejs

@@ -2,6 +2,11 @@ const express = require('express');
 const router = express.Router();
 const logger = require('<% if (architecture === "MVC") { %>../utils/logger<% } else { %>../../infrastructure/log/logger<% } %>');
 const HTTP_STATUS = require('<% if (architecture === "MVC") { %>../utils/httpCodes<% } else { %>../../utils/httpCodes<% } %>');
+<%_ if (database === 'MongoDB') { -%>
+const mongoose = require('mongoose');
+<%_ } else if (database !== 'None') { -%>
+const sequelize = require('<% if (architecture === "MVC") { %>../config/database<% } else { %>../../infrastructure/database/database<% } %>');
+<%_ } -%>
 
 router.get('/', async (req, res) => {
   const healthData = {
@@ -16,7 +21,6 @@ router.get('/', async (req, res) => {
 <%_ if (database !== 'None') { -%>
   try {
 <%_ if (database === 'MongoDB') { -%>
-    const mongoose = require('mongoose');
     if (mongoose.connection.readyState === 1) {
       if (mongoose.connection.db && mongoose.connection.db.admin) {
          await mongoose.connection.db.admin().ping();
@@ -24,7 +28,6 @@ router.get('/', async (req, res) => {
       healthData.database = 'connected';
     }
 <%_ } else { -%>
-    const sequelize = require('<% if (architecture === "MVC") { %>../config/database<% } else { %>../../infrastructure/database/database<% } %>');
     await sequelize.authenticate();
     healthData.database = 'connected';
 <%_ } -%>

package/templates/common/health/ts/healthRoute.ts.ejs

@@ -1,6 +1,11 @@
 import { Router, Request, Response } from 'express';
 import logger from '<% if (architecture === "MVC") { %>@/utils/logger<% } else { %>@/infrastructure/log/logger<% } %>';
 import { HTTP_STATUS } from '@/utils/httpCodes';
+<%_ if (database === 'MongoDB') { -%>
+import mongoose from 'mongoose';
+<%_ } else if (database !== 'None') { -%>
+import sequelize from '<% if (architecture === "MVC") { %>@/config/database<% } else { %>@/infrastructure/database/database<% } %>';
+<%_ } -%>
 
 const router = Router();
 
@@ -17,13 +22,11 @@ router.get('/', async (req: Request, res: Response) => {
 <%_ if (database !== 'None') { -%>
   try {
 <%_ if (database === 'MongoDB') { -%>
-    const mongoose = (await import('mongoose')).default;
     if (mongoose.connection.readyState === 1) {
       await mongoose.connection.db?.admin().ping();
       healthData.database = 'connected';
     }
 <%_ } else { -%>
-    const sequelize = (await import('<% if (architecture === "MVC") { %>@/config/database<% } else { %>@/infrastructure/database/database<% } %>')).default;
     await sequelize.authenticate();
     healthData.database = 'connected';
 <%_ } -%>

package/templates/common/kafka/js/services/kafkaService.js.ejs

@@ -14,6 +14,10 @@ const connectKafka = async (retries = 10) => {
         if (!consumer) consumer = kafka.consumer({ groupId: 'test-group' });
 
         let attempt = 0;
+        // Auto-register WelcomeEmailConsumer if it exists
+        // Note: Dynamic import used here for simplicity and to avoid startup crashes.
+        // In enterprise production, consider using Dependency Injection.
+        const WelcomeEmailConsumer = require('<% if (architecture === "Clean Architecture") { %>../../interfaces/messaging/consumers/instances/welcomeEmailConsumer<% } else { %>../messaging/consumers/instances/welcomeEmailConsumer<% } %>');
         while (attempt < retries) {
             try {
                 await producer.connect();
@@ -22,9 +26,7 @@ const connectKafka = async (retries = 10) => {
                 logger.info('[Kafka] Consumer connected successfully');
                 isConnected = true;
 
-                // Auto-register WelcomeEmailConsumer if it exists
                 try {
-                    const WelcomeEmailConsumer = require('<% if (architecture === "Clean Architecture") { %>../../interfaces/messaging/consumers/instances/welcomeEmailConsumer<% } else { %>../messaging/consumers/instances/welcomeEmailConsumer<% } %>');
                     const welcomeConsumer = new WelcomeEmailConsumer();
                     await consumer.subscribe({ topic: welcomeConsumer.topic, fromBeginning: true });
                     logger.info(`[Kafka] Registered consumer for topic: ${welcomeConsumer.topic}`);

package/templates/common/kafka/ts/services/kafkaService.ts.ejs

@@ -18,6 +18,10 @@ export class KafkaService {
 
         this.connectionPromise = (async () => {
             let attempt = 0;
+            // Auto-register WelcomeEmailConsumer if it exists
+            // Note: Dynamic import used here for simplicity and to avoid startup crashes.
+            // In enterprise production, consider using Dependency Injection.
+            const { WelcomeEmailConsumer } = await import('<% if (architecture === "Clean Architecture") { %>@/interfaces/messaging/consumers/instances/welcomeEmailConsumer<% } else { %>@/messaging/consumers/instances/welcomeEmailConsumer<% } %>');
             while (attempt < retries) {
                 try {
                     await this.producer.connect();
@@ -26,10 +30,7 @@ export class KafkaService {
                     logger.info('[Kafka] Consumer connected successfully');
                     this.isConnected = true;
 
-                    <%_ if (language === 'TypeScript') { -%>
-                    // Auto-register WelcomeEmailConsumer if it exists
                     try {
-                        const { WelcomeEmailConsumer } = await import('<% if (architecture === "Clean Architecture") { %>@/interfaces/messaging/consumers/instances/welcomeEmailConsumer<% } else { %>@/messaging/consumers/instances/welcomeEmailConsumer<% } %>');
                         const welcomeConsumer = new WelcomeEmailConsumer();
                         await this.consumer.subscribe({ topic: welcomeConsumer.topic, fromBeginning: true });
                         logger.info(`[Kafka] Registered consumer for topic: ${welcomeConsumer.topic}`);
@@ -47,15 +48,7 @@ export class KafkaService {
                             },
                         });
                     }
-                    <%_ } else { _%>
-                    await this.consumer.subscribe({ topic: 'test-topic', fromBeginning: true });
-                    await this.consumer.run({
-                        eachMessage: async ({ message }: EachMessagePayload) => {
-                            logger.info({ value: message.value?.toString() });
-                        },
-                    });
-                    <%_ } _%>
-                    return;
+                    return; // Success
                 } catch (error) {
                     attempt++;
                     logger.error(`[Kafka] Connection attempt ${attempt} failed:`, (error as Error).message);

package/templates/common/shutdown/ts/gracefulShutdown.ts.ejs

@@ -4,6 +4,14 @@ import logger from '@/utils/logger';
 <%_ } else { -%>
 import logger from '@/infrastructure/log/logger';
 <%_ } -%>
+<%_ if (database === 'MongoDB') { -%>
+import mongoose from 'mongoose';
+<%_ } else if (database !== 'None') { -%>
+import sequelize from '<% if (architecture === "MVC") { %>@/config/database<% } else { %>@/infrastructure/database/database<% } %>';
+<%_ } -%>
+<%_ if (caching === 'Redis') { -%>
+import redisService from '<% if (architecture === "MVC") { %>@/config/redisClient<% } else { %>@/infrastructure/caching/redisClient<% } %>';
+<%_ } -%>
 
 export const setupGracefulShutdown = (server: Server<% if (communication === 'Kafka') { %>, kafkaService: { disconnect: () => Promise<void> }<% } %>) => {
     const gracefulShutdown = async (signal: string) => {
@@ -13,25 +21,14 @@ export const setupGracefulShutdown = (server: Server<% if (communication === 'Ka
             try {
 <%_ if (database !== 'None') { -%>
 <%_ if (database === 'MongoDB') { -%>
-                const mongoose = (await import('mongoose')).default;
                 await mongoose.connection.close(false);
                 logger.info('MongoDB connection closed.');
 <%_ } else { -%>
-                <%_ if (architecture === 'MVC') { -%>
-                const sequelize = (await import('@/config/database')).default;
-                <%_ } else { -%>
-                const sequelize = (await import('@/infrastructure/database/database')).default;
-                <%_ } -%>
                 await sequelize.close();
                 logger.info('Database connection closed.');
 <%_ } -%>
 <%_ } -%>
 <%_ if (caching === 'Redis') { -%>
-                <%_ if (architecture === 'MVC') { -%>
-                const redisService = (await import('@/config/redisClient')).default;
-                <%_ } else { -%>
-                const redisService = (await import('@/infrastructure/caching/redisClient')).default;
-                <%_ } -%>
                 await redisService.quit();
                 logger.info('Redis connection closed.');
 <%_ } -%>

package/templates/mvc/js/src/controllers/userController.js.ejs

@@ -8,6 +8,9 @@ const cacheService = require('../config/redisClient');
 <%_ } else if (caching === 'Memory Cache') { -%>
 const cacheService = require('../config/memoryCache');
 <%_ } -%>
+<%_ if (communication === 'Kafka') { -%>
+const { sendMessage } = require('../services/kafkaService');
+<%_ } -%>
 
 <% if (communication === 'GraphQL') { -%>
 const getUsers = async () => {
@@ -42,7 +45,6 @@ const createUser = async (data) => {
     await cacheService.del('users:all');
 <%_ } -%>
 <%_ if (communication === 'Kafka') { -%>
-    const { sendMessage } = require('../services/kafkaService');
     await sendMessage('user-topic', JSON.stringify({
       action: 'USER_CREATED',
       payload: { id: user.id || user._id, email: user.email }
@@ -87,7 +89,6 @@ const createUser = async (req, res, next) => {
     await cacheService.del('users:all');
 <%_ } -%>
 <%_ if (communication === 'Kafka') { -%>
-    const { sendMessage } = require('../services/kafkaService');
     await sendMessage('user-topic', JSON.stringify({
       action: 'USER_CREATED',
       payload: { id: user.id || user._id, email: user.email }

package/templates/mvc/js/src/index.js.ejs

@@ -17,6 +17,7 @@ const swaggerUi = require('swagger-ui-express');
 const swaggerSpecs = require('./config/swagger');
 <%_ } -%>
 const { env } = require('./config/env');
+const setupGracefulShutdown = require('./utils/gracefulShutdown');
 
 const app = express();
 const PORT = env.PORT;
@@ -96,25 +97,28 @@ const startServer = async () => {
 <%_ } -%>
     });
 
-    const setupGracefulShutdown = require('./utils/gracefulShutdown');
     setupGracefulShutdown(server);
 };
 
 <%_ if (database !== 'None') { -%>
 // Database Sync
+<%_ if (database !== 'None') { -%>
+<%_ if (database === 'MongoDB') { -%>
+const connectDB = require('./config/database');
+<%_ } else { -%>
+const sequelize = require('./config/database');
+<%_ } -%>
+<%_ } -%>
 const syncDatabase = async () => {
     let retries = 30;
     while (retries) {
         try {
             <%_ if (database === 'MongoDB') { -%>
-            const connectDB = require('./config/database');
             await connectDB();
             <%_ } else { -%>
-            const sequelize = require('./config/database');
             await sequelize.sync();
             <%_ } -%>
             logger.info('Database synced');
-            
             // Start Server after DB is ready
             await startServer();
             break;

package/templates/mvc/ts/src/controllers/userController.ts.ejs

@@ -8,6 +8,8 @@ import logger from '@/utils/logger';
 import cacheService from '@/config/redisClient';
 <%_ } else if (caching === 'Memory Cache') { -%>
 import cacheService from '@/config/memoryCache';
+<%_ } -%><%_ if (communication === 'Kafka') { -%>
+import { kafkaService } from '@/services/kafkaService';
 <%_ } -%>
 
 export class UserController {
@@ -44,7 +46,6 @@ export class UserController {
             await cacheService.del('users:all');
 <%_ } -%>
 <%_ if (communication === 'Kafka') { -%>
-            const { kafkaService } = await import('@/services/kafkaService');
             await kafkaService.sendMessage('user-topic', JSON.stringify({
                 action: 'USER_CREATED',
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -90,7 +91,6 @@ export class UserController {
             await cacheService.del('users:all');
 <%_ } -%>
 <%_ if (communication === 'Kafka') { -%>
-            const { kafkaService } = await import('@/services/kafkaService');
             await kafkaService.sendMessage('user-topic', JSON.stringify({
                 action: 'USER_CREATED',
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/templates/mvc/ts/src/index.ts.ejs

@@ -123,15 +123,16 @@ const startServer = async () => {
 
 <%_ if (database !== 'None') { -%>
 // Database Sync
+<%_ if (database !== 'None') { -%>
+import <% if (database === 'MongoDB') { %>connectDB<% } else { %>sequelize<% } %> from '@/config/database';
+<%_ } -%>
 const syncDatabase = async () => {
     let retries = 30;
     while (retries) {
         try {
             <%_ if (database === 'MongoDB') { -%>
-            const connectDB = (await import('@/config/database')).default;
             await connectDB();
             <%_ } else { -%>
-            const sequelize = (await import('@/config/database')).default;
             await sequelize.sync();
             <%_ } -%>
             logger.info('Database synced');