https://github.com/ebukaodini/express-api-template
an express typescript api template
https://github.com/ebukaodini/express-api-template
expressjs low-code restapi-framework typescript validation-library
Last synced: 7 days ago
JSON representation
an express typescript api template
- Host: GitHub
- URL: https://github.com/ebukaodini/express-api-template
- Owner: ebukaodini
- License: mit
- Created: 2024-01-12T04:21:34.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-01-17T16:13:53.000Z (about 1 year ago)
- Last Synced: 2025-04-14T21:11:32.377Z (10 months ago)
- Topics: expressjs, low-code, restapi-framework, typescript, validation-library
- Language: TypeScript
- Homepage:
- Size: 45.9 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Express TypeScript API Template
A robust, production-ready Express.js API template built with TypeScript, featuring comprehensive testing, documentation, and modern development practices.
## 🚀 Features
- **TypeScript** - Full type safety and modern JavaScript features
- **Express.js** - Fast, unopinionated web framework
- **Central Entry Point** - Robust application architecture with dependency injection
- **Prisma** - Modern database toolkit with type-safe queries
- **Jest** - Comprehensive testing suite with unit and integration tests
- **Swagger/OpenAPI** - Interactive API documentation
- **Winston** - Structured logging
- **Rate Limiting** - Built-in request rate limiting
- **Security** - Helmet.js for security headers
- **Validation** - Class-validator for request validation
- **Error Handling** - Custom error classes and centralized error handling
- **Environment Configuration** - Centralized config management
- **Docker Support** - Ready for containerization
- **Code Quality** - Prettier, ESLint, and TypeScript strict mode
## 📁 Project Structure
```
src/
├── app/ # Central entry point architecture
│ ├── application.ts # Main application class
│ └── service-registry.ts # Service management
├── bootstrap/ # Configuration management
│ ├── app.ts # Express app setup
│ ├── config.ts # Main application class
│ ├── errors.ts # Custom error classes
│ ├── modules.ts # Main application class
│ ├── seeders.ts # Main application class
│ └── services.ts # Main application class
├── features/ # Feature-based modules
│ └── user/ # User feature module
│ ├── user.controller.ts
│ ├── user.service.ts
│ ├── user.repo.ts
│ ├── user.dto.ts
│ └── user.entity.ts
├── middlewares/ # Express middlewares
├── services/ # Shared services
├── utils/ # Utility functions
├── server.ts # Central entry point
├── __tests__/ # Test files
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── prisma.config.ts # Test configuration
```
## 🛠️ Setup
### Prerequisites
- Node.js (v18 or higher)
- PostgreSQL (v12 or higher)
- npm or yarn
### 1. Clone the repository
```bash
npx degit https://github.com/ebukaodini/express-api-template.git my-api
cd my-api
```
### 2. Install dependencies
```bash
pnpm install
```
### 3. Environment Configuration
Create a `.env` file in the root directory:
```bash
cp .env.example .env
```
Update the environment variables:
```env
# Server Configuration
PORT=3000
NODE_ENV=development
# Database Configuration
DATABASE_URL="postgresql://username:password@localhost:5432/sample_api"
# CORS Configuration
CORS_ORIGIN="http://localhost:3000,http://localhost:3001"
CORS_CREDENTIALS=true
# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX=100
# JWT Configuration
JWT_SECRET="your-super-secret-jwt-key-change-this-in-production"
JWT_EXPIRES_IN="24h"
# Logging
LOG_LEVEL="debug"
```
### 4. Database Setup
```bash
# Generate Prisma client
pnpm prisma:generate
# Run database migrations
pnpm prisma:migrate
# Seed the database (optional)
pnpm seed:dev
```
### 5. Start the development server
**Traditional way:**
```bash
pnpm dev
```
The API will be available at `http://localhost:3000`
## 📚 API Documentation
Once the server is running, you can access the interactive API documentation at:
- **Swagger UI**: `http://localhost:3000/api-docs`
- **Health Check**: `http://localhost:3000/health`
## 🧪 Testing
### Run all tests
```bash
pnpm test
```
### Run tests in watch mode
```bash
pnpm run test:watch
```
### Run tests with coverage
```bash
npm run test:coverage
```
### Run integration tests only
```bash
npm run test:integration
```
## 📝 Available Scripts
| Script | Description |
|--------|-------------|
| `npm run dev` | Start development server with hot reload |
| `npm run build` | Build the project for production |
| `npm start` | Start production server |
| `npm test` | Run all tests |
| `npm run test:watch` | Run tests in watch mode |
| `npm run test:coverage` | Run tests with coverage report |
| `npm run test:integration` | Run integration tests only |
| `npm run test:central` | Run central entry point tests |
| `npm run example` | Run central entry point examples |
| `npm run start:central` | Start with central entry point |
| `npm run dev:central` | Development with central entry point |
| `npm run lint` | Format code with Prettier |
| `npm run lint:check` | Check code formatting |
| `npm run prisma:migrate` | Run database migrations |
| `npm run prisma:generate` | Generate Prisma client |
| `npm run prisma:seed` | Seed the database |
| `npm run docs` | Display API documentation info |
## 🏗️ Architecture
### Central Entry Point Architecture
This template implements a robust central entry point architecture that provides:
- **Application Class** - Main orchestrator for application lifecycle
- **Dependency Injection** - Container-based service management
- **Service Registry** - Centralized service lifecycle management
- **Service Factory** - Factory pattern for service creation
- **Health Monitoring** - Comprehensive service health checks
### Feature-Based Structure
The project follows a feature-based architecture where each feature is self-contained with its own:
- **Controller** - Handles HTTP requests and responses
- **Service** - Contains business logic
- **Repository** - Handles data access
- **DTO** - Data transfer objects for validation
- **Entity** - Domain models
- **Routes** - API route definitions
### Error Handling
- Custom error classes for different error types
- Centralized error handling middleware
- Structured error responses
- Proper HTTP status codes
### Logging
- Winston logger with multiple transports
- Structured logging with timestamps
- Different log levels for different environments
- Request/response logging
### Security
- Helmet.js for security headers
- CORS configuration
- Rate limiting
- Input validation
- SQL injection protection (via Prisma)
## 🚀 Deployment
### Docker
```bash
# Build the Docker image
docker build -t my-api .
# Run the container
docker run -p 3000:3000 my-api
```
### Environment Variables for Production
Make sure to set the following environment variables in production:
- `NODE_ENV=production`
- `DATABASE_URL` - Your production database URL
- `JWT_SECRET` - A strong, random secret key
- `CORS_ORIGIN` - Your production frontend URL
- `LOG_LEVEL=info`
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for your changes
5. Ensure all tests pass
6. Submit a pull request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built with [scaffold.js](https://www.npmjs.com/package/@ebukaodini/scaffold.js)
- Inspired by modern Node.js best practices
- Community contributions and feedback