Универсальный монорепозиторий для быстрого старта веб-проектов любого масштаба: SaaS, маркетплейсы, MVP, интернет-магазины, блоги, панели управления и не только. Шаблон уже содержит базовую архитектуру, рабочую БД, API и фронтенд, чтобы ты не тратил время на рутину и сразу начинал писать бизнес-логику.
Этот проект — готовая отправная точка для продукта, который нужно быстро собрать, запустить локально и затем выкатить в продакшн.
Это монорепозиторий на базе Turbo + pnpm с двумя основными приложениями:
apps/web— фронтенд на Next.js 16 + React 19 + App Routerapps/api— бэкенд на NestJS 12 + TypeScriptpackages/ui— переиспользуемые компонентыdocker-compose.yml— PostgreSQL 17 для локальной разработки
| Компонент | Технология | Зачем выбран |
|---|---|---|
| Монорепозиторий | Turborepo + pnpm | Быстрые сборки, общий dependency graph, удобное управление несколькими приложениями |
| Фронтенд | Next.js 16 + React 19 | Современный App Router, SSR/SSG, производительность и экосистема React |
| Стилизация | Panda CSS | Zero-runtime CSS, типобезопасные стили, удобно для дизайн-систем |
| Бэкенд | NestJS 12 | Структурный и масштабируемый backend для API, хорошая архитектура и DX |
| База данных | PostgreSQL 17 + Drizzle ORM | Надёжная SQL-база и простой, типобезопасный ORM |
| Контейнеризация | Docker + Docker Compose | Локальная разработка и запуск сервисов без геморроя с зависимостями |
| Язык | TypeScript (strict) | Безопасность типов, меньше ошибок на ранних этапах |
Перед запуском убедись, что всё установлено и работает.
| Инструмент | Версия | Как проверить |
|---|---|---|
| Node.js | 24+ | node -v |
| pnpm | 11+ | pnpm -v |
| Docker Desktop / Docker Engine | актуальная версия | docker --version |
| Git | любая актуальная | git --version |
# Node.js 24+
# Скачай с официального сайта: https://nodejs.org/
# pnpm
npm install -g pnpm
# Проверка
node -v
pnpm -vДля Docker:
- macOS / Windows: установи Docker Desktop
- Linux: установи Docker Engine + Docker Compose
Проверка Docker:
docker --version
docker compose versionЕсли
node -vпоказывает версию ниже 24, обнови Node.js. Иначе проект может вести себя странно.
Ниже — полный путь "с нуля" до работающего проекта.
git clone https://github.com/SkvizyBoy/universal-boilerplate.git my-project
cd my-projectpnpm installЕсли видишь ошибку вида ERR_PNPM_IGNORED_BUILDS, смотри раздел "Решение проблем" ниже. В этом шаблоне она уже исправляется через pnpm-workspace.yaml.
В этом проекте .env.example лежит в apps/api:
Copy-Item apps\api\.env.example apps\api\.envЕсли ты используешь Bash/Zsh или macOS/Linux, то команда будет такой:
cp apps/api/.env.example apps/api/.envСодержимое файла:
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/app_db"Важно: это переменная для PostgreSQL, который запускается через Docker Compose.
docker compose up -dЭто поднимет контейнер с PostgreSQL 17 и создает базу app_db.
Проверить контейнеры:
docker compose psИз папки apps/api:
cd apps/api
pnpm exec drizzle-kit pushИли из корня проекта:
pnpm --dir apps/api exec drizzle-kit pushЭта команда создаёт/обновляет таблицы по схеме из apps/api/src/db/schema.ts.
Из корня проекта:
cd ..
pnpm devЕсли работаешь в корне, то просто:
pnpm devЭто запустит Turbo, и монорепозиторий поднимет все приложения.
- Веб:
http://localhost:3000 - API:
http://localhost:3001(если не переопределён черезPORT)
Если порт 3000 занят в локальной машине, останови конфликтующий процесс или задай отдельный порт для API через переменную
PORTперед запуском.
После запуска можно быстро проверить, что API живой и отвечает корректно:
curl http://localhost:3001Ожидаемый ответ:
Hello World!
В чистом шаблоне API не содержит маркетплейс-эндпоинтов, поэтому проверка по корневому роуту — правильный и стабильный smoke-test.
Если репозитория ещё нет, делай так.
git init
git add .
git commit -m "Initial commit"
gh auth login
gh repo create my-project --public --source=. --remote=origin --pushgit remote add origin https://github.com/ВАШ_НИК/ВАШ_РЕПОЗИТОРИЙ.git
git branch -M main
git push -u origin maingit add .
git commit -m "feat: initial setup"
git push origin mainНиже — два основных варианта.
Это хороший вариант, если хочешь полностью контролировать окружение и не зависеть от платформенных ограничений.
Подходит любой VPS с Ubuntu 22.04/24.04 и минимум 2 vCPU / 4 GB RAM.
ssh root@IP_ВАШЕГО_VPSapt update
apt install -y ca-certificates curl gnupg
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" \
| tee /etc/apt/sources.list.d/docker.list > /dev/null
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-pluginПроверь:
docker --version
docker compose versionapt install -y git
mkdir -p /var/www
cd /var/www
git clone <URL_ВАШЕГО_РЕПОЗИТОРИЯ> my-project
cd my-projectcp apps/api/.env.example apps/api/.env
nano apps/api/.envПример:
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/app_db"docker compose up -dpnpm install
cd apps/api
pnpm build
cd ../web
pnpm buildВ типичной схеме для этого монорепозитория:
- Web запускается на
3000 - API запускается на
3001
Для NestJS API:
cd /var/www/my-project/apps/api
PORT=3001 NODE_ENV=production pnpm start:prodДля Next.js Web:
cd /var/www/my-project/apps/web
PORT=3000 NODE_ENV=production pnpm startВ продакшне лучше запускать через
systemd,PM2или Docker-контейнеры, но выше — минимально рабочая схема. Явно задавайте порты в конфиге, чтобы не было путаницы между API и frontend.
Если у тебя есть домен, обычно делают так:
- API на
api.example.com - Web на
example.com - Nginx или Caddy проксирует запросы к локальным портам
Пример Nginx для frontend:
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}Для API можно добавить отдельный блок:
server {
listen 80;
server_name api.example.com;
location / {
proxy_pass http://127.0.0.1:3001;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}Если вам нужен максимально простой деплой фронтенда, Vercel подходит идеально.
git add .
git commit -m "ready for deploy"
git push origin main- Открой https://vercel.com
- Нажми Add New Project
- Выбери GitHub-репозиторий
- В качестве root folder укажи
apps/web - Framework preset: Next.js
Для Next.js обычно нужны переменные вида:
NEXT_PUBLIC_API_URL=https://api.example.comVercel сам соберёт и задеплоит проект.
Для production API обычно всё равно нужен отдельный хостинг или контейнер, например VPS, Railway, Render, Fly.io, Azure App Service и т.д.
| Команда | Что делает |
|---|---|
docker compose up -d |
Запускает контейнеры в фоне |
docker compose down |
Останавливает и удаляет контейнеры |
docker compose down -v |
Останавливает контейнеры и удаляет тома (полный сброс БД) |
docker compose ps |
Показывает список запущенных контейнеров |
docker compose logs -f |
Смотрит логи всех сервисов |
docker compose logs -f db |
Смотрит только логи PostgreSQL |
docker compose restart db |
Перезапускает конкретный сервис |
docker exec -it app_db psql -U postgres -d app_db |
Подключается к PostgreSQL из контейнера |
Примеры:
docker compose up -d
docker compose logs -f db
docker compose down
docker compose down -vОткрывай файл apps/api/src/db/schema.ts и добавляй таблицы через pgTable.
Пример:
import { pgTable, timestamp, uuid, varchar } from "drizzle-orm/pg-core";
export const posts = pgTable("posts", {
id: uuid("id").primaryKey().defaultRandom(),
title: varchar("title", { length: 255 }).notNull(),
slug: varchar("slug", { length: 255 }).notNull().unique(),
createdAt: timestamp("created_at").defaultNow().notNull(),
});После этого:
- создай логику работы с таблицей в сервисах/контроллерах
- затем применяй миграции
Для быстрого синка схемы с локальной БД:
cd apps/api
pnpm exec drizzle-kit pushИспользуй это в локалке, когда тебе не нужна сложная миграционная схема.
Для продакшена обычно делают так:
cd apps/api
pnpm db:generate
pnpm db:migrateИли напрямую:
pnpm exec drizzle-kit generate
pnpm exec drizzle-kit migrateПорядок логичный:
generate— создаёт SQL-миграции по изменениям схемыmigrate— применяет их к базе
Чтобы визуально посмотреть БД и таблицы:
cd apps/api
pnpm db:studioОбычно Drizzle Studio открывается в браузере по адресу:
http://localhost:4983
Причина: pnpm по умолчанию блокирует некоторые native builds (например, esbuild, @parcel/watcher, sharp).
Решение: добавь секцию allowBuilds в корневой pnpm-workspace.yaml.
packages:
- "apps/*"
- "packages/*"
allowBuilds:
'@parcel/watcher': true
esbuild: true
sharp: trueПосле этого:
pnpm installВ этом проекте такая настройка уже есть, поэтому проблема обычно исчезает после переустановки зависимостей.
Это значит, что PostgreSQL контейнер был запущен, но база с нужным названием не создалась или в volume остались старые данные.
Решение:
docker compose down -v
docker compose up -dЗатем снова примените схему:
cd apps/api
pnpm exec drizzle-kit pushИли просто удалите том postgres_data и поднимите контейнер заново.
Причина: либо файл удалён, либо ты запускаешь команду не из нужной директории, либо dependencies не установлены.
Проверить файл:
ls apps/webДолжен быть файл:
apps/web/panda.config.ts
Если файл есть, установи зависимости и сгенерируй styled-system:
cd apps/web
pnpm install
pnpm prepareЕсли ошибки всё равно есть, проверь, что ты запускаешь команды из корня проекта и что panda.config.ts не был случайно удалён.
Проверь:
docker ps
docker compose logs -f dbУбедись, что Docker Desktop запущен, а порт 5432 не занят другим сервисом.
Попробуй:
pnpm install
pnpm devИли запустите приложения вручную:
cd apps/api
pnpm install
pnpm start:devcd apps/web
pnpm install
pnpm devЕсли ты уже знаком с проектом, вот минимальный список действий:
-
pnpm install -
cp apps/api/.env.example apps/api/.env -
docker compose up -d -
cd apps/api && pnpm exec drizzle-kit push -
pnpm dev - Открыть фронтенд и API
- Расширить
schema.tsпод свою доменную модель - Закоммитить/запушить изменения
- Подготовить деплой и переменные окружения для production
Если тебе нужен быстрый старт для любого веб-продукта, этот шаблон уже даёт:
- современный стек
- готовый монорепозиторий
- PostgreSQL в Docker
- NestJS API
- Next.js фронтенд
- Panda CSS
- TypeScript
- Drizzle ORM
То есть ты можешь сразу думать о продукте, а не о настройке инфраструктуры.
Если хочешь, следующим сообщением я могу сразу подготовить ещё и:
apps/api/.env.exampleв более "продакшн"-варианте- шаблон
docker-compose.prod.yml - пример
.github/workflows/ci.yml - структуру для SaaS/маркетплейса/блога на базе этого монорепозитория