Build & Tooling

Quick Guide: ESLint 9 flat config with defineConfig() and globalIgnores(). typescript-eslint v8 with projectService. Prettier shared config. Shared TypeScript configs. Bun package manager. Vite build configuration. Husky + lint-staged for git hooks.

WARNING: ESLint 10 (January 2026) completely removes .eslintrc support. Migrate to flat config now.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST use ESLint 9 flat config with defineConfig() from eslint/config - NOT legacy .eslintrc)

(You MUST use globalIgnores() for explicit global ignore patterns - NOT bare ignores property)

(You MUST use typescript-eslint v8+ with projectService: true for typed linting)

(You MUST include eslint-plugin-only-warn to convert errors to warnings for better DX)

(You MUST use shared config pattern - @repo/eslint-config, @repo/prettier-config, @repo/typescript-config)

(You MUST enable TypeScript strict mode in ALL tsconfig.json files)

</critical_requirements>

Auto-detection: ESLint 9 flat config, Prettier, Bun, Vite configuration, Husky pre-commit hooks, lint-staged, commitlint

When to use:

Setting up ESLint 9 flat config with shared configurations
Configuring Prettier with shared config
Setting up Vite build configuration
Configuring TypeScript with shared configs
Setting up pre-commit hooks with lint-staged
Configuring commit message validation (commitlint)

When NOT to use:

Runtime code (this is build-time tooling only)
CI/CD pipelines (see backend/ci-cd skill instead)
Production deployment configuration
Server-side build processes (e.g., Docker builds)

Key patterns covered:

ESLint 9 flat config with only-warn plugin (errors become warnings for better DX)
Shared configurations (@repo/eslint-config, @repo/prettier-config, @repo/typescript-config)
Vite configuration (path aliases, environment-specific builds)
Husky + lint-staged for pre-commit quality gates (fast, staged files only)
Commitlint for conventional commit messages

Detailed Resources:

For code examples, see examples/core.md (essential patterns)
- examples/vite.md - Vite path aliases, vendor chunks, environment builds
- examples/eslint.md - ESLint 9 flat config, shared configs, custom rules
- examples/typescript.md - Shared TypeScript strict config
- examples/git-hooks.md - Husky, lint-staged, VS Code integration
For decision frameworks and anti-patterns, see reference.md

Related skills:

For Turborepo task pipelines, caching, and workspaces, see setup/monorepo
For internal package structure and conventions, see setup/package
For daily coding conventions (naming, imports, constants), see CLAUDE.md

Philosophy

Build tooling should be fast, consistent, and non-blocking. Developers shouldn't fight with tools - tools should help catch issues early while staying out of the way during development.

When to use this skill:

Setting up new apps or packages in the monorepo
Configuring linting, formatting, or type-checking
Adding git hooks for pre-commit quality gates
Creating shared configurations for consistency
Optimizing build performance with Vite

When NOT to use:

Runtime code (this is build-time tooling only)
CI/CD pipelines (see separate CI/CD skill)
Production deployment configuration
Server-side build processes

Core Patterns

Pattern 1: Vite Configuration

Vite is the build tool for frontend apps. Key features: path aliases, vendor chunk splitting, environment-specific builds.

Path Aliases:

Configure in both vite.config.ts and tsconfig.json
Common aliases: @/, @components/, @features/, @lib/, @hooks/, @types/
Vendor chunk splitting reduces main bundle size

Environment-Specific Builds:

Use loadEnv(mode, ...) for environment-aware config
Conditional sourcemaps (dev only) and minification (prod only)
Build-time constants with define option

See examples/vite.md for complete Vite configuration examples.

Pattern 2: ESLint 9 Flat Config

ESLint 9 uses flat config format (replaces legacy .eslintrc). Shared configs live in packages/eslint-config/.

Key Requirements (ESLint 9.15+):

Use defineConfig() from eslint/config for type-safe configuration
Use globalIgnores() for explicit global ignore patterns
Support for eslint.config.ts TypeScript config files
Use extends property in config objects for plugin composition
Include eslint-plugin-only-warn to convert errors to warnings
Use eslint-config-prettier to disable conflicting rules

typescript-eslint v8+ Features:

Use projectService: true for automatic tsconfig discovery (replaces manual project option)
Use allowDefaultProject for config files not in tsconfig
tseslint.config() is deprecated - use ESLint's defineConfig() instead

Custom Rules for Monorepo:

import/no-default-export: Enforce named exports
no-restricted-imports: Prevent importing from internal package paths
@typescript-eslint/consistent-type-imports: Use import type for types

ESLint 10 Migration (January 2026):

.eslintrc files completely removed
.eslintignore files no longer supported
CLI flags like --no-eslintrc, --env, --rulesdir removed
Minimum Node.js 20.19.0 required

See examples/eslint.md for complete ESLint configuration examples.

Pattern 3: Prettier Configuration (v3.0+)

Prettier configuration lives in packages/prettier-config/ and is shared across all packages.

Standard Config:

printWidth: 100 - Balance readability with screen space
trailingComma: "all" - Now the default in Prettier 3.0+ (cleaner git diffs)
singleQuote: false - Match JSON format, reduce JSX escaping
endOfLine: "lf" - Consistent line endings
bracketSameLine: false - Replaces deprecated jsxBracketSameLine

New in v3.5+:

TypeScript config file support (.prettierrc.ts) - requires Node.js 22.6.0+
objectWrap option - controls multi-line object formatting ("preserve" or "collapse")
experimentalOperatorPosition option - controls binary operator placement ("start" or "end")
experimentalTernaries option (v3.1+) - alternative ternary formatting

Usage:

Reference in package.json: "prettier": "@repo/prettier-config"
Single source of truth prevents formatting inconsistencies

See examples/core.md for complete Prettier configuration examples.

Pattern 4: TypeScript Configuration

TypeScript configurations live in packages/typescript-config/ with base settings extended by apps and packages.

Strict Mode (Required):

strict: true - Enables all strict checks
noUncheckedIndexedAccess: true - Prevents undefined access bugs
exactOptionalPropertyTypes: true - Strict optional handling
noImplicitOverride: true - Requires override keyword for inherited methods
noUnusedLocals: true / noUnusedParameters: true - Catch dead code

Modern Module Settings (TS 5.x):

target: "ES2022" - Stable ES target (not esnext)
module: "preserve" - For bundler-based projects
moduleResolution: "bundler" - Modern bundler compatibility
verbatimModuleSyntax: true - Enforces explicit import type
moduleDetection: "force" - Treats all files as modules

Path Aliases:

Configure in tsconfig.json to match Vite aliases
Use ${configDir} template (TS 5.5+) for portable shared configs

For daily TypeScript enforcement rules (no unjustified any, explicit types), see CLAUDE.md.

See examples/typescript.md for complete TypeScript configuration examples including TS 5.x features.

Pattern 5: Git Hooks with Husky + lint-staged

Pre-commit hooks run linting on staged files only for fast feedback.

Setup:

Husky hook calls bunx lint-staged
lint-staged config specifies file patterns and commands
Only lint staged files - NOT entire codebase

VS Code Integration:

Format on save with Prettier
Auto-fix ESLint on save
Recommended extensions for team consistency

Rule of thumb: Pre-commit should take < 10 seconds. Anything slower goes to pre-push or CI.

See examples/git-hooks.md for complete Husky + lint-staged examples.

<decision_framework>

Decision Framework

ESLint vs Biome

Need linting and formatting?
├─ Large monorepo (1000+ files)?
│   ├─ Speed is critical bottleneck?
│   │   └─ YES → Consider Biome (20x faster)
│   └─ NO → ESLint 9 + Prettier
└─ Greenfield project?
    ├─ Want single tool for lint + format?
    │   └─ YES → Consider Biome
    └─ Need mature plugin ecosystem?
        └─ YES → ESLint 9 + Prettier ✓

Current recommendation: ESLint 9 + Prettier (mature, stable, extensive plugin ecosystem)

When to Use Git Hooks

What to run pre-commit?
├─ Fast (< 10 seconds)?
│   ├─ Lint with auto-fix → YES ✓
│   ├─ Format with Prettier → YES ✓
│   └─ Type check (--noEmit) → YES ✓
└─ Slow (> 10 seconds)?
    ├─ Full test suite → NO (run in CI)
    ├─ Full build → NO (run in CI)
    └─ E2E tests → NO (run in CI)

See reference.md for additional decision frameworks.

</decision_framework>

<red_flags>

RED FLAGS

High Priority Issues:

❌ Using legacy .eslintrc format instead of ESLint 9 flat config (WILL BREAK in ESLint 10, January 2026)
❌ Using tseslint.config() instead of ESLint's native defineConfig() (deprecated)
❌ Using bare ignores property instead of globalIgnores() helper (ambiguous behavior)
❌ Missing eslint-plugin-only-warn (errors block developers during development)
❌ Disabling TypeScript strict mode (allows implicit any and null bugs)
❌ Not using shared configs in monorepo (configs drift causing inconsistency)

Medium Priority Issues:

⚠️ Running full test suite in pre-commit hook (too slow, encourages --no-verify)
⚠️ No editor integration for Prettier/ESLint (manual formatting is forgotten)
⚠️ Hardcoded config values in each package instead of shared config
⚠️ Using manual project option instead of projectService: true in typescript-eslint
⚠️ Using deprecated jsxBracketSameLine option in Prettier (use bracketSameLine instead)

Gotchas & Edge Cases:

ESLint 9 flat config uses different plugin syntax than legacy .eslintrc
only-warn plugin must be loaded AFTER other plugins to convert their errors
TypeScript path aliases must be configured in BOTH tsconfig and build tool (Vite/Next)
Prettier and ESLint can conflict - must use eslint-config-prettier to disable conflicting rules
defineConfig() auto-flattens arrays - no spread operators needed
projectService requires typescript-eslint v8+ (was experimental in v6-v7 as EXPERIMENTAL_useProjectService)
ESLint 10 requires Node.js 20.19.0+ (upgrade Node before upgrading ESLint)
Prettier TypeScript config files (.prettierrc.ts) require Node.js 22.6.0+ and --experimental-strip-types flag before Node v24.3.0
Prettier 3.0+ APIs are async - plugins using sync APIs need migration (use @prettier/sync for sync wrappers)

See reference.md for full anti-patterns documentation.

</red_flags>

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md