🚀 Node.js Boilerplate

A minimal Node.js boilerplate for building backend APIs with clean architecture.

Quick Start

1. Install Dependencies

npm install

2. Setup Environment

cp .env.example .env.development
cp .env.example .env.qa
cp .env.example .env.staging
cp .env.example .env.production

Edit each file with your configuration values. See .env.example for available options.

3. Start Server

npm run dev        # Development (auto-reload)
npm run qa         # QA environment
npm run staging    # Staging environment
npm start          # Production

Server runs at http://localhost:5000

📁 Folder Structure

src/
├── config/        Configuration & environment
├── constants/     App constants
├── controllers/   Request handlers
├── database/      Database connection
├── middleware/    Express middleware (logging, error handling, security)
├── models/        Database schemas
├── routes/        API route definitions
├── services/      Business logic
├── utils/         Utility functions
├── validators/    Input validation
└── server.js      Express app setup

🔌 Endpoints

Endpoint	Method	Purpose
/health	GET	Health check
/info	GET	API info
/api/db/status	GET	Database status

📜 Scripts

npm start              Production server
npm run dev            Dev server (auto-reload)
npm run qa             QA environment
npm run staging        Staging environment
npm run lint           ESLint check
npm run lint:fix       Fix linting issues
npm run format         Format code
npm run build          Lint + format
npm test               Run tests
npm run test:watch     Watch mode tests
npm run test:coverage  Coverage report

⚙️ Environment

All configuration via environment variables. See .env.example.

Key variables:

• APP_ENV - Environment type
• APP_PORT - Server port
• LOG_LEVEL - Logging level
• DB_TYPE - Database type (mongodb|mysql|postgresql)
• CORS_ORIGIN - CORS origins

🧪 Testing

npm test               Run tests
npm run test:watch     Watch mode
npm run test:coverage  Coverage

Test files in src/__tests__/:

• Unit tests for database & controllers
• Integration tests for API endpoints

🔒 Pre-commit Hooks

Husky runs ESLint & Prettier before commits:

git commit -m "message"   Runs hooks automatically
git commit --no-verify    Skip hooks if needed

Extending

Add Validation

1. Create src/validators/yourValidator.js
2. Use in controllers

Add Model

1. Create src/models/YourModel.js
2. Use in services

Add Service

1. Create src/services/YourService.js
2. Import in controllers
3. Use for database operations & business logic

Add Controller

1. Create src/controllers/YourController.js
2. Create src/routes/yourRoutes.js
3. Mount in src/server.js