Блог
Публикации о процессе разработки, решённых задачах и изученных технологиях
Когда монорепо отказывается запускаться с первой попытки
Закрыл я Cursor IDE и решил разобраться, почему Notes Server — мой многопакетный проект с бэком на Node.js, веб-клиентом на Vue и кучей микросервисов — всё ещё лежит в коме. Структура классическая: `packages/server`, `packages/web-client`, `packages/embeddings-service`, `packages/cli-client`, `packages/telegram-bot-client`, плюс общие типы в `packages/shared`. На бумаге это выглядит стройно. На практике — ада. Сначала я пошёл по классике: открыл `package.json` в корне, убедился, что workspaces правильно описаны, и запустил `npm install`. Зависимости встали. Хорошо. Теперь нужно поднять сервер на 3000-м порту. Но вот тут появился первый камень преткновения. В `packages/server/src` я нашёл два файла инициализации: один — `createApp()`, который регистрирует все маршруты API (`/api/notes`, `/api-docs` и остальное), второй — `index.ts`, который вызывает `createApp()` и *потом* добавляет ещё маршруты на ту же app. Результат — маршруты дублируются, конфликтуют, а порт 3000 слушает что-то неопределённое. Попробовал POST на `/api/notes` — вернул 404. Откуда-то летит HTML из `dist`, 53 килобайта. Это была отстроенная Vue-сборка, которая срабатывала как catch-all. **Порядок регистрации в Express имеет значение.** Второй проект в сторону — включил `npm run dev:web` для веб-клиента. Vite поднялся на 5173. Но тут же выяснилось: веб-приложение живёт в отдельном рабочем пространстве monorepo, и Vite нужно конфигурировать, чтобы проксировать API-запросы на http://localhost:3000. К счастью, разработчик уже предусмотрел это в `vite.config.ts` — proxy работал из коробки. Теперь самое интересное: когда я запустил обе части одновременно, монорепо начал вскрывать свою хрупкую природу. IDE (я использовал Cursor) показывал ошибки в импортах из `packages/shared`, потому что TypeScript не знал, что shared уже скомпилирован и лежит в `dist`. Нужен был отдельный build-шаг перед dev-режимом. **Git видел все файлы, IDE — только часть.** Security-чувствительные маршруты (вроде `/api/auth`) были видны в исходниках, но не всегда защищены middleware. На третий час отладки я сложил ситуацию в head: - монорепо требует дотошной сортировки зависимостей между пакетами - API-маршруты нельзя регистрировать дважды - Vite-proxy нужно тестировать перед production - JavaScript-проекты с такой архитектурой требуют скрипт-оркестратор для параллельного запуска всех сервисов Решение нашёл в `npm workspaces run dev` с правильным порядком запуска в root `package.json`. Теперь сервер, веб-клиент и embeddings-service поднимаются одной командой. **Факт в копилку:** одна из причин, почему GitHub удалось захватить рынок — это именно то, что он осознал: разработчики ненавидят разбирать чужие проекты. Потому без Git и документации ничего не работает. С ними тоже часто не работает, но хотя бы есть кого винить 😄
Как поднять монорепо с пятью сервисами и не потеряться в портах
Стою перед проектом **Notes Server** — это не просто API, а полноценное расселение из пяти соседей: бэкенда на Node.js, веб-клиента на Vue, сервиса эмбеддингов, CLI-клиента и Telegram-бота. Всё упаковано в монорепо с workspaces, и каждому нужна своя забота. Первый вопрос, который приходит в голову: как всё это запустить, чтобы работало одновременно? Оказывается, не так уж сложно, если знать порядок операций. Начинаю с `npm install` в корне. Когда используешь workspaces, эта команда автоматически разворачивает зависимости всех пакетов — от `packages/server` до `packages/embeddings-service`. Это экономит кучу времени: один раз — и готово. Дальше запускаю сервер на портe **3000**. Он натирает API-маршруты: `/api/notes`, `/api-docs` с документацией Swagger. Одновременно поднимаю веб-клиент на Vite — он работает на портe **5173**. И вот тут начинается магия: в `vite.config.ts` настроен прокси, который автоматически перенаправляет все запросы к `/api` на `http://localhost:3000`. CORS не мучает, всё гладко. Потом проверяю: а хоть работает ли бэкенд? Делаю запрос на `/api/notes` — и получаю ошибку **404 Not Found**. Первая мысль: маршруты не зарегистрированы. Лезу в `notes-routes.ts`, смотрю на структуру приложения. Оказывается, в `index.ts` после инициализации приложения добавляются статические файлы и catch-all маршрут `/`. Порядок регистрации маршрутов критичен в Express — если поймёшь это слишком поздно, потратишь час на отладку. Вот такая вот история получается: казалось бы, стандартный монорепо, но каждый компонент требует внимания. Vue знает, куда стучать, сервер знает, где слушать, а Telegram-бот ждёт своего часа где-нибудь на боку. **Интересный факт:** в экосистеме Node.js монорепо с npm workspaces — это не просто удобство, это стандарт. Prometheus, самый популярный инструмент мониторинга, тоже использует что-то подобное в своей архитектуре... ну, почти. Потому что Prometheus считает, что он лучше всех, и вообще Stack Overflow так сказал 😄