create-express-mongo-ts 1.0.0

package/README.md

@@ -0,0 +1,157 @@
+# create-express-mongo
+
+Create Express + MongoDB applications with TypeScript, authentication, and best practices out of the box.
+
+[![npm version](https://img.shields.io/npm/v/create-express-mongo.svg)](https://www.npmjs.com/package/create-express-mongo)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Quick Start
+
+```bash
+npx create-express-mongo my-app
+cd my-app
+npm install
+cp .env.example .env
+npm run dev
+```
+
+## What's Included
+
+This template provides a production-ready Express.js + MongoDB setup with:
+
+### 🔐 Authentication & Security
+- JWT-based authentication (access & refresh tokens)
+- API key management
+- Role-based access control (RBAC)
+- Password hashing with bcrypt
+- Helmet.js security headers
+- CORS configuration
+
+### 📁 Project Structure
+```
+my-app/
+├── src/
+│   ├── app.ts              # Express app setup
+│   ├── config.ts           # Environment configuration
+│   ├── index.ts            # Application entry point
+│   ├── core/               # Core utilities
+│   │   ├── ApiError.ts     # Custom error classes
+│   │   ├── ApiResponse.ts  # Standardized API responses
+│   │   ├── asyncHandler.ts # Async error handling wrapper
+│   │   ├── authUtils.ts    # Authentication utilities
+│   │   ├── jwtUtils.ts     # JWT token utilities
+│   │   ├── logger.ts       # Winston logger setup
+│   │   └── utils.ts        # General utilities
+│   ├── database/           # Database layer
+│   │   ├── index.ts        # MongoDB connection
+│   │   ├── models/         # Mongoose models
+│   │   └── repositories/   # Data access layer
+│   ├── helpers/            # Helper functions
+│   ├── middlewares/        # Express middlewares
+│   ├── routes/             # API routes
+│   └── types/              # TypeScript type definitions
+├── keys/                   # RSA keys for JWT (generate your own)
+├── Dockerfile              # Docker configuration
+├── tsconfig.json           # TypeScript configuration
+├── jest.config.ts          # Jest testing configuration
+└── eslint.config.mts       # ESLint configuration
+```
+
+### 🛠️ Tech Stack
+- **Runtime**: Node.js 18+
+- **Framework**: Express.js 5
+- **Database**: MongoDB with Mongoose ODM
+- **Language**: TypeScript
+- **Validation**: Zod
+- **Logging**: Winston with daily rotation
+- **Testing**: Jest
+- **Linting**: ESLint + Prettier
+
+## Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start development server with hot-reload |
+| `npm run build` | Compile TypeScript to JavaScript |
+| `npm start` | Build and run production server |
+| `npm test` | Run test suite |
+| `npm run lint` | Check code for linting errors |
+| `npm run lint:fix` | Fix linting errors automatically |
+| `npm run prettier:write` | Format code with Prettier |
+
+## Environment Variables
+
+Create a `.env` file based on `.env.example`:
+
+```env
+# Server Configuration
+PORT=3000
+NODE_ENV=development
+
+# Database Configuration
+DB_HOST=localhost
+DB_PORT=27017
+DB_NAME=myapp
+DB_USER=
+DB_PASSWORD=
+DB_MIN_POOL_SIZE=2
+DB_MAX_POOL_SIZE=5
+
+# JWT Configuration
+ACCESS_TOKEN_VALIDITY_SEC=3600
+REFRESH_TOKEN_VALIDITY_SEC=86400
+TOKEN_ISSUER=your-app
+TOKEN_AUDIENCE=your-app
+
+# CORS Configuration
+ORIGIN_URL=*
+
+# Logging
+LOG_DIRECTORY=logs
+```
+
+## JWT Keys Setup
+
+For production, generate RSA key pairs for JWT signing:
+
+```bash
+# Navigate to keys directory
+cd keys
+
+# Generate private key
+openssl genrsa -out private.pem 2048
+
+# Generate public key
+openssl rsa -in private.pem -pubout -out public.pem
+```
+
+## API Endpoints
+
+### Health Check
+- `GET /health` - Server health status
+
+### Authentication
+- `POST /auth/signup` - User registration
+- `POST /auth/signin` - User login
+- `POST /auth/signout` - User logout
+- `POST /auth/token/refresh` - Refresh access token
+
+## Docker Support
+
+Build and run with Docker:
+
+```bash
+# Build image
+docker build -t my-app .
+
+# Run container
+docker run -p 3000:3000 --env-file .env my-app
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// Colors for console output
+const colors = {
+    reset: '\x1b[0m',
+    bright: '\x1b[1m',
+    green: '\x1b[32m',
+    cyan: '\x1b[36m',
+    yellow: '\x1b[33m',
+    red: '\x1b[31m',
+};
+
+const log = {
+    info: (msg) => console.log(`${colors.cyan}ℹ${colors.reset} ${msg}`),
+    success: (msg) => console.log(`${colors.green}✔${colors.reset} ${msg}`),
+    warn: (msg) => console.log(`${colors.yellow}⚠${colors.reset} ${msg}`),
+    error: (msg) => console.log(`${colors.red}✖${colors.reset} ${msg}`),
+};
+
+// Get project name from command line arguments
+const projectName = process.argv[2];
+
+if (!projectName) {
+    log.error('Please specify the project directory:');
+    console.log(
+        `  ${colors.cyan}npx create-express-mongo${colors.reset} ${colors.green}<project-directory>${colors.reset}`,
+    );
+    console.log();
+    console.log('For example:');
+    console.log(
+        `  ${colors.cyan}npx create-express-mongo${colors.reset} ${colors.green}my-app${colors.reset}`,
+    );
+    process.exit(1);
+}
+
+const currentPath = process.cwd();
+const projectPath = path.join(currentPath, projectName);
+const templatePath = path.join(__dirname, '..', 'template');
+
+// Check if directory already exists
+if (fs.existsSync(projectPath)) {
+    log.error(
+        `The directory ${colors.green}${projectName}${colors.reset} already exists.`,
+    );
+    log.info(
+        'Please choose a different project name or delete the existing directory.',
+    );
+    process.exit(1);
+}
+
+console.log();
+console.log(
+    `${colors.bright}Creating a new Express + MongoDB app in ${colors.green}${projectPath}${colors.reset}`,
+);
+console.log();
+
+// Create project directory
+fs.mkdirSync(projectPath, { recursive: true });
+
+// Function to copy directory recursively
+function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+
+        if (entry.isDirectory()) {
+            copyDir(srcPath, destPath);
+        } else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+
+try {
+    // Copy template files
+    log.info('Copying template files...');
+    copyDir(templatePath, projectPath);
+    log.success('Template files copied successfully.');
+
+    // Update package.json with project name
+    const packageJsonPath = path.join(projectPath, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+        const packageJson = JSON.parse(
+            fs.readFileSync(packageJsonPath, 'utf8'),
+        );
+        packageJson.name = projectName;
+        packageJson.version = '1.0.0';
+        packageJson.description = `${projectName} - Express + MongoDB application`;
+        fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
+        log.success('Updated package.json with project name.');
+    }
+
+    // Create .env.example file
+    const envExamplePath = path.join(projectPath, '.env.example');
+    if (!fs.existsSync(envExamplePath)) {
+        const envContent = `# Server Configuration
+PORT=3000
+NODE_ENV=development
+
+# Database Configuration
+DB_HOST=localhost
+DB_PORT=27017
+DB_NAME=${projectName}
+DB_USER=
+DB_PASSWORD=
+DB_MIN_POOL_SIZE=2
+DB_MAX_POOL_SIZE=5
+
+# JWT Configuration
+ACCESS_TOKEN_VALIDITY_SEC=3600
+REFRESH_TOKEN_VALIDITY_SEC=86400
+
+# CORS Configuration
+CORS_URL=*
+
+# Logging
+LOG_DIR=logs
+`;
+        fs.writeFileSync(envExamplePath, envContent);
+        log.success('Created .env.example file.');
+    }
+
+    // Initialize git repository
+    log.info('Initializing git repository...');
+    try {
+        execSync('git init', { cwd: projectPath, stdio: 'ignore' });
+
+        // Create .gitignore if it doesn't exist
+        const gitignorePath = path.join(projectPath, '.gitignore');
+        if (!fs.existsSync(gitignorePath)) {
+            const gitignoreContent = `# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+
+# IDE
+.vscode/
+.idea/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Coverage
+coverage/
+
+# Keys (keep the folder structure but ignore actual keys)
+keys/*.pem
+keys/*.key
+
+# TypeScript cache
+*.tsbuildinfo
+`;
+            fs.writeFileSync(gitignorePath, gitignoreContent);
+        }
+        log.success('Initialized git repository.');
+    } catch (error) {
+        log.warn(
+            'Could not initialize git repository. Please initialize it manually.',
+        );
+    }
+
+    // Success message
+    console.log();
+    console.log(
+        `${colors.green}${colors.bright}Success!${colors.reset} Created ${colors.cyan}${projectName}${colors.reset} at ${colors.green}${projectPath}${colors.reset}`,
+    );
+    console.log();
+    console.log('Inside that directory, you can run several commands:');
+    console.log();
+    console.log(`  ${colors.cyan}npm install${colors.reset}`);
+    console.log('    Installs all dependencies.');
+    console.log();
+    console.log(`  ${colors.cyan}npm run dev${colors.reset}`);
+    console.log('    Starts the development server with hot-reload.');
+    console.log();
+    console.log(`  ${colors.cyan}npm run build${colors.reset}`);
+    console.log('    Builds the app for production.');
+    console.log();
+    console.log(`  ${colors.cyan}npm start${colors.reset}`);
+    console.log('    Builds and runs the production server.');
+    console.log();
+    console.log(`  ${colors.cyan}npm test${colors.reset}`);
+    console.log('    Runs the test suite.');
+    console.log();
+    console.log('We suggest that you begin by typing:');
+    console.log();
+    console.log(`  ${colors.cyan}cd${colors.reset} ${projectName}`);
+    console.log(`  ${colors.cyan}npm install${colors.reset}`);
+    console.log(`  ${colors.cyan}cp .env.example .env${colors.reset}`);
+    console.log(`  ${colors.cyan}npm run dev${colors.reset}`);
+    console.log();
+    console.log(`${colors.bright}Happy coding!${colors.reset} 🚀`);
+    console.log();
+} catch (error) {
+    log.error('An error occurred while creating the project:');
+    console.error(error);
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "create-express-mongo-ts",
+    "version": "1.0.0",
+    "description": "Create Express + MongoDB applications with TypeScript, authentication, and best practices out of the box",
+    "main": "bin/cli.js",
+    "bin": {
+        "create-express-mongo-ts": "./bin/cli.js"
+    },
+    "files": [
+        "bin",
+        "template"
+    ],
+    "scripts": {
+        "test": "echo \"No tests yet\""
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/sofikulsk02/express-mongobd-template.git"
+    },
+    "keywords": [
+        "express",
+        "mongodb",
+        "mongoose",
+        "typescript",
+        "template",
+        "boilerplate",
+        "rest-api",
+        "authentication",
+        "jwt",
+        "create-express-mongo",
+        "cli"
+    ],
+    "author": "sofikulsk02 <https://github.com/sofikulsk02>",
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/sofikulsk02/express-mongobd-template/issues"
+    },
+    "homepage": "https://github.com/sofikulsk02/express-mongobd-template#readme",
+    "type": "commonjs",
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}

package/template/.dockerignore

@@ -0,0 +1,2 @@
+dist
+node_modules

package/template/.prettierignore

@@ -0,0 +1,6 @@
+build/
+coverage/
+keys/
+logs/
+node_modules/
+*.md

package/template/.prettierrc

@@ -0,0 +1,8 @@
+{
+    "useTabs": false,
+    "semi": true,
+    "trailingComma": "all",
+    "singleQuote": true,
+    "printWidth": 80,
+    "tabWidth": 4
+}

package/template/Dockerfile

@@ -0,0 +1,17 @@
+FROM node:22
+
+USER node
+
+RUN mkdir -p /home/node/app && chown -R node:node /home/node/app
+
+WORKDIR /home/node/app
+
+COPY --chown=node:node . . 
+
+RUN npm install 
+
+# container exposed network port number
+EXPOSE 3000
+
+# command to run within the container
+CMD [ "npm", "start" ]

package/template/README.md

@@ -0,0 +1,67 @@
+# Express + MongoDB Template
+
+This is your new Express + MongoDB application. Follow the steps below to get started.
+
+## Getting Started
+
+1. **Install dependencies**
+   ```bash
+   npm install
+   ```
+
+2. **Set up environment variables**
+   ```bash
+   cp .env.example .env
+   ```
+   Then edit `.env` with your configuration.
+
+3. **Start MongoDB**
+   Make sure MongoDB is running locally or update the connection string in `.env`.
+
+4. **Run the development server**
+   ```bash
+   npm run dev
+   ```
+
+5. **Visit the health endpoint**
+   Open http://localhost:3000/health in your browser.
+
+## JWT Keys Setup (Required for Production)
+
+Generate RSA key pairs for JWT token signing:
+
+```bash
+cd keys
+openssl genrsa -out private.pem 2048
+openssl rsa -in private.pem -pubout -out public.pem
+```
+
+## Available Scripts
+
+- `npm run dev` - Start development server with hot-reload
+- `npm run build` - Compile TypeScript to JavaScript
+- `npm start` - Build and run production server
+- `npm test` - Run test suite
+- `npm run lint` - Check code for linting errors
+- `npm run lint:fix` - Fix linting errors automatically
+
+## Project Structure
+
+```
+├── src/
+│   ├── app.ts              # Express app setup
+│   ├── config.ts           # Environment configuration
+│   ├── index.ts            # Application entry point
+│   ├── core/               # Core utilities (errors, responses, logging)
+│   ├── database/           # Database connection and models
+│   ├── helpers/            # Helper functions
+│   ├── middlewares/        # Express middlewares
+│   ├── routes/             # API routes
+│   └── types/              # TypeScript type definitions
+├── keys/                   # RSA keys for JWT
+└── Dockerfile              # Docker configuration
+```
+
+## Learn More
+
+For more information, see the [create-express-mongo documentation](https://github.com/sofikulsk02/express-mongobd-template).

package/template/eslint.config.mts

@@ -0,0 +1,34 @@
+import tseslint from '@typescript-eslint/eslint-plugin';
+import tsparser from '@typescript-eslint/parser';
+
+export default [
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        project: './tsconfig.json',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tseslint,
+    },
+    rules: {
+      ...tseslint.configs.recommended.rules,
+      // Your custom rule overrides here
+      // "@typescript-eslint/explicit-function-return-type": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          "args": "all",
+          "argsIgnorePattern": "^_",
+          "caughtErrors": "all",
+          "caughtErrorsIgnorePattern": "^_",
+          "destructuredArrayIgnorePattern": "^_",
+          "varsIgnorePattern": "^_",
+          "ignoreRestSiblings": true
+        }
+      ]
+    },
+  },
+];