nodejs-quickstart-structure 1.1.6

package/templates/common/Dockerfile

@@ -0,0 +1,49 @@
+# ==========================================
+# Stage 1: Builder
+# ==========================================
+FROM node:18-alpine AS builder
+
+WORKDIR /app
+
+COPY package*.json ./
+COPY tsconfig*.json ./
+
+# Install ALL dependencies (including devDeps for build)
+RUN npm ci
+
+COPY . .
+
+# Build for production
+<% if (language === 'TypeScript') { %>RUN npm run build<% } %>
+
+# ==========================================
+# Stage 2: Production
+# ==========================================
+FROM node:18-alpine AS production
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+
+COPY package*.json ./
+
+# Install ONLY production dependencies
+RUN npm ci --only=production --ignore-scripts
+
+# Copy built artifacts from builder
+<% if (language === 'TypeScript') { %>
+COPY --from=builder /app/dist ./dist
+<% } else { %>
+COPY --from=builder /app/src ./src
+<% } %>
+
+# Copy other necessary files (like views if MVC)
+<% if (viewEngine && viewEngine !== 'None') { %>
+COPY --from=builder /app/src/views ./dist/views
+<% } %>
+
+EXPOSE 3000
+
+USER node
+
+CMD ["npm", "start"]

package/templates/common/README.md.ejs

@@ -0,0 +1,87 @@
+# <%= projectName %>
+
+![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)
+![License](https://img.shields.io/badge/License-ISC-blue.svg)
+<% if (language === 'TypeScript') { %>![TypeScript](https://img.shields.io/badge/Language-TypeScript-blue.svg)<% } else { %>![JavaScript](https://img.shields.io/badge/Language-JavaScript-yellow.svg)<% } %>
+
+A production-ready Node.js microservice generated with **<%= architecture %>** and **<%= database %>**.
+This project comes pre-configured with industry-standard tooling for **Code Quality**, **Testing**, and **Security**.
+
+## 🚀 Key Features
+
+-   **Architecture**: <%= architecture %> (<% if (architecture === 'Clean Architecture') { %>Domain, UseCases, Infrastructure<% } else { %>MVC Pattern<% } %>).
+-   **Database**: <%= database %> with **Flyway** migrations.
+-   **Security**: Helmet, CORS, Rate Limiting, HPP.
+-   **Quality**: Eslint, Prettier, Husky, Lint-Staged.
+-   **Testing**: Jest (Unit & Integration).
+-   **DevOps**: Multi-stage Docker build, CI/CD ready.
+
+## 🛠️ Getting Started
+
+### 1. Prerequisites
+-   Node.js (v18+)
+-   Docker & Docker Compose
+
+### 2. Quick Start
+```bash
+# Install dependencies
+npm install
+
+# Setup Git Hooks (Husky)
+npm run prepare
+
+# Start Infrastructure (DB, etc.)
+docker-compose up -d
+
+# Run Development Server
+npm run dev
+```
+
+### 3. Development Standards
+Ensure your code meets quality standards before committing:
+
+```bash
+# Run Linter
+npm run lint
+
+# Run Tests
+npm test
+
+# Format Code
+npm run format
+```
+
+## 📂 Project Structure
+
+The project follows **<%= architecture %>** principles.
+<% if (communication === 'Kafka') { -%>
+Microservices communication handled via **Kafka**.
+<% } else { -%>
+API is exposed via **REST**.
+A Swagger UI for API documentation is available at:
+- **URL**: `http://localhost:3000/api-docs` (Dynamic based on PORT)
+<% } -%>
+
+## 📝 Logging
+This project uses **Winston** for structured logging.
+- **Development**: Logs are printed to the console.
+- **Production**: Logs are saved to files:
+  - `error.log`: Only error level logs.
+  - `combined.log`: All logs.
+
+## 🐳 Docker Deployment
+This project uses a **Multi-Stage Dockerfile** for optimized production images.
+
+```bash
+# Build Production Image
+docker build -t <%= projectName %> .
+
+# Run Container
+docker run -p 3000:3000 -e DATABASE_URL=... <%= projectName %>
+```
+
+## 🔒 Security Features
+-   **Helmet**: Sets secure HTTP headers.
+-   **CORS**: Configured for cross-origin requests.
+-   **Rate Limiting**: Protects against DDoS / Brute-force.
+-   **HPP**: Prevents HTTP Parameter Pollution attacks.

package/templates/common/_gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+.env
+.DS_Store
+coverage

package/templates/common/database/js/database.js.ejs

@@ -0,0 +1,20 @@
+const { Sequelize } = require('sequelize');
+require('dotenv').config();
+
+// Determine dialect
+<% if (database === 'MySQL') { %>const dialect = 'mysql';<% } -%>
+<% if (database === 'PostgreSQL') { %>const dialect = 'postgres';<% } -%>
+
+const sequelize = new Sequelize(
+  process.env.DB_NAME || '<%= dbName %>',
+  process.env.DB_USER || '<% if (database === 'MySQL') { %>root<% } else { %>postgres<% } %>',
+  process.env.DB_PASSWORD || '<% if (database === 'MySQL') { %>root<% } else { %>postgres<% } %>',
+  {
+    host: process.env.DB_HOST || '127.0.0.1',
+    dialect: dialect,
+    logging: false,
+    port: parseInt(process.env.DB_PORT || '<% if (database === 'MySQL') { %>3306<% } else { %>5432<% } %>')
+  }
+);
+
+module.exports = sequelize;

package/templates/common/database/js/models/User.js.ejs

@@ -0,0 +1,30 @@
+const { DataTypes, Model } = require('sequelize');
+<% if (architecture === 'MVC') { %>const sequelize = require('../config/database');<% } else { %>const sequelize = require('../database');<% } %>
+
+class User extends Model {}
+
+User.init(
+  {
+    id: {
+      type: DataTypes.INTEGER,
+      autoIncrement: true,
+      primaryKey: true,
+    },
+    name: {
+      type: DataTypes.STRING,
+      allowNull: false,
+    },
+    email: {
+      type: DataTypes.STRING,
+      allowNull: false,
+      unique: true,
+    },
+  },
+  {
+    sequelize,
+    tableName: 'users',
+    underscored: true,
+  }
+);
+
+module.exports = User;

package/templates/common/database/ts/database.ts.ejs

@@ -0,0 +1,22 @@
+import { Sequelize } from 'sequelize';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+// Determine dialect
+<% if (database === 'MySQL') { %>const dialect = 'mysql';<% } -%>
+<% if (database === 'PostgreSQL') { %>const dialect = 'postgres';<% } -%>
+
+const sequelize = new Sequelize(
+  process.env.DB_NAME || '<%= dbName %>',
+  process.env.DB_USER || '<% if (database === 'MySQL') { %>root<% } else { %>postgres<% } %>',
+  process.env.DB_PASSWORD || '<% if (database === 'MySQL') { %>root<% } else { %>postgres<% } %>',
+  {
+    host: process.env.DB_HOST || '127.0.0.1',
+    dialect: dialect,
+    logging: false,
+    port: parseInt(process.env.DB_PORT || '<% if (database === 'MySQL') { %>3306<% } else { %>5432<% } %>')
+  }
+);
+
+export default sequelize;

package/templates/common/database/ts/models/User.ts.ejs

@@ -0,0 +1,34 @@
+import { DataTypes, Model } from 'sequelize';
+<% if (architecture === 'MVC') { %>import sequelize from '../config/database';<% } else { %>import sequelize from '../database';<% } %>
+
+class User extends Model {
+  public id!: number;
+  public name!: string;
+  public email!: string;
+}
+
+User.init(
+  {
+    id: {
+      type: DataTypes.INTEGER,
+      autoIncrement: true,
+      primaryKey: true,
+    },
+    name: {
+      type: DataTypes.STRING,
+      allowNull: false,
+    },
+    email: {
+      type: DataTypes.STRING,
+      allowNull: false,
+      unique: true,
+    },
+  },
+  {
+    sequelize,
+    tableName: 'users',
+    underscored: true,
+  }
+);
+
+export default User;

package/templates/common/docker-compose.yml.ejs

@@ -0,0 +1,93 @@
+version: '3.8'
+
+services:
+  app:
+    build: .
+    ports:
+      - "${PORT:-3000}:3000"
+    depends_on:
+      - db
+<% if (communication === 'Kafka') { %>      - kafka
+<% } -%>
+<% if (communication === 'Kafka') { %>    environment:
+      - KAFKA_BROKER=kafka:29092
+      - KAFKAJS_NO_PARTITIONER_WARNING=1
+      - PORT=3000
+      - DB_HOST=db
+<% if (database === 'MySQL') { %>      - DB_USER=root
+      - DB_PASSWORD=root
+      - DB_NAME=<%= dbName %>
+<% } %><% if (database === 'PostgreSQL') { %>      - DB_USER=postgres
+      - DB_PASSWORD=postgres
+      - DB_NAME=<%= dbName %>
+<% } -%>
+<% } else { %>
+    environment:
+      - PORT=3000
+      - DB_HOST=db
+<% if (database === 'MySQL') { %>      - DB_USER=root
+      - DB_PASSWORD=root
+      - DB_NAME=<%= dbName %>
+<% } %><% if (database === 'PostgreSQL') { %>      - DB_USER=postgres
+      - DB_PASSWORD=postgres
+      - DB_NAME=<%= dbName %>
+<% } -%>
+<% } %>
+  db:
+<% if (database === 'MySQL') { %>    image: mysql:8.0
+    command: --default-authentication-plugin=mysql_native_password
+    restart: always
+    environment:
+      MYSQL_ROOT_PASSWORD: root
+      MYSQL_DATABASE: <%= dbName %>
+    ports:
+      - "${DB_PORT:-3306}:3306"
+<% } %><% if (database === 'PostgreSQL') { %>    image: postgres:15
+    restart: always
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: <%= dbName %>
+    ports:
+      - "${DB_PORT:-5432}:5432"
+<% } %>    volumes:
+      - <%= database.toLowerCase() %>_data:/var/lib/<% if (database === 'MySQL') { %>mysql<% } else { %>postgresql/data<% } %>
+
+  flyway:
+    image: flyway/flyway
+    command: -connectRetries=60 migrate
+    volumes:
+      - ./flyway/sql:/flyway/sql
+    environment:
+<% if (database === 'MySQL') { %>      FLYWAY_URL: jdbc:mysql://db:3306/<%= dbName %>
+      FLYWAY_USER: root
+      FLYWAY_PASSWORD: root
+<% } %><% if (database === 'PostgreSQL') { %>      FLYWAY_URL: jdbc:postgresql://db:5432/<%= dbName %>
+      FLYWAY_USER: postgres
+      FLYWAY_PASSWORD: postgres
+<% } %>    depends_on:
+      - db
+<% if (communication === 'Kafka') { %>  zookeeper:
+    image: confluentinc/cp-zookeeper:7.4.0
+    environment:
+      ZOOKEEPER_CLIENT_PORT: 2181
+      ZOOKEEPER_TICK_TIME: 2000
+    ports:
+      - "${ZOOKEEPER_PORT:-2181}:2181"
+
+  kafka:
+    image: confluentinc/cp-kafka:7.4.0
+    depends_on:
+      - zookeeper
+    ports:
+      - "${KAFKA_PORT:-9092}:9092"
+    environment:
+      KAFKA_BROKER_ID: 1
+      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
+      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:29092,PLAINTEXT_HOST://localhost:9092
+      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
+      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
+      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
+<% } -%>
+volumes:
+  <%= database.toLowerCase() %>_data:

package/templates/common/jest.config.js.ejs

@@ -0,0 +1,11 @@
+module.exports = {
+  testEnvironment: 'node',
+  coverageDirectory: 'coverage',
+  collectCoverageFrom: ['src/**/*.{js,ts}'],
+  testMatch: ['**/*.test.ts', '**/*.test.js'],
+  <% if (language === 'TypeScript') { %>preset: 'ts-jest',<% } %>
+  coveragePathIgnorePatterns: [
+    "/node_modules/",
+    "/dist/"
+  ]
+};

package/templates/common/kafka/js/config/kafka.js

@@ -0,0 +1,8 @@
+const { Kafka } = require('kafkajs');
+
+const kafka = new Kafka({
+    clientId: 'nodejs-service',
+    brokers: [process.env.KAFKA_BROKER || 'localhost:9092']
+});
+
+module.exports = { kafka };

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

@@ -0,0 +1,29 @@
+const { kafka } = require('../config/kafka');
+
+const producer = kafka.producer();
+const consumer = kafka.consumer({ groupId: 'test-group' });
+
+const connectKafka = async () => {
+    await producer.connect();
+    await consumer.connect();
+    await consumer.subscribe({ topic: 'test-topic', fromBeginning: true });
+
+    await consumer.run({
+        eachMessage: async ({ topic, partition, message }) => {
+            console.log({
+                value: message.value.toString(),
+            });
+        },
+    });
+};
+
+const sendMessage = async (topic, message) => {
+    await producer.send({
+        topic,
+        messages: [
+            { value: message },
+        ],
+    });
+};
+
+module.exports = { connectKafka, sendMessage };

package/templates/common/kafka/ts/config/kafka.ts

@@ -0,0 +1,6 @@
+import { Kafka } from 'kafkajs';
+
+export const kafka = new Kafka({
+    clientId: 'nodejs-service',
+    brokers: [process.env.KAFKA_BROKER || 'localhost:9092']
+});

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

@@ -0,0 +1,36 @@
+import { kafka } from '../config/kafka';
+import { EachMessagePayload, Producer, Consumer } from 'kafkajs';
+
+export class KafkaService {
+    private producer: Producer;
+    private consumer: Consumer;
+
+    constructor() {
+        this.producer = kafka.producer();
+        this.consumer = kafka.consumer({ groupId: 'test-group' });
+    }
+
+    async connect() {
+        await this.producer.connect();
+        await this.consumer.connect();
+        await this.consumer.subscribe({ topic: 'test-topic', fromBeginning: true });
+
+        await this.consumer.run({
+            eachMessage: async ({ topic, partition, message }: EachMessagePayload) => {
+                console.log({
+                    value: message.value?.toString(),
+                });
+            },
+        });
+    }
+
+    async sendMessage(topic: string, message: string) {
+        await this.producer.send({
+            topic,
+            messages: [
+                { value: message },
+            ],
+        });
+    }
+}
+

package/templates/common/package.json.ejs

@@ -0,0 +1,78 @@
+{
+  "name": "<%= projectName %>",
+  "version": "1.0.0",
+  "description": "Generated by nodejs-quickstart",
+  "main": "<% if (language === 'TypeScript') { %>dist/index.js<% } else { %>src/index.js<% } %>",
+  "scripts": {
+    "start": "<% if (language === 'TypeScript') { %>node dist/index.js<% } else { %>node src/index.js<% } %>",
+    "dev": "<% if (language === 'TypeScript') { %>nodemon --exec ts-node src/index.ts<% } else { %>nodemon src/index.js<% } %>"<% if (language === 'TypeScript') { %>,
+    "build": "rimraf dist && tsc<% if (viewEngine && viewEngine !== 'None') { %> && copyfiles -u 1 \"src/views/**/*\" dist/<% } %>"<% } %>,
+    "lint": "eslint . --ext .ts,.js",
+    "lint:fix": "eslint . --ext .ts,.js --fix",
+    "format": "prettier --write .",
+    "prepare": "husky install",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "dotenv": "^16.3.1",
+<% if (database === 'MySQL') { %>    "mysql2": "^3.6.5",
+<% } -%>
+<% if (database === 'PostgreSQL') { %>    "pg": "^8.11.3",
+<% } -%>
+    "sequelize": "^6.35.2",
+<% if (communication === 'Kafka') { %>    "kafkajs": "^2.2.4",
+<% } -%>
+<% if (viewEngine === 'EJS') { %>    "ejs": "^3.1.9",
+<% } -%>
+<% if (viewEngine === 'Pug') { %>    "pug": "^3.0.2",
+<% } -%>
+    "cors": "^2.8.5",
+    "helmet": "^7.1.0",
+    "hpp": "^0.2.3",
+    "express-rate-limit": "^7.1.5",
+    "winston": "^3.11.0"<% if (communication === 'REST APIs') { %>,
+    "swagger-ui-express": "^5.0.0",
+    "swagger-jsdoc": "^6.2.8"
+<% } %>
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.2"<% if (language === 'TypeScript') { %>,
+    "typescript": "^5.3.3",
+    "ts-node": "^10.9.2",
+    "@types/node": "^20.10.5",
+    "@types/express": "^4.17.21",
+    "@types/cors": "^2.8.17",
+    "@types/dotenv": "^8.2.0",
+    "@types/hpp": "^0.2.3",
+<% if (database === 'PostgreSQL') { %>    "@types/pg": "^8.10.9",
+<% } -%>
+    "@types/sequelize": "^4.28.19",
+    "rimraf": "^5.0.5"<% if (viewEngine && viewEngine !== 'None') { %>,
+    "copyfiles": "^2.4.1"<% } %><% } %>,
+    "eslint": "^8.56.0",
+    "prettier": "^3.1.1",
+    "eslint-config-prettier": "^9.1.0",
+    "husky": "^8.0.3",
+    "lint-staged": "^15.2.0"<% if (language === 'TypeScript') { %>,
+    "@typescript-eslint/eslint-plugin": "^6.18.1",
+    "@typescript-eslint/parser": "^6.18.1",
+<% if (communication === 'REST APIs') { %>    "@types/swagger-ui-express": "^4.1.6",
+    "@types/swagger-jsdoc": "^6.0.4",<% } -%>
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "@types/jest": "^29.5.11",
+    "supertest": "^6.3.3",
+    "@types/supertest": "^6.0.2"<% } else { %>,
+    "jest": "^29.7.0",
+    "supertest": "^6.3.3"<% } %>
+  },
+  "lint-staged": {
+    "*.{js,ts}": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  }
+}

package/templates/common/tsconfig.json

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

package/templates/common/views/ejs/index.ejs

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title><%= projectName %></title>
+    <style>
+        body { font-family: sans-serif; padding: 20px; }
+        h1 { color: #333; }
+        .status { margin-top: 20px; padding: 10px; background: #e0f7fa; border-left: 5px solid #00acc1; }
+    </style>
+</head>
+<body>
+    <h1>Welcome to <%= projectName %></h1>
+    <p>Architecture: <strong><%= architecture %></strong></p>
+    <p>Database: <strong><%= database %></strong></p>
+    
+    <% if (communication === 'Kafka') { %>
+    <div class="status">
+        <h3>Kafka Status</h3>
+        <p>Connected to Kafka Broker.</p>
+        <p>Check console for messages.</p>
+    </div>
+    <% } else { %>
+    <div class="status">
+        <h3>API Status</h3>
+        <p>REST API is active.</p>
+    </div>
+    <% } %>
+</body>
+</html>

package/templates/common/views/pug/index.pug

@@ -0,0 +1,26 @@
+doctype html
+html(lang="en")
+  head
+    meta(charset="UTF-8")
+    meta(name="viewport", content="width=device-width, initial-scale=1.0")
+    title= projectName
+    style.
+      body { font-family: sans-serif; padding: 20px; }
+      h1 { color: #333; }
+      .status { margin-top: 20px; padding: 10px; background: #e0f7fa; border-left: 5px solid #00acc1; }
+  body
+    h1 Welcome to #{projectName}
+    p Architecture: 
+      strong #{architecture}
+    p Database: 
+      strong #{database}
+
+    if communication === 'Kafka'
+      .status
+        h3 Kafka Status
+        p Connected to Kafka Broker.
+        p Check console for messages.
+    else
+      .status
+        h3 API Status
+        p REST API is active.

package/templates/db/mysql/V1__Initial_Setup.sql

@@ -0,0 +1,9 @@
+CREATE TABLE users (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    name VARCHAR(255) NOT NULL,
+    email VARCHAR(255) NOT NULL UNIQUE,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+
+INSERT INTO users (name, email) VALUES ('Admin User', 'admin@example.com');

package/templates/db/postgres/V1__Initial_Setup.sql

@@ -0,0 +1,9 @@
+CREATE TABLE users (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(255) NOT NULL,
+    email VARCHAR(255) NOT NULL UNIQUE,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+INSERT INTO users (name, email) VALUES ('Admin User', 'admin@example.com');

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

@@ -0,0 +1,12 @@
+// Database configuration placeholder
+// Use environment variables from .env depending on your DB choice (MySQL/Postgres)
+require('dotenv').config();
+
+const dbConfig = {
+    host: process.env.DB_HOST,
+    user: process.env.DB_USER,
+    password: process.env.DB_PASSWORD,
+    database: process.env.DB_NAME
+};
+
+module.exports = dbConfig;

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

@@ -0,0 +1,23 @@
+const swaggerJsdoc = require('swagger-jsdoc');
+
+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 specs = swaggerJsdoc(options);
+
+module.exports = specs;

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

@@ -0,0 +1,14 @@
+exports.getUsers = (req, res) => {
+    res.json([
+        { id: 1, name: 'John Doe' },
+        { id: 2, name: 'Jane Doe' }
+    ]);
+};
+
+exports.createUser = (req, res) => {
+    const { name, email } = req.body;
+    res.status(201).json({
+        message: 'User created successfully',
+        user: { name, email }
+    });
+};