@codeenthusiast09/create-express-app 1.0.0

package/templates/boilerplate/README.md

@@ -0,0 +1,282 @@
+# Express TypeScript Boilerplate
+
+A production-ready Express.js boilerplate with TypeScript, featuring a clean architecture inspired by NestJS.
+
+## Features
+
+- **Clean Architecture** - Modular structure ready for your features
+- **Type Safety** - Strict TypeScript configuration
+- **Validation** - Request validation with Zod
+- **Logging** - Structured logging with Pino
+- **Configuration** - Type-safe config with environment validation
+- **Code Quality** - ESLint + Prettier configured
+- **Docker Ready** - Coming soon
+- **Testing Setup** - Jest configured
+
+## Prerequisites
+
+- Node.js 20.x or higher
+- npm
+- Database: MongoDB OR PostgreSQL (depending on your choice)
+
+## 💾 Database Options
+
+This boilerplate supports three database configurations:
+
+1. **MongoDB with Mongoose** (default)
+2. **PostgreSQL with Prisma**
+3. **PostgreSQL with Drizzle**
+
+The active connection is set in `src/database/index.ts`. See `DEPENDENCIES.md` for setup instructions.
+
+When using the CLI tool, it will automatically configure the database based on your selection.
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+npm install
+```
+
+### 2. Set Up Environment
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your values:
+
+```env
+NODE_ENV=development
+PORT=3000
+DATABASE_URL=mongodb://localhost:27017/myapp
+JWT_SECRET=your-super-secret-jwt-key-min-32-characters-for security
+```
+
+### 3. Start Development Server
+
+```bash
+npm run dev
+```
+
+Server will start at `http://localhost:3000`
+
+## 📁 Project Structure
+
+```
+src/
+├── common/              # Shared utilities and middleware
+│   ├── middleware/      # Express middleware (error handling, validation)
+│   └── utils/           # Helper functions (logger, response formatter)
+├── config/              # Configuration with Zod validation
+├── database/            # Database connection
+├── modules/             # Your feature modules go here
+│   └── .gitkeep
+├── types/               # TypeScript type definitions
+└── server.ts            # Application entry point
+```
+
+## 🗂️ How to Add a Module
+
+### Quick Way: Use the Module Generator
+
+```bash
+npm run generate:module users
+```
+
+This creates:
+
+```
+src/modules/users/
+├── user.controller.ts       # Route handlers
+├── user.service.ts          # Business logic
+├── user.routes.ts           # Route definitions
+├── user.validation.ts       # Request validation schemas
+├── user.repository.interface.ts  # Repository contract
+└── user.repository.ts       # Database operations
+```
+
+Then:
+
+1. Implement database operations in `user.repository.ts`
+2. Update validation schemas in `user.validation.ts`
+3. Register routes in `server.ts`:
+   ```typescript
+   import userRoutes from './modules/users/user.routes';
+   app.use('/api/users', userRoutes);
+   ```
+
+### Manual Way: Create Files Yourself
+
+Create a new folder in `src/modules/` with this structure:
+
+```
+src/modules/users/
+├── user.controller.ts    # Route handlers
+├── user.service.ts       # Business logic
+├── user.repository.ts    # Database operations
+├── user.routes.ts        # Route definitions
+├── user.validation.ts    # Request validation schemas
+└── user.model.ts         # Database model (Mongoose/Prisma)
+```
+
+Then register routes in `server.ts`:
+
+```typescript
+import userRoutes from './modules/users/user.routes';
+app.use('/api/users', userRoutes);
+```
+
+## API Endpoints
+
+### Health Check
+
+```http
+GET /health
+```
+
+Returns server status and uptime.
+
+### Root
+
+```http
+GET /
+```
+
+Returns welcome message.
+
+## Testing
+
+```bash
+# Run tests
+npm test
+
+# Watch mode
+npm run test:watch
+
+# Coverage
+npm run test:coverage
+```
+
+## Building
+
+```bash
+# Build for production
+npm run build
+
+# Start production server
+npm start
+```
+
+## 🐳 Docker
+
+### Using Docker Compose (Recommended for Development)
+
+```bash
+# Start all services (app + database)
+docker-compose up
+
+# Start in detached mode
+docker-compose up -d
+
+# View logs
+docker-compose logs -f app
+
+# Stop services
+docker-compose down
+
+# Remove volumes (clears database)
+docker-compose down -v
+```
+
+### Manual Docker Build
+
+```bash
+# Build image
+docker build -t express-app .
+
+# Run container
+docker run -p 3000:3000 \
+  -e DATABASE_URL=mongodb://host:27017/myapp \
+  -e JWT_SECRET=your-secret-min-32-chars \
+  express-app
+```
+
+### Database Selection in Docker
+
+By default, docker-compose uses MongoDB. To use PostgreSQL:
+
+1. Comment out MongoDB service
+2. Uncomment PostgreSQL service
+3. Uncomment PostgreSQL `DATABASE_URL` in app service
+4. Update depends_on to use postgres
+
+## Code Quality
+
+```bash
+# Lint
+npm run lint
+npm run lint:fix
+
+# Format
+npm run format
+npm run format:check
+
+# Type check
+npm run typecheck
+```
+
+## Path Aliases
+
+Use clean imports with path aliases:
+
+```typescript
+// ❌ Don't do this
+import { logger } from '../../../common/utils/logger';
+
+// ✅ Do this
+import { logger } from '@/common/utils/logger';
+```
+
+Available aliases:
+
+- `@/modules/*`
+- `@/common/*`
+- `@/config/*`
+- `@/database/*`
+- `@/types/*`
+
+## Environment Variables
+
+| Variable       | Description                               | Required |
+| -------------- | ----------------------------------------- | -------- |
+| `NODE_ENV`     | Environment (development/production/test) | No       |
+| `PORT`         | Server port                               | No       |
+| `DATABASE_URL` | Database connection string                | Yes      |
+| `JWT_SECRET`   | JWT signing secret (min 32 chars)         | Yes      |
+| `CORS_ORIGIN`  | CORS allowed origins                      | No       |
+| `LOG_LEVEL`    | Logging level (info/debug/error)          | No       |
+
+## Scripts
+
+| Script           | Description              |
+| ---------------- | ------------------------ |
+| `npm run dev`    | Start development server |
+| `npm run build`  | Build for production     |
+| `npm start`      | Run production build     |
+| `npm test`       | Run tests                |
+| `npm run lint`   | Check code quality       |
+| `npm run format` | Format code              |
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch
+3. Commit your changes
+4. Push to the branch
+5. Open a Pull Request
+
+## License
+
+MIT

package/templates/boilerplate/docker/.dockerignore

@@ -0,0 +1,46 @@
+# Dependencies
+node_modules
+npm-debug.log
+package-lock.json
+
+# Build output
+dist
+build
+
+# Environment files
+.env
+.env.development
+.env.production
+.env.local
+.env.*.local
+
+# Git
+.git
+.gitignore
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+
+# Testing
+coverage
+.nyc_output
+
+# Documentation
+README.md
+docs
+
+# Docker files
+Dockerfile
+docker-compose.yml
+.dockerignore
+
+# CI/CD
+.github
+.gitlab-ci.yml
+
+# Misc
+.DS_Store
+*.log

package/templates/boilerplate/docker/Dockerfile

@@ -0,0 +1,61 @@
+# Multi-stage build for smaller final image
+
+# Stage 1: Build
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files first (for better layer caching)
+COPY package*.json ./
+
+# Install ALL dependencies (including devDependencies for build)
+RUN npm ci
+
+# Copy source code
+COPY . .
+
+# Build TypeScript and remove dev dependencies
+RUN npm run build && \
+  npm prune --production
+
+# Stage 2: Production
+FROM node:20-alpine AS production
+
+# Create non-root user for security
+RUN addgroup -g 1001 -S nodejs && \
+  adduser -S nodejs -u 1001
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+
+# Copy package files
+COPY package*.json ./
+
+# Copy built app and production dependencies from builder
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+
+# Change ownership to non-root user
+RUN chown -R nodejs:nodejs /app
+
+# Switch to non-root user
+USER nodejs
+
+# Expose port
+ARG PORT=3000
+ENV PORT=${PORT}
+
+EXPOSE ${PORT}
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD node -e "require('http').get('http://localhost:' + (process.env.PORT || 3000) + '/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"
+
+# Run the application
+CMD ["node", "dist/server.js"]
+
+# Labels
+LABEL maintainer="your-email@example.com" \
+  description="Express TypeScript API" \
+  version="1.0.0"

package/templates/boilerplate/docker/docker-compose.yml

@@ -0,0 +1,68 @@
+version: '3.8'
+
+services:
+  # MongoDB Service
+  mongodb:
+    image: mongo:7
+    container_name: express-mongodb
+    restart: unless-stopped
+    ports:
+      - '27017:27017'
+    environment:
+      MONGO_INITDB_ROOT_USERNAME: admin
+      MONGO_INITDB_ROOT_PASSWORD: password123
+      MONGO_INITDB_DATABASE: myapp
+    volumes:
+      - mongodb_data:/data/db
+    networks:
+      - app-network
+
+  # PostgreSQL Service (uncomment if using PostgreSQL)
+  # postgres:
+  #   image: postgres:16-alpine
+  #   container_name: express-postgres
+  #   restart: unless-stopped
+  #   ports:
+  #     - '5432:5432'
+  #   environment:
+  #     POSTGRES_USER: postgres
+  #     POSTGRES_PASSWORD: password123
+  #     POSTGRES_DB: myapp
+  #   volumes:
+  #     - postgres_data:/var/lib/postgresql/data
+  #   networks:
+  #     - app-network
+
+  # Application Service
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: production
+    container_name: express-app
+    restart: unless-stopped
+    ports:
+      - '3000:3000'
+    environment:
+      NODE_ENV: production
+      PORT: 3000
+      # MongoDB connection
+      DATABASE_URL: mongodb://admin:password123@mongodb:27017/myapp?authSource=admin
+      # PostgreSQL connection (uncomment if using PostgreSQL)
+      # DATABASE_URL: postgresql://postgres:password123@postgres:5432/myapp
+      JWT_SECRET: your-super-secret-jwt-key-change-this-in-production-min-32-chars
+      JWT_EXPIRES_IN: 7d
+      LOG_LEVEL: info
+    depends_on:
+      - mongodb
+      # - postgres  # Uncomment if using PostgreSQL
+    networks:
+      - app-network
+
+networks:
+  app-network:
+    driver: bridge
+
+volumes:
+  mongodb_data:
+  # postgres_data:  # Uncomment if using PostgreSQL

package/templates/boilerplate/drizzle/drizzle.config.ts

@@ -0,0 +1,13 @@
+import type { Config } from 'drizzle-kit';
+import * as dotenv from 'dotenv';
+
+dotenv.config({ path: '.env', quiet: true });
+
+export default {
+  schema: './drizzle/schema.ts',
+  out: './drizzle/migrations',
+  driver: 'pg',
+  dbCredentials: {
+    connectionString: process.env.DATABASE_URL || '',
+  },
+} satisfies Config;

package/templates/boilerplate/drizzle/schema.ts

@@ -0,0 +1,22 @@
+import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';
+
+/**
+ * Drizzle Schema
+ *
+ * Define your database tables here.
+ * This is an example User table (commented out).
+ * Uncomment and modify as needed.
+ */
+
+// Example User table
+// export const users = pgTable('users', {
+//   id: uuid('id').defaultRandom().primaryKey(),
+//   email: text('email').notNull().unique(),
+//   name: text('name').notNull(),
+//   createdAt: timestamp('created_at').defaultNow().notNull(),
+//   updatedAt: timestamp('updated_at').defaultNow().notNull(),
+// });
+
+// Export all tables
+// export type User = typeof users.$inferSelect;
+// export type NewUser = typeof users.$inferInsert;

package/templates/boilerplate/jest.config.cjs

@@ -0,0 +1,24 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/__tests__/**/*.ts', '**/?(*.)+(spec|test).ts'],
+  transform: {
+    '^.+\\.ts$': 'ts-jest',
+  },
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+    '!src/**/*.interface.ts',
+    '!src/**/*.type.ts',
+    '!src/server.ts',
+  ],
+  coverageDirectory: 'coverage',
+  moduleNameMapper: {
+    '^@/modules/(.*)$': '<rootDir>/src/modules/$1',
+    '^@/common/(.*)$': '<rootDir>/src/common/$1',
+    '^@/config/(.*)$': '<rootDir>/src/config/$1',
+    '^@/database/(.*)$': '<rootDir>/src/database/$1',
+    '^@/types/(.*)$': '<rootDir>/src/types/$1',
+  },
+};

package/templates/boilerplate/nodemon.json

@@ -0,0 +1,11 @@
+{
+  "watch": [
+    "src"
+  ],
+  "ext": "ts,json",
+  "ignore": [
+    "src/**/*.spec.ts",
+    "src/**/*.test.ts"
+  ],
+  "exec": "ts-node -r tsconfig-paths/register src/server.ts"
+}

package/templates/boilerplate/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "express-app",
+  "version": "1.0.0",
+  "description": "Express TypeScript API",
+  "main": "dist/server.js",
+  "scripts": {
+    "dev": "nodemon",
+    "build": "tsc && tsc-alias",
+    "start": "node dist/server.js",
+    "start:prod": "NODE_ENV=production node dist/server.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "generate:module": "node scripts/generate-module.cjs"
+  },
+  "keywords": [
+    "express",
+    "typescript",
+    "nodejs",
+    "api"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "bcryptjs": "^2.4.3",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express": "^4.18.2",
+    "jsonwebtoken": "^9.0.2",
+    "pino": "^8.19.0",
+    "pino-http": "^9.0.0",
+    "pino-pretty": "^10.3.1",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/bcryptjs": "^2.4.6",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/jest": "^29.5.12",
+    "@types/jsonwebtoken": "^9.0.5",
+    "@types/node": "^20.11.19",
+    "@types/supertest": "^6.0.2",
+    "@typescript-eslint/eslint-plugin": "^6.20.0",
+    "@typescript-eslint/parser": "^6.20.0",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "nodemon": "^3.0.3",
+    "prettier": "^3.2.5",
+    "supertest": "^6.3.4",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "tsc-alias": "^1.8.16",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.3.3"
+  }
+}