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/configuration-guide.md

View on GitHub
# Ultracite Configuration Guide

Complete guide for configuring Ultracite with framework presets, customization, and file exclusion patterns.

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

---

## Configuration File Structure

Ultracite uses Biome's configuration format (`biome.json` or `biome.jsonc`):

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

  // Optional: Add framework-specific preset
  // "extends": ["ultracite/core", "ultracite/react"],

  // Optional: Customize rules
  "linter": {
    "rules": {
      "a11y": {
        "noAutofocus": "off"  // Disable specific rule
      }
    }
  },

  // Optional: Exclude files/directories (Biome 2.x uses `includes` with `!` negation)
  "files": {
    "includes": [
      "**",
      "!dist",
      "!build",
      "!coverage",
      "!**/*.generated.ts"
    ]
  }
}
```

---

## Framework Presets

### React Preset (`ultracite/react`)

**Extends**: `ultracite/core` + React-specific rules

**Includes**:
- React Hooks linting (exhaustive deps, rules of hooks)
- JSX accessibility (a11y) checks
- React-specific naming conventions
- Component best practices

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

**Key Rules**:
- `useExhaustiveDependencies`: Ensures all dependencies are listed in hooks
- `noArrayIndexKey`: Prevents using array indices as React keys
- `useButtonType`: Requires explicit button types
- `noChildrenProp`: Prevents passing children as props
- `useJsxKeyInIterable`: Requires keys in JSX lists

**Best For**:
- Create React App projects
- Vite React projects
- Custom React setups

---

### Next.js Preset (`ultracite/nextjs`)

**Extends**: `ultracite/react` + Next.js-specific rules

**Includes**:
- Everything from `ultracite/react`
- Next.js-specific imports (e.g., `next/link`, `next/image`)
- App Router conventions
- Server Component rules
- Performance optimizations

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

**Key Rules**:
- `noHtmlLinkForPages`: Enforces using Next.js `<Link>`
- `noImgElement`: Enforces using Next.js `<Image>`
- `noTitleInDocumentHead`: Prevents `<title>` in custom Document
- Server/Client Component separation checks

**Best For**:
- Next.js 14+ projects (App Router)
- Next.js Pages Router projects
- Vercel deployments

---

### Vue Preset (`ultracite/vue`)

**Extends**: `ultracite/core` + Vue-specific rules

**Includes**:
- Vue 3 Composition API linting
- Template syntax validation
- Reactivity system checks
- Component naming conventions

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

**Key Rules**:
- `useValidVModelName`: Ensures correct v-model naming
- `noMutatingProps`: Prevents prop mutations
- `requireEmitsOption`: Requires explicit emits declaration
- `noReactiveReassign`: Prevents reassigning reactive variables

**Best For**:
- Nuxt 3 projects
- Vue 3 + Vite projects
- Quasar Framework

---

### Svelte Preset (`ultracite/svelte`)

**Extends**: `ultracite/core` + Svelte-specific rules

**Includes**:
- Svelte 4/5 syntax validation
- Reactive declarations linting
- Component lifecycle checks
- Store best practices

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

**Key Rules**:
- `noInnerDeclarations`: Prevents function declarations in blocks
- `validEach`: Ensures each blocks have valid syntax
- `noUnusedStores`: Detects unused store subscriptions
- `preferReadableExports`: Enforces readable exports over defaults

**Best For**:
- SvelteKit projects
- Svelte 5 (runes support)
- Svelte component libraries

---

## Core Preset Features

The `ultracite/core` preset includes **200+ rules** across these categories:

### 1. Correctness (85 rules)
Catches actual bugs and logic errors:
- `noUnreachable`: Detects unreachable code
- `noUnsafeFinally`: Prevents unsafe control flow in finally blocks
- `noConstantCondition`: Catches always-true/false conditions
- `useValidForDirection`: Ensures correct for-loop direction
- `noUnusedVariables`: Removes unused variables

### 2. Suspicious (48 rules)
Flags code that might indicate bugs:
- `noDoubleEquals`: Enforces `===` over `==`
- `noAsyncPromiseExecutor`: Prevents async Promise executors
- `noConsoleLog`: Flags console.log statements
- `noDebugger`: Removes debugger statements
- `noShadowRestrictedNames`: Prevents shadowing global variables

### 3. Style (35 rules)
Enforces consistent code style:
- `useConst`: Prefers `const` over `let` when possible
- `useTemplate`: Prefers template literals over string concatenation
- `useSingleVarDeclarator`: One variable per declaration
- `noNegationElse`: Simplifies negated conditions
- `noUnusedTemplateLiteral`: Removes unnecessary template literals

### 4. Complexity (12 rules)
Reduces cognitive complexity:
- `noExcessiveCognitiveComplexity`: Limits function complexity
- `noForEach`: Prefers for-of loops over forEach
- `useFlatMap`: Suggests flatMap over map().flat()
- `noUselessFragments`: Removes unnecessary React fragments

### 5. Performance (8 rules)
Optimizes runtime performance:
- `noAccumulatingSpread`: Prevents O(n²) spread operations
- `noDelete`: Avoids delete operator (breaks V8 optimizations)
- `useArrayLiterals`: Prefers `[]` over `new Array()`

### 6. Security (6 rules)
Prevents security vulnerabilities:
- `noDangerouslySetInnerHtml`: Flags XSS risks
- `noGlobalEval`: Prevents eval() usage
- `noGlobalObjectCalls`: Prevents calling global objects as functions

### 7. Accessibility (6 rules)
Ensures inclusive UIs:
- `useAltText`: Requires alt text on images
- `useAnchorContent`: Ensures links have accessible content
- `useButtonType`: Requires explicit button types
- `useKeyWithClickEvents`: Ensures keyboard accessibility

---

## Advanced Customization

### Disabling Rules

**Single rule**:
```jsonc
{
  "linter": {
    "rules": {
      "suspicious": {
        "noConsoleLog": "off"
      }
    }
  }
}
```

**Entire category** (Biome 2.x removed the per-group `"all"` value from `linter.rules`; use `linter.domains` or disable the recommended rules individually):
```jsonc
{
  "linter": {
    "rules": {
      "suspicious": {
        "noConsoleLog": "off",
        "noDebugger": "off",
        "noDoubleEquals": "off"
        // ... disable each recommended rule explicitly
      }
    }
  }
}
```

**Re-enable specific rule in disabled category**:
```jsonc
{
  "linter": {
    "rules": {
      "suspicious": {
        "noDoubleEquals": "off",
        "noConsoleLog": "error"  // Re-enable this one
      }
    }
  }
}
```

---

### Rule Severity Levels

```jsonc
{
  "linter": {
    "rules": {
      "suspicious": {
        "noConsoleLog": "warn",      // Warning (doesn't fail CI)
        "noDebugger": "error",       // Error (fails CI)
        "noDoubleEquals": "off"      // Disabled
      }
    }
  }
}
```

---

### Per-File Configuration

**Disable rules for specific files** (Biome 2.x uses `includes` in overrides):
```jsonc
{
  "overrides": [
    {
      "includes": ["**/*.test.ts", "**/*.test.tsx"],
      "linter": {
        "rules": {
          "suspicious": {
            "noConsoleLog": "off"
          }
        }
      }
    }
  ]
}
```

**Different rules for different directories** (Biome 2.x uses `includes` in overrides, and removed per-group `"all"` from rules):
```jsonc
{
  "overrides": [
    {
      "includes": ["src/legacy/**"],
      "linter": {
        "rules": {
          "complexity": {
            "noExcessiveCognitiveComplexity": "off",
            "noForEach": "off"
            // ... disable each complexity rule explicitly
          }
        }
      }
    }
  ]
}
```

---

## File Exclusion Patterns

> **Biome 2.x note**: `files.ignore` and `files.include` were removed. Use a single `files.includes` array with `!` negation to exclude paths. Globs are evaluated relative to the config file and `*` no longer matches `/`.

### Common Exclusions

```jsonc
{
  "files": {
    "includes": [
      "**",
      // Build outputs
      "!dist",
      "!build",
      "!.next",
      "!out",

      // Dependencies
      "!node_modules",
      "!.pnpm-store",

      // Test coverage
      "!coverage",
      "!.nyc_output",

      // Generated files
      "!**/*.generated.ts",
      "!**/*.d.ts",

      // Cache directories
      "!.cache",
      "!.turbo",

      // Framework-specific
      "!.nuxt",
      "!.svelte-kit",
      "!vite.config.ts.timestamp-*"
    ]
  }
}
```

---

### Glob Patterns

**Wildcards**:
- `*`: Matches any file/directory (non-recursive)
- `**`: Matches any file/directory (recursive)
- `?`: Matches single character

**Examples**:
```jsonc
{
  "files": {
    "includes": [
      "**",
      "!*.config.js",          // All .config.js files in root
      "!**/*.config.js",       // All .config.js files anywhere
      "!src/generated/**",     // Everything in src/generated/
      "!**/__tests__/**",      // All __tests__ directories
      "!*.{spec,test}.ts"      // All .spec.ts and .test.ts files
    ]
  }
}
```

---

### Including Files

By default, Ultracite lints all supported files. Use `includes` to limit scope (Biome 2.x renamed `files.include` → `files.includes`):

```jsonc
{
  "files": {
    "includes": [
      "src/**/*.ts",
      "src/**/*.tsx"
    ]
  }
}
```

---

## Formatter Configuration

### Format Options

```jsonc
{
  "formatter": {
    "enabled": true,
    "formatWithErrors": false,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineEnding": "lf",
    "lineWidth": 80
  }
}
```

---

### Per-Language Formatting

```jsonc
{
  "formatter": {
    "enabled": true
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "semicolons": "asNeeded",
      "trailingCommas": "es5"
    }
  },
  "json": {
    "formatter": {
      "indentWidth": 2
    }
  }
}
```

---

## Environment-Specific Configuration

### Development

```jsonc
{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "extends": ["ultracite/core", "ultracite/react"],
  "linter": {
    "rules": {
      "suspicious": {
        "noConsoleLog": "off",  // Allow console.log in dev
        "noDebugger": "off"     // Allow debugger in dev
      }
    }
  }
}
```

---

### Production/CI

```jsonc
{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "extends": ["ultracite/core", "ultracite/react"],
  "linter": {
    "rules": {
      "suspicious": {
        "noConsoleLog": "error",  // Fail on console.log
        "noDebugger": "error"     // Fail on debugger
      }
    }
  }
}
```

**Tip**: Use different config files per environment:
```bash
# Development
ultracite check --config-path=biome.dev.json

# CI
ultracite check --config-path=biome.ci.json
```

---

**See also:**
- `git-hooks-setup.md` for pre-commit integration
- `monorepo-configuration.md` for multi-package setups
- `troubleshooting.md` for configuration 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