https://github.com/typv/nest-turbo-starter
A NestJS monorepo starter kit for building scalable microservices with Turborepo and pnpm.
https://github.com/typv/nest-turbo-starter
api-gateway apisix boilerplate microservices nest-turbo-starter nestjs nestjs-boilerplate nestjs-microservices nestjs-monorepo nestjs-monorepo-starter nestjs-starter nestjs-turborepo nestjs-turborepo-starter turborepo typescript
Last synced: about 1 month ago
JSON representation
A NestJS monorepo starter kit for building scalable microservices with Turborepo and pnpm.
- Host: GitHub
- URL: https://github.com/typv/nest-turbo-starter
- Owner: typv
- License: mit
- Created: 2025-11-13T04:45:31.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-04-21T17:05:49.000Z (about 1 month ago)
- Last Synced: 2026-04-21T18:25:48.250Z (about 1 month ago)
- Topics: api-gateway, apisix, boilerplate, microservices, nest-turbo-starter, nestjs, nestjs-boilerplate, nestjs-microservices, nestjs-monorepo, nestjs-monorepo-starter, nestjs-starter, nestjs-turborepo, nestjs-turborepo-starter, turborepo, typescript
- Language: TypeScript
- Homepage:
- Size: 41.8 MB
- Stars: 177
- Watchers: 0
- Forks: 36
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# 🧠 Nest Turbo Starter
A high-performance, monorepo microservices platform built with NestJS, optimized for speed using Turborepo and the pnpm package manager. The system is containerized with Docker and features dynamic traffic management and security via API Gateway (Apache APISIX / Kong).
# 📑 Table of Contents
* [🚀 Getting Started](#-getting-started)
* [🏗️ System Architecture](#-system-architecture)
* [📦 Monorepo Structure](#-monorepo-structure)
* [✅ Tech Stacks](#-tech-stacks)
* [🛠️ Installation Preparation](#-installation-preparation)
* [🧑💻 Build](#-build)
* [Prerequisites](#prerequisites)
* [Environment Setup](#environment-setup)
* [Install Dependencies](#install-dependencies-1)
* [Build Applications](#build-applications)
* [Run Database Migrations](#run-database-migrations-1)
* [Start Microservices](#start-microservices-1)
* [🌐 API Gateway Configuration](#-api-gateway-configuration)
* [Apache APISIX (Default Gateway)](#apache-apisix-default-gateway)
* [Kong Gateway (Alternative Option)](#kong-gateway-alternative-option)
* [🌍 Access URLs](#-access-urls)
* [🧭 API Gateways](#-api-gateways)
* [⚙️ Microservices](#-microservices)
* [🧰 Tools & Management UI](#-tools--management-ui)
* [🔐 Demo API — Sign-Up & Login (cURL)](#-demo-api--sign-up--login-curl)
* [Sign-Up](#sign-up)
* [Login](#login)
* [📘 Notes](#-notes)
# 🚀 Getting Started
## ✨ Key Concepts (Monorepo & Performance)
This starter uses a Monorepo structure managed by **Turborepo** and **pnpm** to maximize performance and simplify development across multiple microservices.
---
## 🏗️ System Architecture
This project implements a robust, containerized microservices architecture designed for high availability and scalability. All core services-built on NestJS and Node.js-reside within a secure Private Subnet, adhering to the principle of service autonomy where each microservice owns its PostgreSQL database. External client requests are strictly managed by Apache APISIX, which serves as the central API Gateway for routing, security, and policy enforcement via HTTP. Internal service-to-service communication is handled via efficient TCP connections, while Kafka is optionally integrated to enable scalable, asynchronous communication and event-driven processing, minimizing service coupling.
---
## 📦 Monorepo Structure
```bash
apps/
auth-service/
user-service/
...
libs/
common/
core/
...
config/
apisix/
kong/
```
---
## ✅ Tech Stacks
### 🚀 Core Backend
| Component | Version | Description |
|------------------|---------|---------------------------------------|
| Node.js | 22.15 | JavaScript runtime |
| NestJS | 11 | Backend framework |
| TypeScript | 6.x | Type-safe language |
| PostgreSQL | 16 | Main relational DB |
| MikroORM | 7.x | ORM |
| Redis | 8.0 | Cache & queue backend |
| pnpm | 10.x | Monorepo package manager |
| Kafka (optional) | 4.x | Event streaming & async communication |
### 🌐 API Gateway & Service Mesh
| Component | Version | Description |
|------------|----------|-------------|
| Apache APISIX | 3.14 | Default API Gateway |
| Etcd | 3.5.1 | APISIX config store |
| Kong | 3.12 | Optional alternative gateway |
### Infrastructure & DevOps
| Component | Version | Description |
|------------|----------|-------------|
| Docker / Compose | latest | Containerization |
| ADC | latest | APISIX config sync |
| deck | latest | Kong config sync |
| Redis Insight | latest | Redis visualization |
| Kafka UI | latest | Kafka management UI |
| Kong Manager | 3.12 | Kong dashboard |
### 🧰 Developer Tools
| Tool | Description |
|------|--------------|
| ESLint / Prettier | Linting & formatting |
| Jest | Unit testing |
| Swagger | API documentation |
| Husky + lint-staged | Git pre-commit checks |
| Dotenv | Env management |
---
## 🛠️ Installation Preparation
1. **Default Base Path**
```bash
/home/app.user/nest-turbo-starter
```
2. **Environment Variables**
Copy the sample environment file:
```bash
cp .env.example .env
```
```bash
cd apps/service_name & cp .env.example .env
```
> ⚠️ **Note:**
> - The project require additional environment variables both at the **root** of the monorepo/turborepo and for each individual microservice
> - Make sure to add these variables of **root** to turbo.json (or your monorepo configuration)
---
# 🧑💻 Build
---
### Prerequisites
#### Setup Docker
Build and start all containers:
```bash
docker compose up -d --build
```
#### `pnpm` installed globally:
```bash
npm install -g pnpm
```
#### Environment Setup
Copy and configure environment variables:
```bash
cp .env.example .env
```
Edit `.env` with correct values for database, Redis, Kafka, and gateway settings.
---
### Install Dependencies
Install all workspace dependencies:
```bash
pnpm install
```
Or install only for a single service:
```bash
pnpm --filter=auth-service install
```
---
### Build Applications
Build all microservices:
```bash
pnpm build
```
Or build one specific service:
```bash
pnpm --filter=auth-service build
```
---
### Run Database Migrations
Run migrations for all services:
```bash
pnpm migration:up
```
Or for one service:
```bash
pnpm --filter=auth-service migration:up
```
---
### Start Microservices
#### Development mode
Start all services:
```bash
pnpm dev
```
Start one specific service:
```bash
pnpm dev --filter=auth-service
```
#### Production mode
### 1. Check types
To ensure type safety while using the high-speed SWC compiler (which skips type-checking during transpilation), you should run the following command before building or committing code:
Check all services:
```bash
pnpm check-types
```
Check a specific service:
```bash
pnpm --filter=service_name check-types
```
---
### 2. [Build Applications](#build-applications)
### 3. Run production mode
Start all services:
```bash
pnpm prod
```
Start one specific service:
```bash
pnpm prod --filter=auth-service
```
---
## 🌐 API Gateway Configuration
> ⚠️ **Note:**
> - The current setup uses **Kong Gateway (Free / OSS Edition)**, which lacks several advanced enterprise features such as rate limiting, JWT key rotation, analytics, and RBAC management.
> - To address these limitations and support more advanced features, **Apache APISIX** is chosen as the **default API gateway** for this system.
> - Key reasons include:
> - Free & open source
> - High performance and low latency
> - Easy integration with etcd for declarative configuration
> - Rich plugin ecosystem (rate limiting, JWT auth, logging, etc.)
> - Active community and rapid development
> - The system is currently under active development to integrate and extend these features.
### Apache APISIX (Default Gateway)
#### Sync configuration from file
```bash
docker compose run --rm adc adc sync -f conf/apisix-${environment}.yaml
# Example:
docker compose run --rm adc adc sync -f conf/apisix-dev.yaml
```
#### Dump configuration from DB for verification
```bash
docker compose run --rm adc adc dump -o adc/adc.yaml
```
---
### Kong Gateway (Alternative Option)
Sync configuration using `deck`:
```bash
docker compose run --rm kong-deck gateway sync /app/kong-dev.yaml
```
---
# 🌍 Access URLs
## 🧭 API Gateways
| Gateway | URL Example |
|------------------| ------------------------------------------------------------------------------ |
| **APISIX Node** | [http://localhost:`APISIX_NODE_LISTEN`](http://localhost:`APISIX_NODE_LISTEN`) |
| **Kong Gateway** | http://localhost:18088 |
---
## ⚙️ Microservices
| Type | Example |
|------------------|------------------------------------------------------------------------------------------|
| **Direct Access** | http://localhost:port/api |
| **Via APISIX** | http://localhost:`APISIX_NODE_LISTEN`/`service_name`/api |
| Example | [http://localhost:9080/auth-service/api](http://localhost:9080/auth-service/api) |
| Swagger | [http://localhost:9080/auth-service/swagger](http://localhost:9080/auth-service/swagger) |
---
## 🧰 Tools & Management UI
| Tool | URL |
| ------------- | ------------------------------------------------ |
| Redis Insight | [http://localhost:5534](http://localhost:5534) |
| Kafka UI | [http://localhost:18082](http://localhost:18082) |
| Kong Manager | [http://localhost:18086](http://localhost:18086) |
| APISIX Dashboard| http://localhost:`APISIX_DEPLOYMENT_ADMIN_LISTEN`/ui |
---
# 🔐 Demo API — Sign-Up & Login (cURL)
## Sign-Up
```bash
curl --location --request POST 'http://0.0.0.0:9080/auth-service/api/auth/sign-up' \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "test@example.com",
"password": "12345678Aa@"
}'
```
## Login
```bash
curl --location --request POST 'http://0.0.0.0:9080/auth-service/api/auth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "test@example.com",
"password": "12345678Aa@"
}'
```
---
# 📘 Notes
* Make sure `.env` and configuration files (`apisix-*.yaml`, `kong-*.yaml`) are properly set before running migrations or gateway sync commands.
* Use `pnpm --filter=` to target specific microservices efficiently.
* If using Docker, ensure Docker and Docker Compose are running before executing commands.
* If Git Pre-commit (Husky) is not working:
* Run `pnpm prepare`.
* For Linux/macOS users, grant execution permission: chmod +x .husky/pre-commit.
* Verify the hooks path by running: git config core.hooksPath. It should return .husky.
---
**© Nest Turbo Starter — Monorepo, Microservice Backend System**