https://github.com/zahidrahimoon/nest-boiler
https://github.com/zahidrahimoon/nest-boiler
Last synced: 6 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/zahidrahimoon/nest-boiler
- Owner: zahidrahimoon
- Created: 2025-12-11T19:34:50.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2025-12-13T15:27:44.000Z (7 months ago)
- Last Synced: 2025-12-15T06:23:32.379Z (7 months ago)
- Language: TypeScript
- Size: 138 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# NestJS Enterprise Boilerplate
A production-ready NestJS boilerplate with enterprise-level architecture, following best practices for scalable and maintainable applications.
## 🌟 Features
- ✅ **Enterprise Architecture** - Scalable folder structure with clear separation of concerns
- ✅ **Authentication & Authorization** - JWT-based auth with guards and decorators
- ✅ **Database Integration** - TypeORM with PostgreSQL
- ✅ **API Documentation** - Swagger/OpenAPI integration
- ✅ **Security** - Password hashing with bcrypt, global auth guard
- ✅ **Validation** - Class-validator for DTO validation
- ✅ **Modular Design** - Domain-driven structure ready for expansion
- ✅ **Helper Utilities** - Response and exception helpers
- ✅ **TypeScript** - Full type safety
## 📁 Project Structure
```
src/
├── common/ # Shared utilities across modules
│ ├── constants/ # Global constants
│ ├── decorators/ # Custom decorators
│ │ ├── current-user.decorator.ts
│ │ └── public.decorator.ts
│ ├── guards/ # Authentication guards
│ │ └── auth.guard.ts
│ ├── helpers/ # Helper utilities
│ │ ├── exceptions/ # Exception helpers
│ │ └── responses/ # Response formatters
│ ├── interfaces/ # Shared interfaces
│ ├── pipes/ # Custom pipes
│ └── serializers/ # Data serializers
├── config/ # Configuration modules
│ ├── app/ # App configuration
│ ├── database/ # Database configuration
│ │ └── postgres/
│ │ └── postgres.module.ts
│ └── swagger/ # Swagger configuration
│ └── swagger.config.ts
├── models/ # Domain models
│ └── users/ # User domain
│ ├── constants/ # User-specific constants
│ ├── dto/ # Data transfer objects
│ ├── entities/ # TypeORM entities
│ ├── interfaces/ # User interfaces
│ ├── serializers/ # User serializers
│ ├── users.controller.ts
│ ├── users.service.ts
│ ├── users.module.ts
│ └── users.providers.ts
├── authentication/ # Authentication module
│ ├── constants/ # Auth constants
│ ├── dto/ # Auth DTOs
│ ├── authentication.controller.ts
│ ├── authentication.service.ts
│ └── authentication.module.ts
├── providers/ # External service providers
│ └── database/ # Database providers
│ └── postgres/
│ └── postgres.provider.ts
├── app.controller.ts
├── app.module.ts
├── app.service.ts
└── main.ts
```
## 🚀 Getting Started
### Prerequisites
- Node.js (v18 or higher)
- PostgreSQL (v14 or higher)
- npm or yarn
### Installation
1. **Clone the repository**
```bash
git clone git@github.com:zahidrahimoon/nest-boiler.git
cd nest-boiler
```
2. **Install dependencies**
```bash
npm install
```
3. **Environment Setup**
Create a `.env` file in the root directory:
```env
# Application
PORT=3000
# Database
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=your_password
DB_NAME=nestjs_lms
# JWT
JWT_SECRET=your_super_secret_jwt_key
```
4. **Run the application**
```bash
# Development mode with hot-reload
npm run start:dev
# Production mode
npm run start:prod
# Debug mode
npm run start:debug
```
The application will be available at `http://localhost:3000`
## 📚 API Documentation
Swagger documentation is available at: `http://localhost:3000/documentation`
### Available Endpoints
#### Authentication
- `POST /auth/signup` - Register a new user
- `POST /auth/login` - Login with email and password
#### User
- `GET /user/profile` - Get authenticated user profile (requires JWT token)
## 🔐 Authentication
This boilerplate uses JWT-based authentication with the following flow:
1. **Public Routes** - Use `@Public()` decorator to bypass authentication
2. **Protected Routes** - All routes are protected by default via global `AuthGuard`
3. **Current User** - Use `@CurrentUser()` decorator to access authenticated user data
### Decorators
- `@Public()` - Mark routes as public (no authentication required)
- `@CurrentUser()` - Access authenticated user data in route handlers
## 🗄️ Database
### TypeORM Configuration
The application uses TypeORM with PostgreSQL. Entity registration is done in:
`src/providers/database/postgres/postgres.provider.ts`
### Adding New Entities
1. Create entity in `src/models/{domain}/entities/`
2. Register entity in `src/providers/database/postgres/postgres.provider.ts`
## 🧩 Adding New Features
### Creating a New Model
Follow the domain-driven structure:
```bash
src/models/courses/
├── constants/
├── dto/
│ ├── create-course.dto.ts
│ ├── update-course.dto.ts
│ └── course-response.dto.ts
├── entities/
│ └── course.entity.ts
├── serializers/
│ └── course.serializer.ts
├── courses.controller.ts
├── courses.service.ts
├── courses.module.ts
└── courses.providers.ts
```
## 🛠️ Helper Utilities
### Response Helper
- `ResponseHelper.success()` - Standardized success responses
- `ResponseHelper.paginated()` - Paginated data responses
- `ResponseHelper.error()` - Error responses
### Exception Helper
- `ExceptionHelper.notFound()` - 404 Not Found
- `ExceptionHelper.badRequest()` - 400 Bad Request
- `ExceptionHelper.unauthorized()` - 401 Unauthorized
- `ExceptionHelper.conflict()` - 409 Conflict
## 🧪 Testing
```bash
# Unit tests
npm run test
# E2E tests
npm run test:e2e
# Test coverage
npm run test:cov
```
## 📦 Build
```bash
# Build for production
npm run build
# Run production build
npm run start:prod
```
## 🏗️ Architecture Principles
### Separation of Concerns
- **Common**: Shared utilities and cross-cutting concerns
- **Config**: Application configuration
- **Models**: Domain-specific business logic
- **Providers**: External service integrations
### Scalability
- Modular design allows independent development
- Clear patterns for adding new features
- Domain-driven structure
### Maintainability
- Predictable file locations
- Consistent naming conventions
- Clear module boundaries
## 🔧 Configuration
### Swagger Configuration
Customize API documentation in `src/config/swagger/swagger.config.ts`
### Database Configuration
Modify database settings in `src/providers/database/postgres/postgres.provider.ts`
## 📝 Code Style
This project follows NestJS best practices and conventions:
- Use DTOs for data validation
- Implement serializers for response transformation
- Use guards for authorization
- Use decorators for metadata
- Follow domain-driven design
## 🤝 Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 🙏 Acknowledgments
- [NestJS](https://nestjs.com/) - The progressive Node.js framework
- [TypeORM](https://typeorm.io/) - ORM for TypeScript
- [Swagger](https://swagger.io/) - API documentation
## 📞 Support
For questions and support:
- Visit [NestJS Documentation](https://docs.nestjs.com)
- Join [NestJS Discord](https://discord.gg/G7Qnnhy)
## 👨💻 Author
**Muhammad Zahid Ali Rahimoon**
## 🔗 Repository
[GitHub Repository](https://github.com/zahidrahimoon/nest-boiler)