Skip to content

devex-tooling.md

Latest commit

 

History

History
262 lines (185 loc) · 9.04 KB

devex-tooling.md

File metadata and controls

262 lines (185 loc) · 9.04 KB
Raw

DevEx & Tooling — Vite/Turbo, pnpm, шаблоны, генераторы, SBOM

Цель: быстрый DX без боли. Один набор инструментов для всех команд. Контекст: standards, repo-structure, ci-cd, гейты: quality-gates, наблюдаемость: observability, контракты: backend-contracts, дизайн‑система: anyui.

0) TL;DR

  • Монорепа: pnpm + Turborepo с кэшом (локально и удалённо).
  • Сборка: Vite для приложений, tsup/rollup для библиотек.
  • Шаблоны и генераторы: packages/config/templates/* + Plop/Hygen.
  • Кодоген: OpenAPI → SDK (см. backend-contracts).
  • Тест‑набор: Vitest/RTL, Playwright, Storybook.
  • SBOM/лицензии: CycloneDX + license‑checker — в CI как гейты.

1) Стек и версии (минимум)

  • Node: LTS (фиксируем в .nvmrc или Volta).
  • pnpm: 9.x (workspace в корне).
  • TypeScript: strict (см. standards).
  • Vite: для apps/*.
  • tsup/rollup: для packages/* (AnyUI, utils, SDK).
  • Vitest + React Testing Library, Playwright, Storybook.

2) Общие конфиги (reuse вместо копипасты)

Всё лежит в packages/config/. Подключаем через extends/алиасы.

  • eslint-config: единые правила (см. standards).
  • tsconfig: tsconfig.base.json + профили для apps/packages.
  • vite-config: функция‑фабрика для Vite с алиасами и SBOM баннером.
  • jest/vitest пресеты, playwright базовый конфиг, storybook пресет.

Пример использования Vite-конфига:

// apps/web/vite.config.ts
import { defineAppViteConfig } from "@fsf/config/vite";
export default defineAppViteConfig({ appName: "web" });

3) Turborepo — пайплайны и кэш

turbo.json (расширение):

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "lint": { "outputs": [] },
    "typecheck": { "outputs": [] },
    "test": { "outputs": ["coverage/**"] },
    "build": { "dependsOn": ["^build", "typecheck"], "outputs": ["dist/**", ".next/**", "build/**"] },
    "storybook": { "outputs": ["storybook-static/**"] }
  },
  "globalDependencies": ["tsconfig.base.json", "packages/config/**"]
}

Удалённый кэш (по желанию):

# в CI/локально (env)
export TURBO_TOKEN=...
export TURBO_TEAM=fsf

Экономит минуты на сборках. Решение — через ADR, см. rfc-adr.

4) Скрипты верхнего уровня (единый UX)

{
  "scripts": {
    "dev": "turbo run dev --parallel",
    "lint": "turbo run lint",
    "typecheck": "turbo run typecheck",
    "test": "turbo run test",
    "build": "turbo run build",
    "storybook": "turbo run storybook",
    "sbom": "cyclonedx-bom -o sbom.json",
    "licenses": "license-checker-rseidelsohn --summary"
  }
}

Эти команды должны работать одинаково в любом приложении/пакете.

5) Шаблоны и генераторы

Где лежат: packages/config/templates/* Чем генерим: Plop (просто) или Hygen (гибко). Выбираем и фиксируем в ADR.

Примеры заготовок:

  • feature: каркас features/foo (ui/, model/, index.ts, stories, tests).
  • entity: каркас entities/user.
  • page: страница в pages/* + роут + сторисы.
  • widget: блок интерфейса (состояние/композиция).

Команды:

pnpm plop feature --name user-auth
pnpm plop page --name settings

Шаблоны учитывают правила слоёв (см. arch-principles).

6) Vite — быстрый и предсказуемый

Билд‑правила:

  • Код‑сплиты по роутам, динамические импорты для тяжёлых зон.
  • build.target = 'es2022', sourcemap: true (в staging), brotliSize: false (ускорение).
  • optimizeDeps — списком (скорость dev).

Разделение чанков (пример):

// vite.config.ts (фрагмент)
build: {
  rollupOptions: {
    output: {
      manualChunks: {
        vendor: ["react", "react-dom"],
        sentry: ["@sentry/react"],
      }
    }
  }
}

Порог бандла и Web Vitals — см. perf-budgets.

7) Сборка библиотек: tsup/rollup

  • AnyUI/utls/SDK публикуем как ESM + types.
  • tsup для простоты; rollup если нужны финт‑настройки (external, объявления стилей).

tsup.config.ts (минимум):

import { defineConfig } from "tsup";
export default defineConfig({
  entry: ["src/index.ts"],
  format: ["esm"],
  dts: true,
  clean: true,
  treeshake: true
});

8) Тесты и Storybook

  • Vitest: быстрые unit/component.
  • Playwright: критические E2E (см. гейты в quality-gates).
  • Storybook: MDX‑доки и визуальные тесты (Chromatic/скриншоты).

vitest.config.ts (фрагмент):

test: { globals: true, environment: "jsdom", setupFiles: ["./test/setup.ts"] }

storybook/main.ts (фрагмент):

addons: ["@storybook/addon-essentials"],
framework: { name: "@storybook/react-vite", options: {} }

9) Кодоген (OpenAPI) и моки

  • Генерим SDK из OpenAPI спеком в packages/api-sdk (см. backend-contracts).
  • Локально используем MSW (mock‑server) с теми же контрактами.
  • Контракт‑тесты (PACT) — опционально, через ADR.

10) SBOM и лицензии (supply chain)

  • SBOM: cyclonedx-bom генерит sbom.json для репы/приложения.
  • Лицензии: license-checker-rseidelsohn → отчёт об OSS лицензиях.
  • Эти шаги — обязательные в CI и гейтах (см. quality-gates).

Пример CI шага (псевдо):

- name: SBOM
  run: pnpm sbom
- name: Licenses
  run: pnpm licenses

11) Быстрый старт (новое приложение/пакет)

# Приложение
pnpm create app web  # или скрипт Platform: pnpm -w plop app --name web

# Пакет
pnpm -w plop package --name anyui

# Запуск
pnpm i
pnpm dev

После генерации: проверь алиасы/кодоген/Storybook. Готово к работе, гейты и наблюдаемость подключаются из коробки.

12) Производительность разработчика

  • Инкрементальная проверка типов (tsc --build).
  • Быстрые проверка/формат eslint --cache + Prettier.
  • Remote cache Turbo для тяжёлых сборок.
  • Анализ бандла: @bundle-stats/cli или rollup-plugin-visualizer (репорты кидаем в артефакты CI).

13) Безопасность в DX

  • Никаких секретов в .env.example (см. security-a11y).
  • Скан зависимостей и лицензий — в PR (SBOM/OSS отчёты — часть гейтов).
  • Генераторы добавляют безопасные дефолты (aria‑атрибуты, токены AnyUI).

14) DoR/DoD (для задач Platform/DX)

Ready: понятный сценарий (кому/зачем), измеримая метрика выигрыша (время сборки/регрессии). Done: шаблон/генератор опубликован, документация в этом файле обновлена, шаги в CI добавлены, метрика улучшилась.

15) Быстрая навигация