express-genix 1.1.0

package/templates/core/README.md.ejs

@@ -0,0 +1,179 @@
+# <%= projectName %>
+
+A production-grade Express.js boilerplate<% if (hasDatabase) { %> with JWT authentication, <%= db %> support<% } %>, rate-limiting, security middleware, logging, API documentation, testing, and more.
+
+## Features
+
+<% if (hasDatabase) { %>- **Authentication**: JWT-based authentication with refresh tokens
+- **Database**: <%= db === 'mongodb' ? 'MongoDB with Mongoose' : 'PostgreSQL with Sequelize' %>
+- **User Management**: Complete user registration, login, profile management<% } else { %>- **No Database**: Perfect for microservices, proxy servers, or computational APIs
+- **Example API**: CRUD operations with in-memory storage (easily replaceable)<% } %>
+- **Security**: Helmet, CORS, rate limiting
+- **Logging**: Morgan HTTP request logger with custom logging utilities
+- **API Documentation**: Swagger UI
+- **Testing**: Jest and Supertest
+- **Code Quality**: ESLint with Airbnb configuration, Prettier formatting
+- **Deployment**: Docker support with clustering
+- **Project Structure**: Clean, modular Express.js architecture
+
+## Project Structure
+
+```
+├── src/
+│   ├── config/             # Configuration files (swagger<% if (hasDatabase) { %>, database<% } %>)
+│   ├── controllers/        # Request handlers and business logic orchestration<% if (hasDatabase) { %>
+│   ├── middleware/         # Custom middleware (auth, validation, errors)<% } else { %>
+│   ├── middleware/         # Custom middleware (errors)<% } %>
+<% if (hasDatabase) { %>│   ├── models/             # Database models<% } %>
+│   ├── routes/             # API endpoint definitions
+│   ├── services/           # Business logic layer
+│   ├── utils/              # Utility functions and helpers
+│   ├── app.js              # Express app configuration
+│   └── server.js           # Server setup and clustering
+├── tests/                  # Test files
+├── .env                    # Environment variables
+├── .gitignore              # Git ignore rules
+├── package.json            # Dependencies and scripts
+└── README.md               # Project documentation
+```
+
+## Setup
+
+1. **Install Dependencies**
+   ```bash
+   npm install
+   ```
+
+2. **Environment Configuration**
+   - Copy `.env` and configure your environment variables<% if (hasDatabase) { %>
+   - Update database connection settings
+   - Change JWT secrets for production<% } %>
+
+<% if (hasDatabase) { %>3. **Database Setup**<% if (db === 'mongodb') { %>
+   - Ensure MongoDB is running locally or update MONGO_URI
+   - Database will be created automatically<% } else if (db === 'postgresql') { %>
+   - Ensure PostgreSQL is running locally
+   - Create a database matching your DATABASE_URL
+   - Run migrations if needed<% } %>
+
+4.<% } else { %>3.<% } %> **Start Development Server**
+   ```bash
+   npm run dev
+   ```
+
+<% if (hasDatabase) { %>5.<% } else { %>4.<% } %> **Production**
+   ```bash
+   npm start
+   ```
+
+## Available Scripts
+
+- `npm run dev` - Start development server with nodemon
+- `npm start` - Start production server with clustering
+- `npm test` - Run tests with coverage
+- `npm run lint` - Run ESLint
+- `npm run lint:fix` - Fix ESLint issues automatically
+- `npm run format` - Format code with Prettier
+- `npm run format:check` - Check code formatting
+
+## API Documentation
+
+Visit `http://localhost:3000/api-docs` for interactive Swagger documentation.
+
+## API Endpoints
+
+<% if (hasDatabase) { %>### Authentication
+- `POST /api/auth/register` - Register new user
+- `POST /api/auth/login` - User login
+- `POST /api/auth/refresh` - Refresh access token
+- `POST /api/auth/logout` - User logout
+
+### Users
+- `GET /api/users/profile` - Get user profile (protected)
+- `PUT /api/users/profile` - Update user profile (protected)
+- `DELETE /api/users/profile` - Delete user profile (protected)<% } else { %>### Examples
+- `GET /api/examples` - Get all examples (with pagination)
+- `GET /api/examples/:id` - Get example by ID
+- `POST /api/examples` - Create new example
+- `PUT /api/examples/:id` - Update example
+- `DELETE /api/examples/:id` - Delete example<% } %>
+
+### Health Check
+- `GET /health` - Application health status
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| NODE_ENV | Environment mode | development |
+| PORT | Server port | 3000 |<% if (hasDatabase) { %>
+| JWT_SECRET | JWT signing secret | - |
+| JWT_REFRESH_SECRET | Refresh token secret | - |
+| JWT_EXPIRE | Access token expiry | 15m |
+| JWT_REFRESH_EXPIRE | Refresh token expiry | 7d |
+| <%= db === 'mongodb' ? 'MONGO_URI' : 'DATABASE_URL' %> | Database connection | - |<% } %>
+| RATE_LIMIT_WINDOW_MS | Rate limit window | 900000 |
+| RATE_LIMIT_MAX | Max requests per window | 100 |
+
+## Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm run test
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+## Deployment
+
+### Docker
+
+1. **Build Image**
+   ```bash
+   docker build -t <%= projectName %> .
+   ```
+
+2. **Run Container**
+   ```bash
+   docker run -p 3000:3000 --env-file .env <%= projectName %>
+   ```
+
+3. **Docker Compose**
+   ```bash
+   docker-compose up
+   ```
+
+## Security Features
+
+- **Helmet**: Sets various HTTP headers for security
+- **CORS**: Configurable cross-origin resource sharing
+- **Rate Limiting**: Prevents abuse and DDoS attacks<% if (hasDatabase) { %>
+- **JWT**: Stateless authentication with refresh tokens
+- **Password Hashing**: bcrypt for secure password storage
+- **Input Validation**: Request validation middleware<% } %>
+
+<% if (!hasDatabase) { %>## Extending the Application
+
+This boilerplate is designed for APIs that don't require database persistence. You can easily:
+
+- Add database support by integrating MongoDB or PostgreSQL
+- Replace in-memory storage with external services (Redis, etc.)
+- Add authentication by integrating with OAuth providers
+- Build microservices by adding service-to-service communication
+
+<% } %>## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass
+6. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details

package/templates/core/app.js.ejs

@@ -0,0 +1,65 @@
+const express = require('express');
+const cors = require('cors');
+const helmet = require('helmet');
+const morgan = require('morgan');
+const rateLimit = require('express-rate-limit');
+const swaggerUi = require('swagger-ui-express');
+const dotenv = require('dotenv');
+
+const routes = require('./routes');
+const errorHandler = require('./middleware/errorHandler');
+const swaggerConfig = require('./config/swagger.json');
+
+// Load environment variables
+dotenv.config();
+
+const app = express();
+
+// Security middleware
+app.use(helmet());
+app.use(cors());
+
+// Logging
+app.use(morgan('dev'));
+
+// Body parsing middleware
+app.use(express.json({ limit: '10mb' }));
+app.use(express.urlencoded({ extended: true }));
+
+// Rate limiting
+const limiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100, // Limit each IP to 100 requests per windowMs
+  message: 'Too many requests from this IP, please try again later.',
+});
+app.use(limiter);
+
+// Health check endpoint
+app.get('/health', (req, res) => {
+  res.status(200).json({
+    status: 'OK',
+    timestamp: new Date().toISOString(),
+    uptime: process.uptime(),<% if (hasDatabase) { %>
+    database: '<%= db %>'<% } else { %>
+    database: 'none'<% } %>,
+  });
+});
+
+// API documentation
+app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerConfig));
+
+// API routes
+app.use('/api', routes);
+
+// 404 handler
+app.use('*', (req, res) => {
+  res.status(404).json({
+    error: 'Route not found',
+    path: req.originalUrl,
+  });
+});
+
+// Error handling middleware (should be last)
+app.use(errorHandler);
+
+module.exports = app;

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

@@ -0,0 +1,48 @@
+# templates/core/docker-compose.yml.ejs
+version: '3.8'
+
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+    env_file:
+      - .env<% if (hasDatabase) { %>
+    depends_on:
+      - <%= db === 'mongodb' ? 'mongodb' : 'postgres' %><% } %>
+    restart: unless-stopped
+    networks:
+      - app-network
+
+<% if (db === 'mongodb') { %>  mongodb:
+    image: mongo:7-jammy
+    ports:
+      - "27017:27017"
+    environment:
+      - MONGO_INITDB_DATABASE=<%= projectName %>
+    volumes:
+      - mongodb_data:/data/db
+    restart: unless-stopped
+    networks:
+      - app-network<% } else if (db === 'postgresql') { %>  postgres:
+    image: postgres:15-alpine
+    ports:
+      - "5432:5432"
+    environment:
+      - POSTGRES_DB=<%= projectName %>
+      - POSTGRES_USER=user
+      - POSTGRES_PASSWORD=password
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    restart: unless-stopped
+    networks:
+      - app-network<% } %>
+
+<% if (hasDatabase) { %>volumes:
+  <%= db === 'mongodb' ? 'mongodb_data:' : 'postgres_data:' %><% } %>
+
+networks:
+  app-network:
+    driver: bridge

package/templates/core/env.ejs

@@ -0,0 +1,20 @@
+# Server Configuration
+NODE_ENV=development
+PORT=3000<% if (hasDatabase) { %>
+
+# JWT Configuration
+JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
+JWT_REFRESH_SECRET=your-super-secret-refresh-key-change-this-in-production
+JWT_EXPIRE=15m
+JWT_REFRESH_EXPIRE=7d
+
+# Database Configuration<% if (db === 'mongodb') { %>
+MONGO_URI=mongodb://localhost:27017/<%= projectName %><% } else if (db === 'postgresql') { %>
+DATABASE_URL=postgresql://user:password@localhost:5432/<%= projectName %><% } %><% } %>
+
+# Rate Limiting
+RATE_LIMIT_WINDOW_MS=900000
+RATE_LIMIT_MAX=100
+
+# Logging
+LOG_LEVEL=info

package/templates/core/eslintrc.json.ejs

@@ -0,0 +1,20 @@
+{
+    "extends": ["airbnb-base"],
+    "env": {
+      "node": true,
+      "jest": true
+    },
+    "rules": {
+      "no-console": "off",
+      "consistent-return": "off",
+      "func-names": "off",
+      "object-shorthand": "off",
+      "no-process-exit": "off",
+      "no-param-reassign": "off",
+      "no-return-await": "off",
+      "no-underscore-dangle": "off",
+      "class-methods-use-this": "off",
+      "prefer-destructuring": ["error", { "object": true, "array": false }],
+      "no-unused-vars": ["error", { "argsIgnorePattern": "req|res|next|val" }]
+    }
+  }

package/templates/core/gitignore.ejs

@@ -0,0 +1,51 @@
+// templates/core/gitignore.ejs
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Build outputs
+dist/
+build/
+
+# Logs
+logs/
+*.log
+
+# Runtime data
+pids/
+*.pid
+*.seed
+*.pid.lock
+
+# Coverage directory used by tools like istanbul
+coverage/
+*.lcov
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Temporary files
+tmp/
+temp/

package/templates/core/healthcheck.js.ejs

@@ -0,0 +1,25 @@
+// templates/core/healthcheck.js.ejs
+const http = require('http');
+
+const options = {
+  host: 'localhost',
+  port: process.env.PORT || 3000,
+  path: '/health',
+  timeout: 2000,
+};
+
+const request = http.request(options, (res) => {
+  console.log(`STATUS: ${res.statusCode}`);
+  if (res.statusCode === 200) {
+    process.exit(0);
+  } else {
+    process.exit(1);
+  }
+});
+
+request.on('error', (err) => {
+  console.log('ERROR:', err);
+  process.exit(1);
+});
+
+request.end();

package/templates/core/index.js.ejs

@@ -0,0 +1,24 @@
+const express = require('express');<% if (hasDatabase) { %>
+  const authRoutes = require('./authRoutes');
+  const userRoutes = require('./userRoutes');<% } else { %>
+  const exampleRoutes = require('./exampleRoutes');<% } %>
+  
+  const router = express.Router();
+  
+  // Mount route modules<% if (hasDatabase) { %>
+  router.use('/auth', authRoutes);
+  router.use('/users', userRoutes);<% } else { %>
+  router.use('/examples', exampleRoutes);<% } %>
+  
+  // API root endpoint
+  router.get('/', (req, res) => {
+    res.json({
+      message: 'Welcome to the API',
+      version: '1.0.0',
+      documentation: '/api-docs',<% if (hasDatabase) { %>
+      features: ['authentication', 'user-management', '<%= db %>-database']<% } else { %>
+      features: ['rate-limiting', 'logging', 'swagger-docs']<% } %>,
+    });
+  });
+  
+  module.exports = router;

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

@@ -0,0 +1,23 @@
+
+// templates/core/jest.config.js.ejs
+module.exports = {
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src', '<rootDir>/tests'],
+  testMatch: [
+    '**/__tests__/**/*.js',
+    '**/?(*.)+(spec|test).js'
+  ],
+  collectCoverageFrom: [
+    'src/**/*.js',
+    '!src/server.js',
+    '!src/config/**',
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: [
+    'text',
+    'lcov',
+    'html'
+  ],
+  setupFilesAfterEnv: ['<rootDir>/tests/setup.js'],
+  testTimeout: 10000,
+};

package/templates/core/package.json.ejs

@@ -0,0 +1,33 @@
+{
+    "name": "<%= projectName %>",
+    "version": "1.0.0",
+    "main": "src/server.js",
+    "scripts": {
+      "start": "node src/server.js",
+      "dev": "nodemon src/server.js",
+      "test": "jest --coverage",
+      "lint": "eslint ."
+    },
+    "dependencies": {
+      "express": "^4.18.2",
+      "express-rate-limit": "^7.1.5",
+      "dotenv": "^16.3.1",
+      "cors": "^2.8.5",
+      "helmet": "^7.1.0",
+      "morgan": "^1.10.0",
+      "swagger-ui-express": "^5.0.1"<% if (hasDatabase) { %>,
+      "jsonwebtoken": "^9.0.2",
+      "bcryptjs": "^2.4.3"<% if (db === 'mongodb') { %>,
+      "mongoose": "^8.0.3"<% } else if (db === 'postgresql') { %>,
+      "pg": "^8.11.3",
+      "sequelize": "^6.35.1"<% } %><% } %>
+    },
+    "devDependencies": {
+      "nodemon": "^3.0.3",
+      "jest": "^29.7.0",
+      "supertest": "^6.3.4",
+      "eslint": "^8.56.0",
+      "eslint-config-airbnb-base": "^15.0.0",
+      "eslint-plugin-import": "^2.29.1"
+    }
+  }

package/templates/core/prettierrc.json.ejs

@@ -0,0 +1,12 @@
+{
+    "semi": true,
+    "trailingComma": "es5",
+    "singleQuote": true,
+    "printWidth": 80,
+    "tabWidth": 2,
+    "useTabs": false,
+    "bracketSpacing": true,
+    "bracketSameLine": false,
+    "arrowParens": "always",
+    "endOfLine": "lf"
+  }

package/templates/core/server.js.ejs

@@ -0,0 +1,44 @@
+const cluster = require('cluster');
+const os = require('os');
+const app = require('./app');<% if (hasDatabase) { %>
+const db = require('./config/database');<% } %>
+
+const port = process.env.PORT || 3000;
+
+const startServer = async () => {<% if (hasDatabase) { %>
+  await db.connect();<% } %>
+  
+  if (cluster.isMaster) {
+    const numCPUs = os.cpus().length;
+    console.log(`Master ${process.pid} is running`);
+    
+    // Fork workers
+    for (let i = 0; i < numCPUs; i++) {
+      cluster.fork();
+    }
+    
+    cluster.on('exit', (worker, code, signal) => {
+      console.log(`Worker ${worker.process.pid} died with code ${code} and signal ${signal}`);
+      cluster.fork();
+    });
+  } else {
+    app.listen(port, () => {
+      console.log(`Worker ${process.pid} running on http://localhost:${port}`);
+    });
+  }
+};
+
+startServer().catch(console.error);
+
+// Graceful Shutdown
+process.on('SIGTERM', async () => {
+  console.log('SIGTERM signal received: closing HTTP server');<% if (hasDatabase) { %>
+  await db.disconnect();<% } %>
+  process.exit(0);
+});
+
+process.on('SIGINT', async () => {
+  console.log('SIGINT signal received: closing HTTP server');<% if (hasDatabase) { %>
+  await db.disconnect();<% } %>
+  process.exit(0);
+});

package/templates/middleware/auth.js.ejs

@@ -0,0 +1,66 @@
+const jwt = require('jsonwebtoken');
+const { AppError } = require('../utils/errors');
+
+const jwtSecret = process.env.JWT_SECRET || 'your-secret-key';
+
+/**
+ * Middleware to authenticate JWT tokens
+ */
+const authenticateToken = (req, res, next) => {
+  const authHeader = req.headers['authorization'];
+  const token = authHeader && authHeader.split(' ')[1];
+  
+  if (!token) {
+    return next(new AppError('Access token is required', 401));
+  }
+  
+  jwt.verify(token, jwtSecret, (err, decoded) => {
+    if (err) {
+      return next(new AppError('Invalid or expired token', 403));
+    }
+    
+    req.user = decoded;
+    next();
+  });
+};
+
+/**
+ * Optional authentication middleware - doesn't require token
+ */
+const optionalAuth = (req, res, next) => {
+  const authHeader = req.headers['authorization'];
+  const token = authHeader && authHeader.split(' ')[1];
+  
+  if (token) {
+    jwt.verify(token, jwtSecret, (err, decoded) => {
+      if (!err) {
+        req.user = decoded;
+      }
+    });
+  }
+  
+  next();
+};
+
+/**
+ * Middleware to check if user has specific role
+ */
+const requireRole = (role) => {
+  return (req, res, next) => {
+    if (!req.user) {
+      return next(new AppError('Authentication required', 401));
+    }
+    
+    if (req.user.role !== role) {
+      return next(new AppError('Insufficient permissions', 403));
+    }
+    
+    next();
+  };
+};
+
+module.exports = {
+  authenticateToken,
+  optionalAuth,
+  requireRole,
+};

package/templates/middleware/errorHandler.js.ejs

@@ -0,0 +1,47 @@
+
+// templates/middleware/errorHandler.js.ejs
+const { AppError } = require('../utils/errors');
+
+const errorHandler = (err, req, res, next) => {
+  let error = { ...err };
+  error.message = err.message;
+
+  console.error(err);
+
+<% if (db === 'mongodb') { %>  // Mongoose bad ObjectId
+  if (err.name === 'CastError') {
+    const message = 'Resource not found';
+    error = new AppError(message, 404);
+  }
+
+  // Mongoose duplicate key
+  if (err.code === 11000) {
+    const message = 'Duplicate field value entered';
+    error = new AppError(message, 400);
+  }
+
+  // Mongoose validation error
+  if (err.name === 'ValidationError') {
+    const message = Object.values(err.errors).map(val => val.message).join(', ');
+    error = new AppError(message, 400);
+  }<% } %>
+
+<% if (hasDatabase) { %>  // JWT errors
+  if (err.name === 'JsonWebTokenError') {
+    const message = 'Invalid token';
+    error = new AppError(message, 401);
+  }
+
+  if (err.name === 'TokenExpiredError') {
+    const message = 'Token expired';
+    error = new AppError(message, 401);
+  }<% } %>
+
+  res.status(error.statusCode || 500).json({
+    success: false,
+    error: error.message || 'Server Error',
+    ...(process.env.NODE_ENV === 'development' && { stack: err.stack }),
+  });
+};
+
+module.exports = errorHandler;