|
| 1 | +# Starter Kit API Project |
| 2 | + |
| 3 | +This Starter Kit API project serves as a robust foundation for building scalable and maintainable backend applications. It incorporates best practices, essential modules, and configurations to jumpstart your development process. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +- **Enhanced TypeScript Configuration**: Improved `tsconfig.json` for stricter type checking and better developer experience. |
| 8 | +- **Environment Configuration**: Utilizes `ConfigModule` for managing environment variables, including Jest setup. |
| 9 | +- **Consistent HTTP Responses**: Enforces a standardized structure for all HTTP responses. |
| 10 | +- **Basic HTTP Security**: Implements essential security measures to protect your application. |
| 11 | +- **Request Validation**: Incorporates whitelisted validation for incoming requests. |
| 12 | +- **Advanced Logging**: Utilizes Winston for comprehensive logging capabilities. |
| 13 | +- **Database Setup**: Docker Compose configuration for PostgreSQL and Redis. |
| 14 | +- **ORM Integration**: Prisma setup for efficient database interactions. |
| 15 | +- **Caching Solution**: Redis integration with a CacheService for improved performance. |
| 16 | +- **Testing Framework**: Jest configuration with environment variable support. |
| 17 | +- **CI Pipeline**: GitHub Actions setup for continuous integration. |
| 18 | + |
| 19 | +## Core Module |
| 20 | + |
| 21 | +The Core Module (`CoreModule`) serves as the central hub for essential application-wide services and configurations. It includes: |
| 22 | + |
| 23 | +- Global exception filters |
| 24 | +- Interceptors for response transformation |
| 25 | +- Logging service |
| 26 | +- Caching service |
| 27 | +- Database module |
| 28 | + |
| 29 | +When extending core functionality, consider adding services or providers to this module if they are required application-wide. |
| 30 | + |
| 31 | +## Logging |
| 32 | + |
| 33 | +This starter uses Winston for advanced logging capabilities. The `LoggerService` in the Core Module provides: |
| 34 | + |
| 35 | +- Customizable log formats for different environments |
| 36 | +- Log levels (error, warn, info, debug, verbose) |
| 37 | +- Context-based logging |
| 38 | +- Metadata support for detailed log entries |
| 39 | + |
| 40 | +To use the logger in your services or controllers, inject the `LoggerService` and utilize its methods for consistent logging across your application. |
| 41 | + |
| 42 | +## Getting Started |
| 43 | + |
| 44 | +1. Go to the [Starter Kit API](https://github.com/jfjuanmiguel/starter-kit-api) Github repo: |
| 45 | +2. Press the "Use this template" button to create a new repository. |
| 46 | +3. Follow the steps to create a new Github repo from the template. |
| 47 | +4. Clone the repository on your local machine: |
| 48 | + ``` |
| 49 | + git clone https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git |
| 50 | + ``` |
| 51 | +5. Install dependencies: |
| 52 | + ``` |
| 53 | + pnpm install |
| 54 | + ``` |
| 55 | +6. Set up your environment variables: |
| 56 | + Copy `.env.example` to `.env` and fill in the required values. |
| 57 | +7. Start the development server: |
| 58 | + ``` |
| 59 | + pnpm start:dev |
| 60 | + ``` |
| 61 | + |
| 62 | +The Starter Kit API project has 2 Docker Compose files: In both files, you need to update the name of the containers and networks where it says `# Needs updating`, for example `starter_kit_api` to the name of your project. |
| 63 | + |
| 64 | +``` |
| 65 | +services: |
| 66 | + postgres_starter_kit_api: # Needs updating |
| 67 | + image: postgres:alpine |
| 68 | + container_name: postgres_starter_kit_api # Needs updating |
| 69 | + restart: always |
| 70 | + env_file: |
| 71 | + - .env |
| 72 | + environment: |
| 73 | + - POSTGRES_USER=${POSTGRES_USER} |
| 74 | + - POSTGRES_PASSWORD=${POSTGRES_PASSWORD} |
| 75 | + ports: |
| 76 | + - '5432:5432' |
| 77 | + volumes: |
| 78 | + - postgres_data:/var/lib/postgresql/data |
| 79 | +
|
| 80 | + redis_starter_kit_api: # Needs updating |
| 81 | + image: redis:alpine |
| 82 | + container_name: redis_starter_kit_api # Needs updating |
| 83 | + ports: |
| 84 | + - '6379:6379' |
| 85 | + volumes: |
| 86 | + - redis_data:/data |
| 87 | +
|
| 88 | +networks: |
| 89 | + default: |
| 90 | + name: starter_kit_api # Needs updating |
| 91 | +
|
| 92 | +volumes: |
| 93 | + postgres_data: |
| 94 | + redis_data: |
| 95 | +``` |
| 96 | + |
| 97 | +Make sure you remember to also update the `docker-compose-test.yml` file! |
| 98 | + |
| 99 | +This repo comes with a default `User` model out of the box defined in the `/src/database/schema.prisma` file: |
| 100 | + |
| 101 | +``` |
| 102 | +model User { |
| 103 | + id Int @id @default(autoincrement()) |
| 104 | + email String @unique |
| 105 | + createdAt DateTime @default(now()) |
| 106 | + updatedAt DateTime @updatedAt |
| 107 | +} |
| 108 | +``` |
| 109 | + |
| 110 | +Before you can run the local server, you need to apply this migration to your local Postgres database. |
| 111 | + |
| 112 | +Make sure on your local machine you don't have any existing Docker containers running that would cause a conflict. |
| 113 | + |
| 114 | +Then spin up the local Postgres and Redis containers: |
| 115 | + |
| 116 | +``` |
| 117 | +pnpm docker:start |
| 118 | +``` |
| 119 | + |
| 120 | +Then run this script to apply the migration to your local Postgres database: |
| 121 | + |
| 122 | +``` |
| 123 | +pnpm db:migrate:dev |
| 124 | +``` |
| 125 | + |
| 126 | +And you're ready to go! |
| 127 | + |
| 128 | +You can now start the local server: |
| 129 | + |
| 130 | +``` |
| 131 | +pnpm start:dev |
| 132 | +``` |
| 133 | + |
| 134 | +## Testing |
| 135 | + |
| 136 | +This project uses Jest for testing. To run the tests, use the following command: |
| 137 | + |
| 138 | +``` |
| 139 | +pnpm test |
| 140 | +``` |
0 commit comments