A production-ready Node.js boilerplate with TypeScript, Express, MongoDB, and comprehensive testing setup using Test-Driven Development (TDD) approach.
# 1. Clone the repository
git clone https://github.com/yourusername/boilerplate-node.git
cd boilerplate-node
# 2. Install dependencies
yarn install
# 3. Copy and configure environment variables
cp .env.example .env
# Edit .env as needed
# 4. Start the development server
yarn dev
# 5. Run tests
yarn test- Runtime: Node.js
- Language: TypeScript
- Web Framework: Express.js
- Database: MongoDB with Mongoose
- Authentication: JWT (Access & Refresh Tokens) + bcrypt + Cookies (HttpOnly)
- Validation: Zod for schema validation (Requests & Environment Variables)
- Logging: Winston + Morgan
- Testing: Jest with Supertest
- Code Quality: ESLint, Prettier, Husky, lint-staged
- Process Manager: PM2
- Containerization: Docker
- Rate Limiting: Express Rate Limit
- AI Integration: OpenAI SDK (configured for Gemini)
- User Model: MongoDB schema with secure password hashing using bcrypt
- User Service: Business logic layer with CRUD operations and validation
- User Controllers: RESTful API endpoints with proper status codes
- Role-Based Access Control (RBAC): 'admin' and 'user' roles
- User Validation: Zod schemas for request validation
- User Routes: Structured API routes with versioning
- Secure registration and login
- JWT-based access and refresh tokens
- HttpOnly cookie for refresh token storage
- Role-Based Access Control (RBAC) for user permissions
- Middleware for authentication and authorization
- Logout endpoint clears refresh token cookie
- Winston logger with daily rotating log files
- Morgan HTTP request logging
- Separate error logs and combined logs
- Different log levels for development and production
- MongoDB integration with Mongoose
- Containerized database with Docker
- Environment-based configuration
- TypeScript for type safety
- ESLint for code linting
- Prettier for code formatting
- Husky for Git hooks
- Lint-staged for pre-commit checks
- Utility function (
AIRequest.ts) to interact with AI models via OpenAI SDK - Configurable for different models (defaults to Gemini via compatible endpoint)
- Multi-environment Docker compositions
- Production-ready Dockerfile
- Development and testing environments
- MongoDB container integration
POST /api/v1/auth/register - Register a new user
POST /api/v1/auth/login - Login user and get JWT token
POST /api/v1/auth/logout - Logout user (clears refresh token cookie)
POST /api/v1/auth/refresh - Refresh JWT tokens using refresh token cookie
GET /api/v1/auth/profile - Get authenticated user's profile
POST /api/v1/users - Create a new user (Admin only)
GET /api/v1/users - Get all users (Admin only, with filtering and pagination)
GET /api/v1/users/:userId - Get a specific user (Admin or Owner)
PATCH /api/v1/users/:userId - Update a user (Admin or Owner)
DELETE /api/v1/users/:userId - Delete a user (Admin only)
.
├── src/
│ ├── config/ # Configuration files
│ ├── controllers/ # Route controllers
│ ├── middlewares/ # Express middlewares
│ ├── models/ # Mongoose models
│ ├── routes/ # API routes
│ ├── services/ # Business logic
│ ├── utils/ # Utility functions
│ ├── validations/ # Request validation schemas
│ ├── app.ts # Express app setup
│ └── index.ts # Application entry point
├── tests/
│ ├── integration/ # Integration tests
│ ├── unit/ # Unit tests
│ └── testEnv.ts # Test environment setup
├── logs/ # Application logs
├── Dockerfile # Docker build file
├── docker-compose.*.yml # Docker Compose files
├── .env.example # Example environment variables
├── README.md # Project documentation
└── ... # Other config and setup files
-
Test-Driven Development (TDD):
- Write failing tests first
- Write minimal code to pass
- Refactor with tests green
-
Testing Layers:
- Unit Tests: Isolated modules (models, services, controllers, utils, middlewares)
- Integration Tests: API endpoints, middleware chains, DB operations
-
Coverage: High coverage for all business logic, error handling, and edge cases.
- Atomic Commits: Each logical change (feature, fix, refactor, test) is committed separately.
- Conventional Commits: Follows Conventional Commits for clarity.
- Pre-commit Hooks: Husky + lint-staged enforce code quality before every commit.
- Custom Error Class (ApiError): Status code, message, stack trace
- Global Error Handler: Centralized error processing, environment-based responses
- Async Handler: Catches promise rejections in route handlers
- Not Found Handler: 404 for undefined routes
- Validated and sanitized using Zod schemas
- Type-safe and runtime-checked
- See
src/config/env.validation.tsfor all variables and defaults
- Zod-based middleware for body, query, params, cookies
- Type-safe, detailed error messages, automatic parsing
yarn start- Start production server with PM2yarn dev- Start development server with nodemonyarn build- Build TypeScript codeyarn test- Run all testsyarn test:watch- Run tests in watch modeyarn coverage- Generate test coverage reportyarn lint- Run ESLintyarn format- Run Prettier checkyarn docker:prod- Run production Docker environmentyarn docker:dev- Run development Docker environmentyarn docker:test- Run test Docker environment
- Fork the repository
- Create a new branch (
git checkout -b feature/my-feature) - Make your changes (with tests!)
- Run
yarn lintandyarn testbefore committing - Commit using Conventional Commits
- Push your branch and open a Pull Request
Q: How do I run tests?
A: yarn test for all tests, yarn test:watch for watch mode, yarn coverage for coverage.
Q: How do I add a new environment variable?
A: Add it to .env.example and update src/config/env.validation.ts with a Zod schema.
Q: How do I add a new API route?
A: Create a controller, add a route in src/routes/v1/, and add validation in src/validations/.
Q: How do I use Docker for development?
A: yarn docker:dev spins up the app and MongoDB in containers.
Q: How do I reset the database?
A: Stop the containers and remove the MongoDB volume, or use a test database for development.
This project is licensed for non-commercial use. See the LICENSE file for the full terms.
Shuvrojit Biswas