nodejs-quickstart-structure 1.9.2 → 1.9.4

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.9.4] - 2026-02-26
+### Fixed
+- Fixed an `EBADENGINE` compatibility issue during Docker builds by upgrading the default template `Dockerfile` base image from `node:18-alpine` to `node:22-alpine`, supporting modern dependencies like `eslint@9` and `cpx2`.
+- Fixed a port collision bug (`Bind for 0.0.0.0:6379 failed: port is already allocated`) during parallel E2E testing. The `validation-core.js` script now dynamically assigns random network ports for `REDIS_PORT` when running concurrent testing matrices.
+
+## [1.9.3] - 2026-02-26
+### Added
+- Refactored Swagger documentation to use a standalone `swagger.yml` file instead of inline JSDoc comments across all templates (MVC, Clean Architecture, TS, and JS).
+- Integrated `yamljs` to parse the `swagger.yml` file and removed the `swagger-jsdoc` dependency, significantly reducing boilerplate in route files.
+
+### Fixed
+- Fixed an issue in `package.json.ejs` where `jest` configuration had malformed JSON due to whitespace stripping.
+- Fixed a Docker build crash for non-REST API projects caused by the build script unconditionally attempting to copy `swagger.yml` using `cpx2`.
+
 ## [1.9.2] - 2026-02-23
 ### Fixed
 - Fixed an issue where the generator output misleading instructions (`DATABASE_URL`) for standalone `docker run` executions. The CLI success commands and `README.md` now conditionally include dynamic compose network bindings (`--network`) and accurate environment variables matching the user's selected DB stack.

package/lib/generator.js

@@ -58,7 +58,7 @@ export const generateProject = async (config) => {
     await setupSrcViews(templatesDir, targetDir, config);
 
     // 12. Swagger Config
-    await renderSwaggerConfig(targetDir, config);
+    await renderSwaggerConfig(templatesDir, targetDir, config);
 
     // 13. Professional Config & Tests
     await renderProfessionalConfig(templatesDir, targetDir, language);

package/lib/modules/app-setup.js

@@ -63,24 +63,34 @@ export const renderDynamicComponents = async (templatePath, targetDir, config) =
     }
 };
 
-export const renderSwaggerConfig = async (targetDir, config) => {
-    const { communication } = config;
+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)
-    // This path is common for both MVC and Clean Arch TS templates based on current structure
     // Check for Swagger config template (typically in src/config/swagger.ts.ejs)
     const swaggerTsTemplate = path.join(targetDir, 'src', 'config', 'swagger.ts.ejs');
     
     // Ensure config directory exists
-    await fs.ensureDir(path.join(targetDir, 'src', 'config'));
+    let configDir = path.join(targetDir, 'src', 'config');
+    if (architecture === 'Clean Architecture' && language === 'JavaScript') {
+        configDir = path.join(targetDir, 'src', 'infrastructure', 'webserver');
+    }
+    await fs.ensureDir(configDir);
 
-    if (await fs.pathExists(swaggerTsTemplate)) {
-        // Render if REST APIs
-        if (communication === 'REST APIs') {
+    if (communication === 'REST APIs') {
+        const swaggerYmlTemplateSource = path.join(templatesDir, 'common', 'swagger.yml.ejs');
+        if (await fs.pathExists(swaggerYmlTemplateSource)) {
+            const ymlContent = ejs.render(await fs.readFile(swaggerYmlTemplateSource, 'utf-8'), { projectName });
+            await fs.writeFile(path.join(configDir, 'swagger.yml'), ymlContent);
+        }
+
+        if (await fs.pathExists(swaggerTsTemplate)) {
             const content = ejs.render(await fs.readFile(swaggerTsTemplate, 'utf-8'), { communication });
             await fs.writeFile(path.join(targetDir, 'src', 'config', 'swagger.ts'), content);
         }
-        // Always remove the template after processing or if not needed
+    }
+    
+    // Always remove the template after processing or if not needed
+    if (await fs.pathExists(swaggerTsTemplate)) {
         await fs.remove(swaggerTsTemplate);
     }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodejs-quickstart-structure",
-  "version": "1.9.2",
+  "version": "1.9.4",
   "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/infrastructure/webserver/swagger.js

@@ -1,23 +1,6 @@
-const swaggerJsdoc = require('swagger-jsdoc');
+const path = require('path');
+const YAML = require('yamljs');
 
-const options = {
-  definition: {
-    openapi: '3.0.0',
-    info: {
-      title: 'NodeJS API Service',
-      version: '1.0.0',
-      description: 'API documentation for the NodeJS Service',
-    },
-    servers: [
-      {
-        url: process.env.SERVER_URL || `http://localhost:${process.env.PORT || 3000}`,
-        description: 'Server',
-      },
-    ],
-  },
-  apis: ['./src/interfaces/routes/*.js'], // Path to the API docs
-};
+const swaggerDocument = YAML.load(path.join(__dirname, 'swagger.yml'));
 
-const specs = swaggerJsdoc(options);
-
-module.exports = specs;
+module.exports = swaggerDocument;

package/templates/clean-architecture/js/src/interfaces/routes/api.js

@@ -2,75 +2,8 @@ const express = require('express');
 const router = express.Router();
 const UserController = require('../controllers/userController');
 
-// Should inject dependencies here in a real app
 const userController = new UserController();
 
-/**
- * @swagger
- * components:
- *   schemas:
- *     User:
- *       type: object
- *       required:
- *         - name
- *         - email
- *       properties:
- *         id:
- *           type: integer
- *           description: The auto-generated id of the user
- *         name:
- *           type: string
- *           description: The name of the user
- *         email:
- *           type: string
- *           description: The email of the user
- *       example:
- *         id: 1
- *         name: John Doe
- *         email: john@example.com
- */
-
-/**
- * @swagger
- * tags:
- *   name: Users
- *   description: The users managing API
- */
-
-/**
- * @swagger
- * /api/users:
- *   get:
- *     summary: Returns the list of all the users
- *     tags: [Users]
- *     responses:
- *       200:
- *         description: The list of the users
- *         content:
- *           application/json:
- *             schema:
- *               type: array
- *               items:
- *                 $ref: '#/components/schemas/User'
- *   post:
- *     summary: Create a new user
- *     tags: [Users]
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             $ref: '#/components/schemas/User'
- *     responses:
- *       201:
- *         description: The created user.
- *         content:
- *           application/json:
- *             schema:
- *               $ref: '#/components/schemas/User'
- *       500:
- *         description: Some server error
- */
 router.post('/users', (req, res) => userController.createUser(req, res));
 router.get('/users', (req, res) => userController.getUsers(req, res));
 

package/templates/clean-architecture/ts/src/config/swagger.ts.ejs

@@ -1,23 +1,6 @@
-<% if (communication === 'REST APIs') { %>import swaggerJsdoc from 'swagger-jsdoc';
+<% if (communication === 'REST APIs') { %>import path from 'path';
+import YAML from 'yamljs';
 
-const options = {
-  definition: {
-    openapi: '3.0.0',
-    info: {
-      title: 'NodeJS API Service',
-      version: '1.0.0',
-      description: 'API documentation for the NodeJS Service',
-    },
-    servers: [
-      {
-        url: process.env.SERVER_URL || `http://localhost:${process.env.PORT || 3000}`,
-        description: 'Server',
-      },
-    ],
-  },
-  apis: ['./src/interfaces/routes/*.ts', './dist/interfaces/routes/*.js'], // Path to the API docs
-};
+const swaggerDocument = YAML.load(path.join(__dirname, 'swagger.yml'));
 
-const specs = swaggerJsdoc(options);
-
-export default specs;<% } %>
+export default swaggerDocument;<% } %>

package/templates/clean-architecture/ts/src/interfaces/routes/userRoutes.ts

@@ -4,72 +4,6 @@ import { UserController } from '@/interfaces/controllers/userController';
 const router = Router();
 const userController = new UserController();
 
-/**
- * @swagger
- * components:
- *   schemas:
- *     User:
- *       type: object
- *       required:
- *         - name
- *         - email
- *       properties:
- *         id:
- *           type: integer
- *           description: The auto-generated id of the user
- *         name:
- *           type: string
- *           description: The name of the user
- *         email:
- *           type: string
- *           description: The email of the user
- *       example:
- *         id: 1
- *         name: John Doe
- *         email: john@example.com
- */
-
-/**
- * @swagger
- * tags:
- *   name: Users
- *   description: The users managing API
- */
-
-/**
- * @swagger
- * /api/users:
- *   get:
- *     summary: Returns the list of all the users
- *     tags: [Users]
- *     responses:
- *       200:
- *         description: The list of the users
- *         content:
- *           application/json:
- *             schema:
- *               type: array
- *               items:
- *                 $ref: '#/components/schemas/User'
- *   post:
- *     summary: Create a new user
- *     tags: [Users]
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             $ref: '#/components/schemas/User'
- *     responses:
- *       201:
- *         description: The created user.
- *         content:
- *           application/json:
- *             schema:
- *               $ref: '#/components/schemas/User'
- *       500:
- *         description: Some server error
- */
 router.post('/', (req: Request, res: Response) => userController.createUser(req, res));
 router.get('/', (req: Request, res: Response) => userController.getUsers(req, res));
 

package/templates/common/Dockerfile

@@ -1,7 +1,7 @@
 # ==========================================
 # Stage 1: Builder
 # ==========================================
-FROM node:18-alpine AS builder
+FROM node:22-alpine AS builder
 
 WORKDIR /app
 
@@ -19,7 +19,7 @@ COPY . .
 # ==========================================
 # Stage 2: Production
 # ==========================================
-FROM node:18-alpine AS production
+FROM node:22-alpine AS production
 
 WORKDIR /app
 

package/templates/common/package.json.ejs

@@ -6,7 +6,7 @@
   "scripts": {
     "start": "<% if (language === 'TypeScript') { %>node dist/index.js<% } else { %>node src/index.js<% } %>",
     "dev": "<% if (language === 'TypeScript') { %>nodemon --exec ts-node -r tsconfig-paths/register src/index.ts<% } else { %>nodemon src/index.js<% } %>"<% if (language === 'TypeScript') { %>,
-    "build": "rimraf dist && tsc && tsc-alias<% if (viewEngine && viewEngine !== 'None') { %> && cpx \"src/views/**/*\" dist/views<% } %>"<% } %>,
+    "build": "rimraf dist && tsc && tsc-alias<% if (viewEngine && viewEngine !== 'None') { %> && cpx \"src/views/**/*\" dist/views<% } %><% if (communication === 'REST APIs') { %> && cpx \"src/**/*.yml\" dist/<% } %>"<% } %>,
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
@@ -48,7 +48,7 @@
     "winston-daily-rotate-file": "^5.0.0",
     "morgan": "^1.10.0"<% if (communication === 'REST APIs') { %>,
     "swagger-ui-express": "^5.0.0",
-    "swagger-jsdoc": "^6.2.8"<% } %>
+    "yamljs": "^0.3.0"<% } %>
   },
   "devDependencies": {
     "nodemon": "^3.0.2"<% if (language === 'TypeScript') { %>,
@@ -68,7 +68,7 @@
     "@types/sequelize": "^4.28.19",
 <%_ } -%>
     "@types/morgan": "^1.9.9",
-    "rimraf": "^6.0.1"<% if (viewEngine && viewEngine !== 'None') { %>,
+    "rimraf": "^6.0.1"<% if ((viewEngine && viewEngine !== 'None') || communication === 'REST APIs') { %>,
     "cpx2": "^8.0.0"<% } %><% } %>,
     "eslint": "^9.20.1",
     "@eslint/js": "^9.20.0",
@@ -79,7 +79,7 @@
     "lint-staged": "^15.4.3"<% if (language === 'TypeScript') { %>,
     "typescript-eslint": "^8.24.1",
 <% if (communication === 'REST APIs') { %>    "@types/swagger-ui-express": "^4.1.6",
-    "@types/swagger-jsdoc": "^6.0.4",<% } -%>
+    "@types/yamljs": "^0.2.34",<% } %>
     "jest": "^29.7.0",
     "ts-jest": "^29.2.5",
     "@types/jest": "^29.5.14",

package/templates/common/swagger.yml.ejs

@@ -0,0 +1,66 @@
+openapi: 3.0.0
+info:
+  title: <%= projectName %> API
+  version: 1.0.0
+  description: API documentation for <%= projectName %>
+servers:
+  - url: http://localhost:3000
+    description: Local Server
+components:
+  schemas:
+    User:
+      type: object
+      required:
+        - name
+        - email
+      properties:
+        id:
+          type: integer
+          description: The auto-generated id of the user
+        name:
+          type: string
+          description: The name of the user
+        email:
+          type: string
+          description: The email of the user
+      example:
+        id: 1
+        name: John Doe
+        email: john@example.com
+tags:
+  - name: Users
+    description: The users managing API
+paths:
+  /api/users:
+    get:
+      summary: Returns the list of all the users
+      tags:
+        - Users
+      responses:
+        '200':
+          description: The list of the users
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+    post:
+      summary: Create a new user
+      tags:
+        - Users
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/User'
+      responses:
+        '201':
+          description: The created user.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        '500':
+          description: Some server error

package/templates/mvc/js/src/config/swagger.js

@@ -1,23 +1,6 @@
-const swaggerJsdoc = require('swagger-jsdoc');
+const path = require('path');
+const YAML = require('yamljs');
 
-const options = {
-  definition: {
-    openapi: '3.0.0',
-    info: {
-      title: 'NodeJS API Service',
-      version: '1.0.0',
-      description: 'API documentation for the NodeJS Service',
-    },
-    servers: [
-      {
-        url: process.env.SERVER_URL || `http://localhost:${process.env.PORT || 3000}`,
-        description: 'Server',
-      },
-    ],
-  },
-  apis: ['./src/routes/*.js'], // Path to the API docs
-};
+const swaggerDocument = YAML.load(path.join(__dirname, 'swagger.yml'));
 
-const specs = swaggerJsdoc(options);
-
-module.exports = specs;
+module.exports = swaggerDocument;

package/templates/mvc/js/src/routes/api.js

@@ -2,72 +2,6 @@ const express = require('express');
 const router = express.Router();
 const userController = require('../controllers/userController');
 
-/**
- * @swagger
- * components:
- *   schemas:
- *     User:
- *       type: object
- *       required:
- *         - name
- *         - email
- *       properties:
- *         id:
- *           type: integer
- *           description: The auto-generated id of the user
- *         name:
- *           type: string
- *           description: The name of the user
- *         email:
- *           type: string
- *           description: The email of the user
- *       example:
- *         id: 1
- *         name: John Doe
- *         email: john@example.com
- */
-
-/**
- * @swagger
- * tags:
- *   name: Users
- *   description: The users managing API
- */
-
-/**
- * @swagger
- * /api/users:
- *   get:
- *     summary: Returns the list of all the users
- *     tags: [Users]
- *     responses:
- *       200:
- *         description: The list of the users
- *         content:
- *           application/json:
- *             schema:
- *               type: array
- *               items:
- *                 $ref: '#/components/schemas/User'
- *   post:
- *     summary: Create a new user
- *     tags: [Users]
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             $ref: '#/components/schemas/User'
- *     responses:
- *       201:
- *         description: The created user.
- *         content:
- *           application/json:
- *             schema:
- *               $ref: '#/components/schemas/User'
- *       500:
- *         description: Some server error
- */
 router.get('/users', userController.getUsers);
 router.post('/users', userController.createUser);
 

package/templates/mvc/ts/src/config/swagger.ts.ejs

@@ -1,23 +1,6 @@
-<% if (communication === 'REST APIs') { %>import swaggerJsdoc from 'swagger-jsdoc';
+<% if (communication === 'REST APIs') { %>import path from 'path';
+import YAML from 'yamljs';
 
-const options = {
-  definition: {
-    openapi: '3.0.0',
-    info: {
-      title: 'NodeJS API Service',
-      version: '1.0.0',
-      description: 'API documentation for the NodeJS Service',
-    },
-    servers: [
-      {
-        url: process.env.SERVER_URL || `http://localhost:${process.env.PORT || 3000}`,
-        description: 'Server',
-      },
-    ],
-  },
-  apis: ['./src/routes/*.ts', './dist/routes/*.js'], // Path to the API docs
-};
+const swaggerDocument = YAML.load(path.join(__dirname, 'swagger.yml'));
 
-const specs = swaggerJsdoc(options);
-
-export default specs;<% } %>
+export default swaggerDocument;<% } %>

package/templates/mvc/ts/src/routes/api.ts

@@ -4,72 +4,6 @@ import { UserController } from '@/controllers/userController';
 const router = Router();
 const userController = new UserController();
 
-/**
- * @swagger
- * components:
- *   schemas:
- *     User:
- *       type: object
- *       required:
- *         - name
- *         - email
- *       properties:
- *         id:
- *           type: integer
- *           description: The auto-generated id of the user
- *         name:
- *           type: string
- *           description: The name of the user
- *         email:
- *           type: string
- *           description: The email of the user
- *       example:
- *         id: 1
- *         name: John Doe
- *         email: john@example.com
- */
-
-/**
- * @swagger
- * tags:
- *   name: Users
- *   description: The users managing API
- */
-
-/**
- * @swagger
- * /api/users:
- *   get:
- *     summary: Returns the list of all the users
- *     tags: [Users]
- *     responses:
- *       200:
- *         description: The list of the users
- *         content:
- *           application/json:
- *             schema:
- *               type: array
- *               items:
- *                 $ref: '#/components/schemas/User'
- *   post:
- *     summary: Create a new user
- *     tags: [Users]
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             $ref: '#/components/schemas/User'
- *     responses:
- *       201:
- *         description: The created user.
- *         content:
- *           application/json:
- *             schema:
- *               $ref: '#/components/schemas/User'
- *       500:
- *         description: Some server error
- */
 router.get('/users', (req: Request, res: Response) => userController.getUsers(req, res));
 router.post('/users', (req: Request, res: Response) => userController.createUser(req, res));