@martinffx/atelier 1.4.0 → 3.0.0

package/skills/typescript-build-tools/SKILL.md

@@ -1,447 +0,0 @@
----
-name: typescript-build-tools
-description: TypeScript project tooling with Bun, tsgo, Vitest, Biome, and Turborepo. Use when setting up package.json scripts, running builds, typechecking, configuring tests, linting, formatting, or orchestrating monorepo development.
-user-invocable: false
----
-
-# TypeScript Build Tools
-
-Modern TypeScript build tooling stack: Bun for package management and task running, tsgo for typechecking, Vitest for testing, Biome for linting/formatting, and Turborepo for monorepo orchestration.
-
-## Additional References
-
-- [references/bun.md](./references/bun.md) - Bun package manager and task runner
-- [references/vitest.md](./references/vitest.md) - Advanced Vitest configuration patterns
-- [references/biome.md](./references/biome.md) - Biome rules and customization
-- [references/turborepo.md](./references/turborepo.md) - Turborepo monorepo orchestration
-
-## Quick Start
-
-```bash
-# Install dependencies
-bun add -D vitest @vitest/coverage-v8 @biomejs/biome
-
-# For monorepos
-bun add -D turbo
-```
-
-## Package.json Scripts
-
-### Single Package
-
-```json
-{
-  "scripts": {
-    "dev": "bun run --watch src/index.ts",
-    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
-    "typecheck": "tsgo --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "lint": "biome check .",
-    "lint:fix": "biome check --write .",
-    "format": "biome format --write .",
-    "check": "bun run typecheck && bun run lint && bun run test"
-  }
-}
-```
-
-### Monorepo Root
-
-```json
-{
-  "scripts": {
-    "dev": "turbo dev",
-    "build": "turbo build",
-    "typecheck": "turbo typecheck",
-    "test": "turbo test",
-    "lint": "turbo lint",
-    "check": "turbo typecheck lint test"
-  }
-}
-```
-
-## Bun
-
-### Package Manager
-
-```bash
-# Install dependencies
-bun install
-
-# Add dependencies
-bun add fastify drizzle-orm
-bun add -D vitest @biomejs/biome
-
-# Remove dependency
-bun remove package-name
-
-# Update dependencies
-bun update
-```
-
-### Task Runner
-
-**Important:** Use `bun run test` (not `bun test`) on Node projects. `bun test` invokes Bun's native test runner, not your package.json test script.
-
-```bash
-# Run script from package.json
-bun run dev
-bun run test
-bun run build
-
-# Run TypeScript directly (no build step)
-bun run src/index.ts
-
-# Watch mode
-bun run --watch src/index.ts
-
-# With environment variables
-bun run --env-file .env src/index.ts
-```
-
-### Build Command
-
-```bash
-# Basic build for Bun runtime
-bun build ./src/index.ts --outdir ./dist --target bun
-
-# For Node.js runtime
-bun build ./src/index.ts --outdir ./dist --target node
-
-# With minification
-bun build ./src/index.ts --outdir ./dist --target bun --minify
-
-# Multiple entry points
-bun build ./src/index.ts ./src/worker.ts --outdir ./dist --target bun
-```
-
-See [references/bun.md](./references/bun.md) for bunfig.toml configuration and advanced patterns.
-
-## tsgo Typechecking
-
-tsgo is a fast TypeScript typechecker. Use it instead of `tsc` for faster CI builds.
-
-```bash
-# Typecheck without emitting
-tsgo --noEmit
-
-# Typecheck specific files
-tsgo --noEmit src/**/*.ts
-
-# With project reference
-tsgo --noEmit -p tsconfig.json
-```
-
-### tsconfig.json
-
-```json
-{
-  "compilerOptions": {
-    "target": "ESNext",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "skipLibCheck": true,
-    "noEmit": true,
-    "esModuleInterop": true,
-    "resolveJsonModule": true,
-    "isolatedModules": true,
-    "verbatimModuleSyntax": true,
-    "lib": ["ESNext"],
-    "types": ["bun-types"]
-  },
-  "include": ["src/**/*.ts"],
-  "exclude": ["node_modules", "dist"]
-}
-```
-
-## Vitest
-
-### Basic Configuration
-
-```typescript
-// vitest.config.ts
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    globals: true,
-    environment: 'node',
-    include: ['src/**/*.test.ts', 'test/**/*.test.ts'],
-    coverage: {
-      provider: 'v8',
-      reporter: ['text', 'json', 'html'],
-      include: ['src/**/*.ts'],
-      exclude: ['src/**/*.test.ts', 'src/types/**'],
-    },
-  },
-})
-```
-
-### With Path Aliases
-
-```typescript
-// vitest.config.ts
-import { defineConfig } from 'vitest/config'
-import tsconfigPaths from 'vite-tsconfig-paths'
-
-export default defineConfig({
-  plugins: [tsconfigPaths()],
-  test: {
-    globals: true,
-  },
-})
-```
-
-### Global Setup (Database Migrations)
-
-```typescript
-// vitest.config.ts
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    globals: true,
-    globalSetup: './test/global-setup.ts',
-    setupFiles: ['./test/setup.ts'],
-  },
-})
-```
-
-```typescript
-// test/global-setup.ts
-import { execSync } from 'node:child_process'
-
-export async function setup() {
-  console.log('Running database migrations...')
-  execSync('drizzle-kit migrate', { stdio: 'inherit' })
-}
-
-export async function teardown() {
-  console.log('Test teardown complete')
-}
-```
-
-See [references/vitest.md](./references/vitest.md) for workspace configs, benchmarks, and Cloudflare Workers pool.
-
-## Biome
-
-### Basic biome.json
-
-```json
-{
-  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
-  "vcs": {
-    "enabled": true,
-    "clientKind": "git",
-    "useIgnoreFile": true
-  },
-  "files": {
-    "ignoreUnknown": true,
-    "ignore": ["dist", "node_modules", "*.gen.ts"]
-  },
-  "formatter": {
-    "enabled": true,
-    "indentStyle": "tab",
-    "lineWidth": 100
-  },
-  "javascript": {
-    "formatter": {
-      "quoteStyle": "double",
-      "trailingCommas": "es5"
-    }
-  },
-  "linter": {
-    "enabled": true,
-    "rules": {
-      "recommended": true
-    }
-  },
-  "organizeImports": {
-    "enabled": true
-  }
-}
-```
-
-### Strict Rules (Production)
-
-```json
-{
-  "linter": {
-    "enabled": true,
-    "rules": {
-      "recommended": true,
-      "complexity": {
-        "noForEach": "error"
-      },
-      "performance": {
-        "noDelete": "error"
-      },
-      "style": {
-        "useNodejsImportProtocol": "error"
-      }
-    }
-  }
-}
-```
-
-See [references/biome.md](./references/biome.md) for rule explanations, shareable configs, and CLI commands.
-
-## Turborepo (Monorepo)
-
-### turbo.json
-
-```json
-{
-  "$schema": "https://turbo.build/schema.json",
-  "tasks": {
-    "build": {
-      "dependsOn": ["^build"],
-      "outputs": ["dist/**"]
-    },
-    "typecheck": {
-      "dependsOn": ["^typecheck"]
-    },
-    "lint": {},
-    "test": {
-      "dependsOn": ["^build"],
-      "env": ["DATABASE_URL"]
-    },
-    "dev": {
-      "cache": false,
-      "persistent": true
-    }
-  }
-}
-```
-
-### Workspace Structure
-
-```
-my-monorepo/
-├── package.json          # Root with turbo scripts
-├── turbo.json            # Turbo configuration
-├── biome.json            # Shared Biome config
-├── packages/
-│   ├── config-biome/     # Shareable Biome package
-│   └── shared/           # Shared utilities
-├── apps/
-│   ├── api/              # Fastify API
-│   └── web/              # React app
-└── bun.lock
-```
-
-See [references/turborepo.md](./references/turborepo.md) for caching strategies, filtering, and CI setup.
-
-## Cloudflare Workers
-
-### Vite + Cloudflare Plugin
-
-```typescript
-// vite.config.ts
-import { cloudflare } from '@cloudflare/vite-plugin'
-import { reactRouter } from '@react-router/dev/vite'
-import tailwindcss from '@tailwindcss/vite'
-import tsconfigPaths from 'vite-tsconfig-paths'
-import { defineConfig } from 'vite'
-
-export default defineConfig({
-  plugins: [
-    cloudflare({ viteEnvironment: { name: 'ssr' } }),
-    tailwindcss(),
-    reactRouter(),
-    tsconfigPaths(),
-  ],
-})
-```
-
-### Vitest with Cloudflare Workers Pool
-
-```typescript
-// vitest.config.ts
-import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config'
-
-export default defineWorkersConfig({
-  test: {
-    globals: true,
-    pool: '@cloudflare/vitest-pool-workers',
-    poolOptions: {
-      workers: {
-        wrangler: { configPath: './wrangler.jsonc' },
-      },
-    },
-  },
-})
-```
-
-## CI Pipeline
-
-### GitHub Actions
-
-```yaml
-name: typescript-build-tools
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-
-jobs:
-  check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - run: bun install --frozen-lockfile
-
-      - run: bun run typecheck
-      - run: bun run lint
-      - run: bun run test
-```
-
-### Monorepo CI with Turbo
-
-```yaml
-name: typescript-build-tools
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-
-jobs:
-  check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: oven-sh/setup-bun@v2
-
-      - run: bun install --frozen-lockfile
-
-      - run: bun run check  # turbo typecheck lint test
-        env:
-          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
-          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
-```
-
-## Guidelines
-
-1. **Use Bun** as package manager (`bun install`) and task runner (`bun run`)
-2. **Use `bun run test`** (not `bun test`) - `bun test` runs Bun's native test runner
-3. **Use tsgo** for typechecking - faster than `tsc` for CI
-4. **Use Vitest** for testing - fast, ESM-native, great DX
-5. **Use Biome** for linting and formatting - single tool, fast
-6. **Use Turborepo** for monorepos - caching, parallel execution
-7. **Enable V8 coverage** in Vitest for accurate coverage reports
-8. **Configure global setup** for database migrations in tests
-9. **Use workspace configs** in Vitest for different test pools
-10. **Share Biome config** via workspace package in monorepos
-11. **Run checks in order**: typecheck, lint, test (fail fast)
-12. **Use `--frozen-lockfile`** in CI for reproducible builds
-13. **Configure Turbo caching** for faster CI with remote cache