Skip to content

secondsky/claude-skills / plugins/ultracite/skills/ultracite

ultracite

Verified

Ultracite multi-provider linting/formatting (Biome, ESLint, Oxlint). Use for v6/v7 setup, provider selection, Git hooks, MCP integration, AI hooks, migrations, or encountering configuration, type-aware linting, monorepo errors.

references/monorepo-configuration.md

View on GitHub
# Ultracite Monorepo Configuration

Complete guide for configuring Ultracite in monorepos with Turborepo, Nx, and pnpm workspaces.

**Last Updated**: 2025-11-22

---

## Overview

Ultracite supports monorepos with:
- **Shared configurations** across packages
- **Package-specific overrides** for custom rules
- **Performance optimizations** for large codebases
- **Workspace-aware linting** (Turborepo, Nx, pnpm)

**Benefits**:
- Single source of truth for linting rules
- Per-package customization when needed
- Faster linting with caching (Turborepo)
- Consistent code quality across all packages

---

## Configuration Strategies

### Strategy 1: Single Root Config (Simplest)

**Best for**: Small monorepos (< 10 packages) with similar requirements

**Structure**:
```
monorepo/
├── biome.json              # ← Single config for entire repo
├── apps/
│   ├── web/
│   └── mobile/
└── packages/
    ├── ui/
    └── utils/
```

**Root `biome.json`**:
```jsonc
{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "extends": ["ultracite/core", "ultracite/react"],

  "files": {
    // Biome 2.x: files.includes with ! negation (files.ignore removed)
    "includes": [
      "**",
      "!**/dist",
      "!**/build",
      "!**/.next",
      "!**/node_modules"
    ]
  }
}
```

**Usage**:
```bash
# Lint entire monorepo
ultracite check

# Lint specific package
ultracite check apps/web
```

---

### Strategy 2: Shared Config + Overrides (Recommended)

**Best for**: Medium monorepos (10-50 packages) with some variation

**Structure**:
```
monorepo/
├── biome.json              # ← Shared base config
├── apps/
│   ├── web/
│   │   └── biome.json      # ← Next.js-specific overrides
│   └── mobile/
│       └── biome.json      # ← React Native overrides
└── packages/
    ├── ui/
    │   └── biome.json      # ← React component overrides
    └── utils/
        └── biome.json      # ← Utility library overrides
```

**Root `biome.json`** (shared):
```jsonc
{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "extends": ["ultracite/core"],

  "linter": {
    "rules": {
      "suspicious": {
        "noConsoleLog": "error",
        "noDebugger": "error"
      }
    }
  }
}
```

**`apps/web/biome.json`** (Next.js):
```jsonc
{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "extends": ["../../biome.json", "ultracite/nextjs"],

  "linter": {
    "rules": {
      "suspicious": {
        "noConsoleLog": "off"  // Allow console.log in Next.js app
      }
    }
  }
}
```

**`packages/ui/biome.json`** (React library):
```jsonc
{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "extends": ["../../biome.json", "ultracite/react"],

  "linter": {
    // Biome 2.x: per-group "all" value was removed — use linter.domains
    // to elevate a whole domain (e.g. react/a11y) to "all"
    "domains": { "react": "all" },
    "rules": {
      "a11y": {
        // Explicit rule enables (Biome 2.x no longer accepts "all": "error")
        "useAltText": "error",
        "useAnchorContent": "error",
        "useButtonType": "error",
        "useKeyWithClickEvents": "error"
      }
    }
  }
}
```

---

### Strategy 3: Per-Package Configs (Flexible)

**Best for**: Large monorepos (50+ packages) with diverse requirements

**Structure**:
```
monorepo/
├── .ultracite/
│   ├── base.json           # ← Shared base
│   ├── react.json          # ← React apps/packages
│   └── node.json           # ← Node.js packages
├── apps/
│   └── web/
│       └── biome.json      # extends .ultracite/react.json
└── packages/
    └── api/
        └── biome.json      # extends .ultracite/node.json
```

**`.ultracite/base.json`**:
```jsonc
{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "extends": ["ultracite/core"],

  "formatter": {
    "indentWidth": 2,
    "lineWidth": 100
  }
}
```

**`.ultracite/react.json`**:
```jsonc
{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "extends": ["./base.json", "ultracite/react"]
}
```

**`apps/web/biome.json`**:
```jsonc
{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "extends": ["../../.ultracite/react.json", "ultracite/nextjs"]
}
```

---

## Turborepo Integration

### Setup

**Install**:
```bash
bun add -D ultracite
```

**`turbo.json`**:
```json
{
  "tasks": {
    "lint": {
      "cache": true,
      "inputs": [
        "**/*.ts",
        "**/*.tsx",
        "**/*.js",
        "**/*.jsx",
        "biome.json"
      ],
      "outputs": []
    },
    "lint:fix": {
      "cache": false,
      "dependsOn": ["^lint:fix"]
    }
  }
}
```

---

### Package Scripts

**Root `package.json`**:
```json
{
  "scripts": {
    "lint": "turbo run lint",
    "lint:fix": "turbo run lint:fix"
  }
}
```

**`apps/web/package.json`**:
```json
{
  "scripts": {
    "lint": "ultracite check",
    "lint:fix": "ultracite check --write"
  }
}
```

**`packages/ui/package.json`**:
```json
{
  "scripts": {
    "lint": "ultracite check",
    "lint:fix": "ultracite check --write"
  }
}
```

---

### Running Lints

```bash
# Lint all packages (parallel, cached)
turbo run lint

# Lint all packages and fix
turbo run lint:fix

# Lint specific package
turbo run lint --filter=web

# Lint changed packages only
turbo run lint --filter=[HEAD^1]
```

---

### Cache Benefits

**First run** (no cache):
```
Tasks:    5 successful, 5 total
Cached:   0 cached, 5 total
Time:     12.3s
```

**Second run** (with cache):
```
Tasks:    5 successful, 5 total
Cached:   5 cached, 5 total
Time:     0.1s  ← 99% faster!
```

---

## Nx Integration

### Setup

**Install**:
```bash
bun add -D ultracite
```

**`nx.json`**:
```json
{
  "targetDefaults": {
    "lint": {
      "cache": true,
      "inputs": [
        "{projectRoot}/**/*.ts",
        "{projectRoot}/**/*.tsx",
        "{projectRoot}/biome.json",
        "{workspaceRoot}/biome.json"
      ]
    }
  }
}
```

---

### Project Configuration

**`apps/web/project.json`**:
```json
{
  "name": "web",
  "targets": {
    "lint": {
      "executor": "nx:run-commands",
      "options": {
        "command": "ultracite check",
        "cwd": "apps/web"
      }
    },
    "lint:fix": {
      "executor": "nx:run-commands",
      "options": {
        "command": "ultracite check --write",
        "cwd": "apps/web"
      }
    }
  }
}
```

---

### Running Lints

```bash
# Lint all projects
nx run-many --target=lint --all

# Lint specific project
nx run web:lint

# Lint affected projects only
nx affected --target=lint

# Lint and fix
nx run web:lint:fix
```

---

## pnpm Workspaces

### Setup

**`pnpm-workspace.yaml`**:
```yaml
packages:
  - 'apps/*'
  - 'packages/*'
```

**Root `package.json`**:
```json
{
  "scripts": {
    "lint": "pnpm --recursive --parallel run lint",
    "lint:fix": "pnpm --recursive run lint:fix"
  },
  "devDependencies": {
    "ultracite": "^7.0.0"
  }
}
```

---

### Package Scripts

**`apps/web/package.json`**:
```json
{
  "scripts": {
    "lint": "ultracite check",
    "lint:fix": "ultracite check --write"
  }
}
```

---

### Running Lints

```bash
# Lint all packages (parallel)
pnpm lint

# Lint specific package
pnpm --filter web lint

# Lint and fix all packages
pnpm lint:fix

# Lint changed packages only
pnpm --filter "...[HEAD^1]" lint
```

---

## Package-Specific Overrides

### Example: Strict Library, Relaxed App

**`packages/ui/biome.json`** (strict):
```jsonc
{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "extends": ["../../biome.json", "ultracite/react"],

  "linter": {
    // Biome 2.x: per-group "all" value was removed — use linter.domains
    "domains": { "react": "all" },
    "rules": {
      "a11y": {
        // Explicit rule enables (Biome 2.x no longer accepts "all": "error")
        "useAltText": "error",
        "useAnchorContent": "error",
        "useButtonType": "error"
      },
      "suspicious": {
        "noConsoleLog": "error",  // No console.log
        "noDebugger": "error"     // No debugger
      },
      "complexity": {
        "noExcessiveCognitiveComplexity": {
          "level": "error",
          "options": { "maxComplexity": 10 }  // Lower complexity limit
        }
      }
    }
  }
}
```

**`apps/web/biome.json`** (relaxed):
```jsonc
{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "extends": ["../../biome.json", "ultracite/nextjs"],

  "linter": {
    "rules": {
      "suspicious": {
        "noConsoleLog": "off"     // Allow console.log in app
      },
      "complexity": {
        "noExcessiveCognitiveComplexity": "off"  // No complexity limit
      }
    }
  }
}
```

---

## Performance Optimizations

### 1. Use Workspace-Aware Commands

**Turborepo**:
```bash
# ✓ Only lints changed packages
turbo run lint --filter=[HEAD^1]

# ✗ Lints all packages
turbo run lint
```

**Nx**:
```bash
# ✓ Only lints affected projects
nx affected --target=lint

# ✗ Lints all projects
nx run-many --target=lint --all
```

---

### 2. Leverage Caching

**Turborepo** (automatic):
```json
{
  "tasks": {
    "lint": {
      "cache": true  // ← Enables caching
    }
  }
}
```

**Nx** (automatic):
```json
{
  "targetDefaults": {
    "lint": {
      "cache": true  // ← Enables caching
    }
  }
}
```

---

### 3. Parallel Execution

**Turborepo** (default):
```bash
turbo run lint  # Runs in parallel automatically
```

**pnpm**:
```bash
pnpm --recursive --parallel run lint
```

**Nx** (configurable):
```bash
nx run-many --target=lint --all --parallel=3
```

---

### 4. Incremental Linting

**Git hook integration** (only lint staged files):

```bash
# .husky/pre-commit
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# Only lint staged files
ultracite check --staged --write
```

---

## Troubleshooting

### Config Not Found

**Error**:
```
Configuration file not found
```

**Fix**: Ensure `biome.json` exists in package root or parent directory:

```bash
# Check config path
ultracite check --verbose

# Specify config explicitly
ultracite check --config-path=../../biome.json
```

---

### Rules Overridden Unexpectedly

**Issue**: Child config doesn't override parent rules

**Fix**: Use explicit rule values:

```jsonc
{
  "linter": {
    "rules": {
      "suspicious": {
        "noConsoleLog": "off"  // ← Must be explicit, not inherited
      }
    }
  }
}
```

---

### Slow Linting in Large Monorepo

**Solutions**:

1. **Enable caching** (Turborepo/Nx)
2. **Lint changed packages only**:
   ```bash
   turbo run lint --filter=[HEAD^1]
   ```
3. **Use parallel execution**:
   ```bash
   pnpm --recursive --parallel run lint
   ```
4. **Exclude unnecessary files**:
   ```jsonc
   {
     "files": {
       // Biome 2.x: files.includes with ! negation
       "includes": [
         "**",
         "!**/dist",
         "!**/.next",
         "!**/coverage",
         "!**/*.generated.ts"
       ]
     }
   }
   ```

---

## Best Practices

1. **Use root config for shared rules** (DRY principle)
2. **Override only when necessary** (avoid config duplication)
3. **Leverage workspace caching** (Turborepo/Nx)
4. **Lint changed packages only** in CI
5. **Run lints in parallel** for speed
6. **Use `--filter` flags** to target specific packages
7. **Document config strategy** in root README
8. **Keep configs close to code** (per-package `biome.json`)

---

**See also:**
- `configuration-guide.md` for Ultracite configuration details
- `git-hooks-setup.md` for pre-commit integration
- `troubleshooting.md` for common issues
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall