Nx: управление монорепозиторием

Обзор

Kontinuum использует Nx для унифицированного управления backend (Rust), frontend (Vue 3) и docs (VitePress). Все команды запускаются из корня проекта.

Базовый синтаксис:

nx run <project>:<target>

# Примеры
nx run backend:build
nx run frontend:dev
nx run backend:test

Команды

Backend (Rust + Tauri)

# Сборка
nx run backend:build                  # Debug build
nx run backend:build:release          # Release build
nx run backend:build:headless         # Headless binary (release)
nx run backend:build:headless:debug   # Headless binary (debug, для e2e)
nx run backend:build:desktop          # Desktop app (→ gen:bindings → frontend:build)
nx run backend:build:desktop:release  # Release desktop app
nx run backend:build:android          # Android APK

# Development
nx run backend:dev                    # Tauri dev с hot reload
nx run backend:dev:headless           # Headless HTTP сервер

# Тестирование
nx run backend:test                   # Unit тесты
nx run backend:test:all               # Все тесты с features
nx run backend:test:integration       # Integration тесты
nx run backend:test:doc               # Doc тесты
nx run backend:test:coverage          # Coverage report

# Качество кода
nx run backend:lint                   # Clippy
nx run backend:fmt                    # Форматирование
nx run backend:fmt:check              # Проверка форматирования
nx run backend:audit                  # Security audit
nx run backend:outdated               # Устаревшие зависимости

# Утилиты
nx run backend:gen:bindings           # Генерация TypeScript биндингов (Specta)
nx run backend:clean                  # Очистка артефактов

Frontend (Vue 3 + TypeScript)

# Сборка
nx run frontend:build                 # Production build
nx run frontend:build:check           # Build с type checking
nx run frontend:build:web             # Web-режим (HTTP transport)

# Development
nx run frontend:dev                   # Dev сервер с HMR
nx run frontend:dev:web               # Dev в web-режиме (HTTP transport)
nx run frontend:dev:inspector         # Dev с HTTP транспортом для инспекции headless бекенда
nx run frontend:preview               # Preview production build

# Тестирование
nx run frontend:test                  # Vitest тесты
nx run frontend:test:ui               # UI для тестов
nx run frontend:test:coverage         # Coverage report
nx run frontend:test:watch            # Watch режим

# E2E (Playwright + headless backend)
nx run frontend:e2e                   # Headless (→ backend:build:headless:debug)
nx run frontend:e2e:headed            # С видимым браузером
nx run frontend:e2e:ui                # Интерактивный UI Playwright
nx run frontend:e2e:debug             # Пошаговая отладка
nx run frontend:e2e:list              # Список тестов
nx run frontend:e2e:report            # HTML-отчёт

# E2E: дополнительные возможности
nx run frontend:e2e -- e2e/app-load.spec.ts  # Конкретный тест
nx run frontend:e2e -- --last-failed         # Только упавшие тесты заново
npx playwright show-trace test-results/<test-folder>/trace.zip  # Trace упавшего теста

# Качество кода
nx run frontend:lint                  # ESLint
nx run frontend:lint:fix              # Автоисправление
nx run frontend:format                # Prettier
nx run frontend:format:check          # Проверка форматирования
nx run frontend:type-check            # TypeScript проверка
nx run frontend:audit                 # npm security audit

Примечание: Все e2e-команды (кроме e2e:list и e2e:report) автоматически собирают headless backend (backend:build:headless:debug) перед запуском. Playwright сам поднимает backend (порт 18080) и Vite в режиме e2e (порт 9000).

Documentation (VitePress + Kroki)

# Dev и build автоматически поднимают Kroki (Docker, порт 18484)
nx run docs:dev                       # Kroki ↑ + VitePress dev с hot reload
nx run docs:build                     # Kroki ↑ + PlantUML→SVG + VitePress build
nx run docs:preview                   # Превью собранного сайта (→ docs:build)

# Управление Kroki-сервером
nx run docs:kroki:up                  # Поднять Kroki отдельно
nx run docs:kroki:down                # Остановить Kroki

Интеграционные тесты

# Полный запуск: cargo build + observability + backends + тесты
nx run integration-tests:test:full

# Без сборки (binary уже собран)
nx run integration-tests:test

# С очисткой Docker после тестов
nx run integration-tests:test:clean

# Без завершения бекендов (для инспекции после тестов)
nx run integration-tests:test:inspect

# Observability стек
nx run integration-tests:observability:up
nx run integration-tests:observability:down

Ручной запуск runner.ts

cd infra/testing
npx tsx src/runner.ts [флаги]

# Один сценарий с подробными логами (без Docker)
npx tsx src/runner.ts --no-build --no-observability --scenario pairing --verbose

# Только бекенды без тестов (для ручной инспекции или Android pairing)
npx tsx src/runner.ts --no-build --no-observability --no-tests --verbose

# Инспекция бекендов после тестов (Ctrl+C для остановки)
npx tsx src/runner.ts --no-build --keep-alive --scenario sharing --verbose

Примечание: Для target'ов с : в имени (например test:full, observability:up) нужен явный синтаксис nx run project:target. Шортхенд nx project:target не работает — Nx парсит : как разделитель project/target/configuration.

Composite команды

# Все проекты
nx run-many --target=build --all
nx run-many --target=test --all --parallel=2
nx run-many --target=lint --all --parallel=2
nx run-many --target=format --all

# Только измененные (affected)
nx affected --target=test
nx affected --target=build
nx affected --target=lint
nx affected --target=test --base=origin/main --parallel=3

# Граф зависимостей
nx graph
nx affected:graph

Кэширование

Nx автоматически кэширует результаты задач. При повторном запуске без изменений результат возвращается мгновенно.

Что кэшируется: build, test, lint, format, gen:bindings, coverage.

Что НЕ кэшируется: dev-серверы, watch-режимы, e2e тесты, audit.

# Пропустить кэш
nx run backend:build --skip-nx-cache

# Очистить кэш
nx reset

Cache invalidation

Cache сбрасывается при изменении inputs:

• Backend: Cargo.toml, Cargo.lock, src/**/*.rs, build.rs, tauri.conf.json
• Frontend: package.json, src/**/*.{ts,vue,js}, vite.config.ts, tsconfig.json
• Docs: **/*.md, .vitepress/**/*

Зависимости между targets

build:desktop автоматически запускает генерацию биндингов и сборку frontend.

Типовые workflows

Начало работы

npm install
nx run backend:gen:bindings
nx run backend:dev

Перед коммитом

nx run-many --target=format --all
nx run-many --target=lint --all
nx run frontend:type-check
nx affected --target=test

CI/CD

nx affected --target=test --base=origin/main --parallel=3
nx affected --target=lint --base=origin/main --parallel=2
nx affected --target=build --base=origin/main

Release

nx run backend:gen:bindings
nx run frontend:build
nx run backend:build:desktop:release

Конфигурация

Файл	Назначение
nx.json	Глобальная конфигурация (кэширование, зависимости)
backend/project.json	Targets для backend
frontend/project.json	Targets для frontend
docs/project.json	Targets для документации (VitePress + Kroki)
infra/testing/project.json	Targets для интеграционных тестов

Troubleshooting

# Проверить список проектов и targets
nx show projects
nx show project backend

# Dry run (что будет выполнено)
nx run backend:build --dry-run

# Verbose output
nx run backend:build --verbose

# Очистить кэш и daemon
nx reset
nx daemon --stop && nx daemon --start