ultracite — Skillopedia

Ultracite Skill Fast, zero-config linting and formatting for modern JavaScript/TypeScript projects Overview Ultracite is a unified linting and formatting solution that supports multiple providers: Biome (default, Rust-based), ESLint+Prettier+Stylelint , and Oxlint+Oxfmt . It provides framework-specific presets and zero-configuration defaults, replacing traditional ESLint+Prettier setups with a faster, simpler alternative. Ultracite operates invisibly in the background, automatically formatting code and applying fixes on every save. Version 7 Changes : Multi-provider architecture, preset path…

)\n\nif [ -n \"$TS_FILES\" ]; then\n # Run fix with custom flags\n npx ultracite fix $TS_FILES \\\n --no-errors-on-unmatched \\\n --skip-gitignored \\\n --quiet\nfi\n\nexit 0\n```\n\n## Configuration Options\n\n### Hook Behavior\n\nConfigure hook execution in `.ultracite/hooks.json`:\n\n```json\n{\n \"aiHooks\": {\n \"enabled\": true,\n \"runOn\": \"post-edit\",\n \"filePatterns\": [\"**/*.ts\", \"**/*.tsx\", \"**/*.js\", \"**/*.jsx\"],\n \"excludePatterns\": [\"**/*.test.ts\", \"**/dist/**\"],\n \"timeoutMs\": 5000,\n \"showNotifications\": true\n }\n}\n```\n\n**Options**:\n- `enabled`: Enable/disable hooks\n- `runOn`: When to run (`post-edit`, `pre-commit`)\n- `filePatterns`: Which files to format\n- `excludePatterns`: Files to skip\n- `timeoutMs`: Max hook execution time\n- `showNotifications`: Show toast notifications\n\n### Per-Editor Configuration\n\n**Cursor** (`.cursor/hooks/config.json`):\n```json\n{\n \"hooks\": {\n \"postEdit\": {\n \"enabled\": true,\n \"script\": \"./post-edit.sh\",\n \"timeout\": 5000\n }\n }\n}\n```\n\n**Claude Code** (`.claude/settings.json`):\n```json\n{\n \"hooks\": {\n \"postEdit\": \".claude/hooks/post-edit.sh\",\n \"postEditTimeout\": 5000\n }\n}\n```\n\n## Usage\n\n### Automatic Execution\n\nOnce installed, hooks run automatically:\n\n1. **AI makes edit** → File is modified\n2. **Hook triggers** → `post-edit.sh` runs\n3. **Ultracite fixes** → Auto-format, organize imports, fix lint issues\n4. **User sees result** → Formatted code\n\n### Manual Testing\n\nTest hook manually:\n\n```bash\n# Simulate AI edit on file\n.cursor/hooks/post-edit.sh src/index.ts\n\n# Test multiple files\n.cursor/hooks/post-edit.sh \"src/**/*.ts\"\n```\n\n### Disable Temporarily\n\n```bash\n# Disable hooks for single AI session\nULTRACITE_HOOKS_DISABLED=true cursor\n\n# Or edit config\n# .ultracite/hooks.json\n{\n \"aiHooks\": {\n \"enabled\": false // Disable\n }\n}\n```\n\n## Workflow Examples\n\n### Example 1: React Component Generation\n\n**Before AI Hooks**:\n1. Ask AI: \"Create a React button component\"\n2. AI generates code\n3. **Manual step**: Run `npx ultracite fix src/Button.tsx`\n4. Code is formatted\n\n**After AI Hooks**:\n1. Ask AI: \"Create a React button component\"\n2. AI generates code\n3. **Hook auto-runs**: `npx ultracite fix src/Button.tsx`\n4. Code is formatted automatically ✨\n\n### Example 2: Large Refactoring\n\n**Before AI Hooks**:\n1. Ask AI: \"Refactor these 10 files to use hooks\"\n2. AI edits 10 files\n3. **Manual step**: Run `npx ultracite fix src/**/*.tsx`\n4. All files formatted\n\n**After AI Hooks**:\n1. Ask AI: \"Refactor these 10 files to use hooks\"\n2. AI edits 10 files\n3. **Hook auto-runs**: Formats each file as edited\n4. All files automatically formatted ✨\n\n## Performance Considerations\n\n### Hook Execution Time\n\nTypical hook execution times:\n- **Single file**: 50-200ms\n- **5 files**: 200-500ms\n- **10+ files**: 500ms-2s\n\n### Optimization Tips\n\n**1. Only format changed files**:\n```bash\n# In hook script\nCHANGED_FILES=$(echo \"$EDITED_FILES\" | grep -E '\\.(ts|tsx)

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

)\nnpx ultracite fix $CHANGED_FILES # Not all files\n```\n\n**2. Skip tests and generated files**:\n```json\n{\n \"excludePatterns\": [\n \"**/*.test.ts\",\n \"**/*.spec.ts\",\n \"**/*.generated.ts\",\n \"**/dist/**\",\n \"**/node_modules/**\"\n ]\n}\n```\n\n**3. Use cache**:\n```bash\n# Ultracite automatically caches results\nnpx ultracite fix $FILES --use-cache\n```\n\n**4. Set timeout**:\n```json\n{\n \"timeoutMs\": 3000 // Kill if takes >3s\n}\n```\n\n## Troubleshooting\n\n### Hook Not Running\n\n**Problem**: AI edits don't trigger hook\n\n**Check**:\n1. Hook script exists: `ls .cursor/hooks/post-edit.sh`\n2. Script is executable: `chmod +x .cursor/hooks/post-edit.sh`\n3. Hooks enabled: Check `.ultracite/hooks.json`\n\n**Solution**:\n```bash\n# Reinstall hooks\nnpx ultracite ai-hooks install --editor cursor --force\n\n# Make executable\nchmod +x .cursor/hooks/post-edit.sh\n\n# Test manually\n.cursor/hooks/post-edit.sh src/test.ts\n```\n\n### Hook Fails Silently\n\n**Problem**: Hook runs but doesn't format\n\n**Debug**:\n```bash\n# Run hook with debug output\nDEBUG=ultracite:hooks .cursor/hooks/post-edit.sh src/test.ts\n\n# Check Ultracite can run\nnpx ultracite fix src/test.ts --verbose\n```\n\n**Common issues**:\n- Ultracite not installed: `bun add -D ultracite`\n- Invalid configuration: `npx ultracite doctor`\n- File not matched by patterns: Check `filePatterns`\n\n### Hook Timeout\n\n**Problem**: Hook takes too long, gets killed\n\n**Solution**: Increase timeout\n\n```json\n{\n \"aiHooks\": {\n \"timeoutMs\": 10000 // 10 seconds\n }\n}\n```\n\nOr optimize hook:\n```bash\n# Skip slow operations\nnpx ultracite fix $FILES \\\n --skip-typecheck \\\n --no-verify \\\n --quiet\n```\n\n### Conflicting Format Changes\n\n**Problem**: Hook reverts some of AI's formatting\n\n**Cause**: AI uses different format style than Ultracite\n\n**Solution**: Align AI rules with Ultracite config\n\n**1. Update AI Rules** (`.cursor/rules/ultracite.mdc`):\n```markdown\n- Use 2 spaces for indentation (matches Ultracite)\n- Use single quotes for strings (matches Ultracite)\n- No semicolons (matches Ultracite Biome config)\n```\n\n**2. Update Ultracite config** to match AI preferences:\n```jsonc\n{\n \"formatter\": {\n \"indentWidth\": 2,\n \"quoteStyle\": \"single\",\n \"semicolons\": false\n }\n}\n```\n\n## Advanced Usage\n\n### Conditional Formatting\n\nFormat only if file changed significantly:\n\n```bash\n#!/bin/bash\nEDITED_FILES=$1\n\nfor file in $EDITED_FILES; do\n # Check if file changed >10 lines\n CHANGED_LINES=$(git diff --numstat \"$file\" | awk '{print $1 + $2}')\n\n if [ \"$CHANGED_LINES\" -gt 10 ]; then\n npx ultracite fix \"$file\" --quiet\n fi\ndone\n```\n\n### Pre-Commit Integration\n\nCombine AI hooks with Git hooks:\n\n```bash\n# .husky/pre-commit\n#!/bin/bash\n\n# Format staged files (from AI edits or manual)\nnpx lint-staged\n\n# Or use Ultracite directly\nnpx ultracite fix --staged --quiet\n```\n\n### Multi-Provider Support\n\nUse different providers based on file type:\n\n```bash\n#!/bin/bash\nEDITED_FILES=$1\n\nfor file in $EDITED_FILES; do\n case \"$file\" in\n *.css|*.scss)\n # Use ESLint provider for CSS\n npx ultracite fix \"$file\" --provider eslint\n ;;\n *.ts|*.tsx)\n # Use Oxlint for TypeScript\n npx ultracite fix \"$file\" --provider oxlint\n ;;\n *)\n # Default to Biome\n npx ultracite fix \"$file\"\n ;;\n esac\ndone\n```\n\n## Best Practices\n\n### 1. Combine with AI Rules\n- Use AI Rules to guide generation\n- Use AI Hooks to polish result\n\n### 2. Set Reasonable Timeouts\n- Keep hooks fast (\u003c2s)\n- Avoid blocking AI workflow\n\n### 3. Exclude Generated Files\n- Don't format lock files, dist, node_modules\n- Focus on source files only\n\n### 4. Use Notifications\n- Enable toast notifications to see hook status\n- Helps debug when hooks fail\n\n### 5. Test Hooks Locally\n- Run hook manually before committing\n- Verify it works on sample files\n\n## Resources\n\n- AI Hooks Guide: https://www.ultracite.ai/guides/ai-hooks\n- Cursor Hooks Docs: https://cursor.sh/docs/hooks\n- Claude Code Hooks: https://docs.anthropic.com/claude/docs/hooks\n- Hook Examples: https://github.com/ultracite/ultracite/tree/main/examples/hooks\n- Troubleshooting: https://www.ultracite.ai/troubleshooting/ai-hooks\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":10252,"content_sha256":"16963f1ac2a9aa5f9df88c9b0836a9187a5a7bd0500167d6c506d0f6055f9fb5"},{"filename":"references/configuration-guide.md","content":"# Ultracite Configuration Guide\n\nComplete guide for configuring Ultracite with framework presets, customization, and file exclusion patterns.\n\n**Last Updated**: 2025-11-22\n\n---\n\n## Configuration File Structure\n\nUltracite uses Biome's configuration format (`biome.json` or `biome.jsonc`):\n\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\"],\n\n // Optional: Add framework-specific preset\n // \"extends\": [\"ultracite/core\", \"ultracite/react\"],\n\n // Optional: Customize rules\n \"linter\": {\n \"rules\": {\n \"a11y\": {\n \"noAutofocus\": \"off\" // Disable specific rule\n }\n }\n },\n\n // Optional: Exclude files/directories\n \"files\": {\n \"ignore\": [\n \"dist\",\n \"build\",\n \"coverage\",\n \"**/*.generated.ts\"\n ]\n }\n}\n```\n\n---\n\n## Framework Presets\n\n### React Preset (`ultracite/react`)\n\n**Extends**: `ultracite/core` + React-specific rules\n\n**Includes**:\n- React Hooks linting (exhaustive deps, rules of hooks)\n- JSX accessibility (a11y) checks\n- React-specific naming conventions\n- Component best practices\n\n**Configuration**:\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\", \"ultracite/react\"]\n}\n```\n\n**Key Rules**:\n- `useExhaustiveDependencies`: Ensures all dependencies are listed in hooks\n- `noArrayIndexKey`: Prevents using array indices as React keys\n- `useButtonType`: Requires explicit button types\n- `noChildrenProp`: Prevents passing children as props\n- `useJsxKeyInIterable`: Requires keys in JSX lists\n\n**Best For**:\n- Create React App projects\n- Vite React projects\n- Custom React setups\n\n---\n\n### Next.js Preset (`ultracite/nextjs`)\n\n**Extends**: `ultracite/react` + Next.js-specific rules\n\n**Includes**:\n- Everything from `ultracite/react`\n- Next.js-specific imports (e.g., `next/link`, `next/image`)\n- App Router conventions\n- Server Component rules\n- Performance optimizations\n\n**Configuration**:\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\", \"ultracite/nextjs\"]\n}\n```\n\n**Key Rules**:\n- `noHtmlLinkForPages`: Enforces using Next.js `\u003cLink>`\n- `noImgElement`: Enforces using Next.js `\u003cImage>`\n- `noTitleInDocumentHead`: Prevents `\u003ctitle>` in custom Document\n- Server/Client Component separation checks\n\n**Best For**:\n- Next.js 14+ projects (App Router)\n- Next.js Pages Router projects\n- Vercel deployments\n\n---\n\n### Vue Preset (`ultracite/vue`)\n\n**Extends**: `ultracite/core` + Vue-specific rules\n\n**Includes**:\n- Vue 3 Composition API linting\n- Template syntax validation\n- Reactivity system checks\n- Component naming conventions\n\n**Configuration**:\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\", \"ultracite/vue\"]\n}\n```\n\n**Key Rules**:\n- `useValidVModelName`: Ensures correct v-model naming\n- `noMutatingProps`: Prevents prop mutations\n- `requireEmitsOption`: Requires explicit emits declaration\n- `noReactiveReassign`: Prevents reassigning reactive variables\n\n**Best For**:\n- Nuxt 3 projects\n- Vue 3 + Vite projects\n- Quasar Framework\n\n---\n\n### Svelte Preset (`ultracite/svelte`)\n\n**Extends**: `ultracite/core` + Svelte-specific rules\n\n**Includes**:\n- Svelte 4/5 syntax validation\n- Reactive declarations linting\n- Component lifecycle checks\n- Store best practices\n\n**Configuration**:\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\", \"ultracite/svelte\"]\n}\n```\n\n**Key Rules**:\n- `noInnerDeclarations`: Prevents function declarations in blocks\n- `validEach`: Ensures each blocks have valid syntax\n- `noUnusedStores`: Detects unused store subscriptions\n- `preferReadableExports`: Enforces readable exports over defaults\n\n**Best For**:\n- SvelteKit projects\n- Svelte 5 (runes support)\n- Svelte component libraries\n\n---\n\n## Core Preset Features\n\nThe `ultracite/core` preset includes **200+ rules** across these categories:\n\n### 1. Correctness (85 rules)\nCatches actual bugs and logic errors:\n- `noUnreachable`: Detects unreachable code\n- `noUnsafeFinally`: Prevents unsafe control flow in finally blocks\n- `noConstantCondition`: Catches always-true/false conditions\n- `useValidForDirection`: Ensures correct for-loop direction\n- `noUnusedVariables`: Removes unused variables\n\n### 2. Suspicious (48 rules)\nFlags code that might indicate bugs:\n- `noDoubleEquals`: Enforces `===` over `==`\n- `noAsyncPromiseExecutor`: Prevents async Promise executors\n- `noConsoleLog`: Flags console.log statements\n- `noDebugger`: Removes debugger statements\n- `noShadowRestrictedNames`: Prevents shadowing global variables\n\n### 3. Style (35 rules)\nEnforces consistent code style:\n- `useConst`: Prefers `const` over `let` when possible\n- `useTemplate`: Prefers template literals over string concatenation\n- `useSingleVarDeclarator`: One variable per declaration\n- `noNegationElse`: Simplifies negated conditions\n- `noUnusedTemplateLiteral`: Removes unnecessary template literals\n\n### 4. Complexity (12 rules)\nReduces cognitive complexity:\n- `noExcessiveCognitiveComplexity`: Limits function complexity\n- `noForEach`: Prefers for-of loops over forEach\n- `useFlatMap`: Suggests flatMap over map().flat()\n- `noUselessFragments`: Removes unnecessary React fragments\n\n### 5. Performance (8 rules)\nOptimizes runtime performance:\n- `noAccumulatingSpread`: Prevents O(n²) spread operations\n- `noDelete`: Avoids delete operator (breaks V8 optimizations)\n- `useArrayLiterals`: Prefers `[]` over `new Array()`\n\n### 6. Security (6 rules)\nPrevents security vulnerabilities:\n- `noDangerouslySetInnerHtml`: Flags XSS risks\n- `noGlobalEval`: Prevents eval() usage\n- `noGlobalObjectCalls`: Prevents calling global objects as functions\n\n### 7. Accessibility (6 rules)\nEnsures inclusive UIs:\n- `useAltText`: Requires alt text on images\n- `useAnchorContent`: Ensures links have accessible content\n- `useButtonType`: Requires explicit button types\n- `useKeyWithClickEvents`: Ensures keyboard accessibility\n\n---\n\n## Advanced Customization\n\n### Disabling Rules\n\n**Single rule**:\n```jsonc\n{\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"noConsoleLog\": \"off\"\n }\n }\n }\n}\n```\n\n**Entire category**:\n```jsonc\n{\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"all\": false // Disable all suspicious rules\n }\n }\n }\n}\n```\n\n**Re-enable specific rule in disabled category**:\n```jsonc\n{\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"all\": false,\n \"noConsoleLog\": \"error\" // Re-enable this one\n }\n }\n }\n}\n```\n\n---\n\n### Rule Severity Levels\n\n```jsonc\n{\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"noConsoleLog\": \"warn\", // Warning (doesn't fail CI)\n \"noDebugger\": \"error\", // Error (fails CI)\n \"noDoubleEquals\": \"off\" // Disabled\n }\n }\n }\n}\n```\n\n---\n\n### Per-File Configuration\n\n**Disable rules for specific files**:\n```jsonc\n{\n \"overrides\": [\n {\n \"include\": [\"**/*.test.ts\", \"**/*.test.tsx\"],\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"noConsoleLog\": \"off\"\n }\n }\n }\n }\n ]\n}\n```\n\n**Different rules for different directories**:\n```jsonc\n{\n \"overrides\": [\n {\n \"include\": [\"src/legacy/**\"],\n \"linter\": {\n \"rules\": {\n \"complexity\": {\n \"all\": false // Legacy code exempted from complexity rules\n }\n }\n }\n }\n ]\n}\n```\n\n---\n\n## File Exclusion Patterns\n\n### Common Exclusions\n\n```jsonc\n{\n \"files\": {\n \"ignore\": [\n // Build outputs\n \"dist\",\n \"build\",\n \".next\",\n \"out\",\n\n // Dependencies\n \"node_modules\",\n \".pnpm-store\",\n\n // Test coverage\n \"coverage\",\n \".nyc_output\",\n\n // Generated files\n \"**/*.generated.ts\",\n \"**/*.d.ts\",\n\n // Cache directories\n \".cache\",\n \".turbo\",\n\n // Framework-specific\n \".nuxt\",\n \".svelte-kit\",\n \"vite.config.ts.timestamp-*\"\n ]\n }\n}\n```\n\n---\n\n### Glob Patterns\n\n**Wildcards**:\n- `*`: Matches any file/directory (non-recursive)\n- `**`: Matches any file/directory (recursive)\n- `?`: Matches single character\n\n**Examples**:\n```jsonc\n{\n \"files\": {\n \"ignore\": [\n \"*.config.js\", // All .config.js files in root\n \"**/*.config.js\", // All .config.js files anywhere\n \"src/generated/**\", // Everything in src/generated/\n \"**/__tests__/**\", // All __tests__ directories\n \"*.{spec,test}.ts\" // All .spec.ts and .test.ts files\n ]\n }\n}\n```\n\n---\n\n### Including Files\n\nBy default, Ultracite lints all supported files. Use `include` to limit scope:\n\n```jsonc\n{\n \"files\": {\n \"include\": [\n \"src/**/*.ts\",\n \"src/**/*.tsx\"\n ]\n }\n}\n```\n\n---\n\n## Formatter Configuration\n\n### Format Options\n\n```jsonc\n{\n \"formatter\": {\n \"enabled\": true,\n \"formatWithErrors\": false,\n \"indentStyle\": \"space\",\n \"indentWidth\": 2,\n \"lineEnding\": \"lf\",\n \"lineWidth\": 80\n }\n}\n```\n\n---\n\n### Per-Language Formatting\n\n```jsonc\n{\n \"formatter\": {\n \"enabled\": true\n },\n \"javascript\": {\n \"formatter\": {\n \"quoteStyle\": \"single\",\n \"semicolons\": \"asNeeded\",\n \"trailingCommas\": \"es5\"\n }\n },\n \"json\": {\n \"formatter\": {\n \"indentWidth\": 2\n }\n }\n}\n```\n\n---\n\n## Environment-Specific Configuration\n\n### Development\n\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\", \"ultracite/react\"],\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"noConsoleLog\": \"off\", // Allow console.log in dev\n \"noDebugger\": \"off\" // Allow debugger in dev\n }\n }\n }\n}\n```\n\n---\n\n### Production/CI\n\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\", \"ultracite/react\"],\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"noConsoleLog\": \"error\", // Fail on console.log\n \"noDebugger\": \"error\" // Fail on debugger\n }\n }\n }\n}\n```\n\n**Tip**: Use different config files per environment:\n```bash\n# Development\nultracite check --config-path=biome.dev.json\n\n# CI\nultracite check --config-path=biome.ci.json\n```\n\n---\n\n**See also:**\n- `git-hooks-setup.md` for pre-commit integration\n- `monorepo-configuration.md` for multi-package setups\n- `troubleshooting.md` for configuration issues\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":10362,"content_sha256":"f85e69365c6e31c56f612fd8a8007636c0a058210374693b3d471acf394fa209"},{"filename":"references/git-hooks-setup.md","content":"# Ultracite Git Hooks Setup\n\nComplete guide for integrating Ultracite with Husky, Lefthook, and lint-staged for automated pre-commit linting.\n\n**Last Updated**: 2025-11-22\n\n---\n\n## Overview\n\nGit hooks automatically run Ultracite before commits, preventing bad code from entering the repository.\n\n**Benefits**:\n- Catch errors before they reach CI\n- Enforce code quality standards\n- Reduce code review noise\n- Faster feedback loop\n\n**Supported Hook Managers**:\n- **Husky** (npm-based, most popular)\n- **Lefthook** (Go-based, faster)\n- **lint-staged** (runs linters on staged files only)\n\n---\n\n## Choosing a Hook Manager\n\n| Feature | Husky | Lefthook | lint-staged |\n|---------|-------|----------|-------------|\n| **Language** | Node.js | Go | Node.js |\n| **Speed** | Medium | Fast | Medium |\n| **Configuration** | Shell scripts | YAML | JavaScript |\n| **Popularity** | 40k+ stars | 5k+ stars | 13k+ stars |\n| **Best For** | General use | Monorepos | Simple linting |\n| **Windows Support** | ✅ | ✅ | ✅ |\n\n**Recommendation**:\n- **First-time setup**: Husky (most documentation)\n- **Performance-critical**: Lefthook (2-3x faster)\n- **Simple projects**: lint-staged only\n\n---\n\n## Husky Integration\n\n### Installation\n\n```bash\n# Install Husky\nbun add -D husky\n\n# Initialize Husky\nbunx husky init\n```\n\nThis creates:\n- `.husky/` directory\n- `.husky/pre-commit` hook\n\n---\n\n### Basic Setup\n\n**Option 1: Lint all files** (simple, slower):\n\n```bash\n# .husky/pre-commit\n#!/usr/bin/env sh\n. \"$(dirname -- \"$0\")/_/husky.sh\"\n\nultracite check --write\n```\n\n**Option 2: Lint staged files only** (recommended):\n\n```bash\n# .husky/pre-commit\n#!/usr/bin/env sh\n. \"$(dirname -- \"$0\")/_/husky.sh\"\n\nultracite check --staged --write\n```\n\n---\n\n### Advanced Setup with lint-staged\n\n**Install lint-staged**:\n```bash\nbun add -D lint-staged\n```\n\n**Configure lint-staged** in `package.json`:\n```json\n{\n \"lint-staged\": {\n \"*.{js,jsx,ts,tsx,json,css}\": [\n \"ultracite check --write --no-errors-on-unmatched --files-ignore-unknown=true\"\n ]\n }\n}\n```\n\n**Update `.husky/pre-commit`**:\n```bash\n#!/usr/bin/env sh\n. \"$(dirname -- \"$0\")/_/husky.sh\"\n\nbunx lint-staged\n```\n\n---\n\n### Framework-Specific Examples\n\n**Next.js**:\n```json\n{\n \"lint-staged\": {\n \"*.{js,jsx,ts,tsx}\": [\n \"ultracite check --write --no-errors-on-unmatched\"\n ],\n \"*.{json,css}\": [\n \"ultracite format --write\"\n ]\n }\n}\n```\n\n**Turborepo Monorepo**:\n```json\n{\n \"lint-staged\": {\n \"apps/**/*.{js,jsx,ts,tsx}\": [\n \"ultracite check --write --no-errors-on-unmatched\"\n ],\n \"packages/**/*.{js,jsx,ts,tsx}\": [\n \"ultracite check --write --no-errors-on-unmatched\"\n ]\n }\n}\n```\n\n---\n\n### Troubleshooting Husky\n\n**Hook not executing**:\n```bash\n# Make hook executable\nchmod +x .husky/pre-commit\n\n# Verify hook exists\nls -la .husky/\n```\n\n**Hook fails silently**:\n```bash\n# Add debugging\nset -x # Add to top of .husky/pre-commit\n\n# Test hook manually\n.husky/pre-commit\n```\n\n**Skipping hooks** (emergency only):\n```bash\ngit commit --no-verify -m \"Emergency fix\"\n```\n\n---\n\n## Lefthook Integration\n\n### Installation\n\n```bash\n# Install Lefthook\nbun add -D lefthook\n\n# Initialize Lefthook\nbunx lefthook install\n```\n\nThis creates:\n- `lefthook.yml` configuration\n- Git hooks in `.git/hooks/`\n\n---\n\n### Basic Setup\n\nCreate `lefthook.yml`:\n\n```yaml\npre-commit:\n commands:\n ultracite:\n glob: \"*.{js,jsx,ts,tsx,json,css}\"\n run: ultracite check --write --no-errors-on-unmatched --files-ignore-unknown=true {staged_files}\n```\n\n---\n\n### Advanced Setup\n\n**Multiple commands**:\n```yaml\npre-commit:\n parallel: true # Run commands in parallel\n commands:\n ultracite-lint:\n glob: \"*.{js,jsx,ts,tsx}\"\n run: ultracite check --write --no-errors-on-unmatched {staged_files}\n\n ultracite-format:\n glob: \"*.{json,css,md}\"\n run: ultracite format --write {staged_files}\n\n type-check:\n glob: \"*.{ts,tsx}\"\n run: tsc --noEmit {staged_files}\n```\n\n---\n\n### Monorepo Setup\n\n**Root `lefthook.yml`**:\n```yaml\npre-commit:\n commands:\n ultracite-apps:\n glob: \"apps/**/*.{js,jsx,ts,tsx}\"\n run: ultracite check --write --config-path=apps/biome.json {staged_files}\n\n ultracite-packages:\n glob: \"packages/**/*.{js,jsx,ts,tsx}\"\n run: ultracite check --write --config-path=packages/biome.json {staged_files}\n```\n\n---\n\n### Performance Optimization\n\n**Skip on merge commits** (faster rebases):\n```yaml\npre-commit:\n skip:\n - merge\n commands:\n ultracite:\n run: ultracite check --staged --write\n```\n\n**Fail fast** (stop on first error):\n```yaml\npre-commit:\n piped: true # Stop pipeline on error\n commands:\n ultracite:\n run: ultracite check --staged --write\n```\n\n---\n\n### Troubleshooting Lefthook\n\n**Hook not found**:\n```bash\n# Reinstall hooks\nbunx lefthook install\n\n# Verify installation\nls -la .git/hooks/pre-commit\n```\n\n**YAML syntax errors**:\n```bash\n# Validate config\nbunx lefthook run pre-commit --verbose\n```\n\n**Skipping hooks** (emergency only):\n```bash\nLEFTHOOK=0 git commit -m \"Emergency fix\"\n```\n\n---\n\n## lint-staged (Standalone)\n\n### Installation\n\n```bash\nbun add -D lint-staged husky\nbunx husky init\n```\n\n---\n\n### Configuration Options\n\n**Option 1: `package.json`** (recommended for simple setups):\n\n```json\n{\n \"lint-staged\": {\n \"*.{js,jsx,ts,tsx}\": [\n \"ultracite check --write --no-errors-on-unmatched\"\n ],\n \"*.{json,css}\": [\n \"ultracite format --write\"\n ]\n }\n}\n```\n\n**Option 2: `.lintstagedrc.json`** (cleaner):\n\n```json\n{\n \"*.{js,jsx,ts,tsx}\": [\n \"ultracite check --write --no-errors-on-unmatched\"\n ],\n \"*.{json,css}\": [\n \"ultracite format --write\"\n ]\n}\n```\n\n**Option 3: `lint-staged.config.js`** (dynamic configuration):\n\n```javascript\nexport default {\n '*.{js,jsx,ts,tsx}': (filenames) => [\n `ultracite check --write --no-errors-on-unmatched ${filenames.join(' ')}`,\n ],\n '*.{json,css}': (filenames) => [\n `ultracite format --write ${filenames.join(' ')}`,\n ],\n};\n```\n\n---\n\n### Advanced Patterns\n\n**Conditional linting**:\n```javascript\nexport default {\n '*.{js,jsx,ts,tsx}': (filenames) => {\n const isApp = filenames.some(f => f.startsWith('apps/'));\n const config = isApp ? 'apps/biome.json' : 'biome.json';\n\n return [\n `ultracite check --config-path=${config} --write ${filenames.join(' ')}`,\n ];\n },\n};\n```\n\n**Multiple commands per file type**:\n```json\n{\n \"*.{js,jsx,ts,tsx}\": [\n \"ultracite check --write --no-errors-on-unmatched\",\n \"vitest related --run\"\n ]\n}\n```\n\n---\n\n### Troubleshooting lint-staged\n\n**Files not being linted**:\n```bash\n# Test manually\nbunx lint-staged --debug\n\n# Check staged files\ngit diff --cached --name-only\n```\n\n**Glob patterns not matching**:\n```bash\n# Test pattern matching\nbunx lint-staged --diff=\"main...HEAD\"\n```\n\n**Hangs on large changesets**:\n```json\n{\n \"lint-staged\": {\n \"*.{js,jsx,ts,tsx}\": [\n \"ultracite check --write --no-errors-on-unmatched --files-max-size=1048576\"\n ]\n }\n}\n```\n\n---\n\n## Detection Logic\n\nUltracite CLI automatically detects existing hook managers:\n\n```bash\n# Check for Husky\nls .husky/pre-commit\n\n# Check for Lefthook\nls lefthook.yml\n\n# Check for lint-staged\ncat package.json | grep \"lint-staged\"\n```\n\n**Auto-configuration priority**:\n1. If `lefthook.yml` exists → Use Lefthook\n2. Else if `.husky/` exists → Use Husky\n3. Else → Prompt user to choose\n\n---\n\n## CI Integration\n\n### GitHub Actions\n\n```yaml\nname: Lint\n\non: [push, pull_request]\n\njobs:\n lint:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: oven-sh/setup-bun@v1\n\n - name: Install dependencies\n run: bun install\n\n - name: Run Ultracite\n run: bun ultracite ci\n```\n\n---\n\n### GitLab CI\n\n```yaml\nlint:\n image: node:20\n script:\n - npm install -g bun\n - bun install\n - bun ultracite ci\n```\n\n---\n\n### Cloudflare Pages\n\n```yaml\n# .cloudflare/pages.yml\nbuild:\n command: bun run build\n environment:\n NODE_VERSION: 20\n pre_build:\n - bun install\n - bun ultracite ci\n```\n\n---\n\n## Best Practices\n\n1. **Use `--staged` flag** to lint only changed files (faster)\n2. **Use `--write` flag** to auto-fix issues\n3. **Use `--no-errors-on-unmatched`** to ignore unsupported file types\n4. **Combine with lint-staged** for maximum performance\n5. **Skip hooks sparingly** (only for emergencies)\n6. **Test hooks locally** before pushing to CI\n7. **Document hook setup** in project README\n8. **Use Lefthook for monorepos** (better performance)\n\n---\n\n**See also:**\n- `configuration-guide.md` for Ultracite configuration\n- `ai-editor-integration.md` for editor hooks\n- `troubleshooting.md` for hook failures\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":8615,"content_sha256":"6aecb947e6111f6eb8a1fda0f506d13af9e69172f82e5c517c48fbcb6e5ca354"},{"filename":"references/limitations-and-workarounds.md","content":"# Ultracite Limitations and Workarounds\n\nKnown limitations of Ultracite/Biome and practical workarounds for common scenarios.\n\n**Last Updated**: 2025-11-22\n\n---\n\n## CSS/SCSS Linting\n\n### Limitation\n\n**Issue**: Biome does not lint CSS, SCSS, or Less files.\n\n**GitHub Issue**: https://github.com/biomejs/biome/issues/13\n\n**Status**: Planned for Biome v2.0 (no ETA)\n\n---\n\n### Workaround: Use Stylelint\n\n**Install Stylelint**:\n```bash\nbun add -D stylelint stylelint-config-standard\n```\n\n**Configure Stylelint** (`stylelint.config.js`):\n```javascript\nexport default {\n extends: ['stylelint-config-standard'],\n rules: {\n 'color-hex-length': 'short',\n 'declaration-block-no-redundant-longhand-properties': true,\n },\n};\n```\n\n**Update Scripts**:\n```json\n{\n \"scripts\": {\n \"lint\": \"ultracite check && stylelint '**/*.css'\",\n \"lint:fix\": \"ultracite check --write && stylelint '**/*.css' --fix\"\n }\n}\n```\n\n**Pre-Commit Hook** (Husky):\n```bash\n# .husky/pre-commit\n#!/usr/bin/env sh\n. \"$(dirname -- \"$0\")/_/husky.sh\"\n\nultracite check --staged --write\nstylelint '**/*.css' --fix\n```\n\n---\n\n## Framework Support Gaps\n\n### Angular\n\n**Limitation**: No official Angular preset in Ultracite.\n\n**Workaround**: Use `ultracite/core` and add Angular-specific rules manually:\n\n`biome.json`:\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\"],\n\n \"linter\": {\n \"rules\": {\n \"style\": {\n \"useNamingConvention\": {\n \"level\": \"error\",\n \"options\": {\n \"strictCase\": true,\n \"conventions\": [\n {\n \"selector\": { \"kind\": \"class\" },\n \"match\": \"^[A-Z][a-zA-Z0-9]*$\", // PascalCase for components\n \"formats\": [\"PascalCase\"]\n },\n {\n \"selector\": { \"kind\": \"variable\" },\n \"match\": \"^[a-z][a-zA-Z0-9]*$\", // camelCase for variables\n \"formats\": [\"camelCase\"]\n }\n ]\n }\n }\n }\n }\n }\n}\n```\n\n**Alternative**: Keep ESLint with `@angular-eslint` plugin:\n\n```json\n{\n \"scripts\": {\n \"lint\": \"ng lint && ultracite check\"\n }\n}\n```\n\n---\n\n### Astro\n\n**Limitation**: No official Astro preset.\n\n**Workaround**: Use `ultracite/core` for `.js/.ts` files:\n\n`biome.json`:\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\"],\n\n \"files\": {\n \"include\": [\"src/**/*.js\", \"src/**/*.ts\"],\n \"ignore\": [\"src/**/*.astro\"] // Skip .astro files\n }\n}\n```\n\n**For `.astro` files**: Use `eslint-plugin-astro`:\n\n```bash\nbun add -D eslint eslint-plugin-astro\n```\n\n```json\n{\n \"scripts\": {\n \"lint\": \"ultracite check src/**/*.{js,ts} && eslint src/**/*.astro\"\n }\n}\n```\n\n---\n\n### Qwik\n\n**Limitation**: No official Qwik preset.\n\n**Workaround**: Use `ultracite/react` (similar JSX syntax):\n\n`biome.json`:\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\", \"ultracite/react\"]\n}\n```\n\n**Note**: Some Qwik-specific patterns (e.g., ` ultracite — Skillopedia suffix for signals) may trigger warnings.\n\n---\n\n### Solid.js\n\n**Limitation**: No official Solid preset.\n\n**Workaround**: Use `ultracite/react` (very similar syntax):\n\n`biome.json`:\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\", \"ultracite/react\"]\n}\n```\n\n**Disable incompatible React rules**:\n```jsonc\n{\n \"linter\": {\n \"rules\": {\n \"correctness\": {\n \"useExhaustiveDependencies\": \"off\" // Solid doesn't use deps arrays\n }\n }\n }\n}\n```\n\n---\n\n## ESLint Plugin Ecosystem\n\n### Limitation\n\n**Issue**: Many ESLint plugins have no Biome equivalent:\n- `eslint-plugin-import` (import sorting)\n- `eslint-plugin-testing-library` (test linting)\n- `eslint-plugin-jest` (Jest best practices)\n- `eslint-plugin-cypress` (Cypress linting)\n- `eslint-plugin-storybook` (Storybook rules)\n\n---\n\n### Workaround 1: Run ESLint Alongside Ultracite\n\n**For test files only**:\n```bash\nbun add -D eslint eslint-plugin-testing-library eslint-plugin-jest\n```\n\n**Configure ESLint for tests** (`.eslintrc.test.json`):\n```json\n{\n \"extends\": [\"plugin:testing-library/react\", \"plugin:jest/recommended\"],\n \"rules\": {\n \"testing-library/prefer-screen-queries\": \"error\"\n }\n}\n```\n\n**Update Scripts**:\n```json\n{\n \"scripts\": {\n \"lint\": \"ultracite check\",\n \"lint:tests\": \"eslint **/*.test.ts --config .eslintrc.test.json\"\n }\n}\n```\n\n---\n\n### Workaround 2: Use Biome's Import Sorting\n\n**For import organization** (partial replacement for `eslint-plugin-import`):\n\n`biome.json`:\n```jsonc\n{\n \"organizeImports\": {\n \"enabled\": true\n }\n}\n```\n\n**VS Code**:\n`.vscode/settings.json`:\n```json\n{\n \"editor.codeActionsOnSave\": {\n \"source.organizeImports.biome\": \"explicit\"\n }\n}\n```\n\n**Limitations**: Biome's import sorting is basic compared to `eslint-plugin-import`.\n\n---\n\n## File Type Support\n\n### Markdown\n\n**Limitation**: Biome does not lint Markdown files.\n\n**Workaround**: Use `markdownlint`:\n\n```bash\nbun add -D markdownlint-cli\n```\n\n**Configure** (`.markdownlint.json`):\n```json\n{\n \"MD013\": false, // Line length\n \"MD033\": false // Inline HTML\n}\n```\n\n**Update Scripts**:\n```json\n{\n \"scripts\": {\n \"lint\": \"ultracite check && markdownlint '**/*.md'\"\n }\n}\n```\n\n---\n\n### YAML\n\n**Limitation**: Biome does not lint YAML files.\n\n**Workaround**: Use `yamllint`:\n\n```bash\nbun add -D yamllint\n```\n\n**Update Scripts**:\n```json\n{\n \"scripts\": {\n \"lint\": \"ultracite check && yamllint '**/*.yml'\"\n }\n}\n```\n\n---\n\n### HTML\n\n**Limitation**: Biome does not lint standalone HTML files (only JSX).\n\n**Workaround**: Use `htmlhint`:\n\n```bash\nbun add -D htmlhint\n```\n\n**Update Scripts**:\n```json\n{\n \"scripts\": {\n \"lint\": \"ultracite check && htmlhint '**/*.html'\"\n }\n}\n```\n\n---\n\n## Language Feature Support\n\n### Decorators\n\n**Limitation**: Biome has limited support for TypeScript decorators (Stage 3 proposal).\n\n**Status**: Partial support added in Biome v1.9.\n\n**Workaround**: Enable unsafe decorators:\n\n`biome.json`:\n```jsonc\n{\n \"javascript\": {\n \"parser\": {\n \"unsafeParameterDecoratorsEnabled\": true\n }\n }\n}\n```\n\n**If issues persist**: Keep TypeScript compiler for type checking:\n\n```json\n{\n \"scripts\": {\n \"lint\": \"ultracite check && tsc --noEmit\"\n }\n}\n```\n\n---\n\n### JSDoc Validation\n\n**Limitation**: Biome does not validate JSDoc syntax or types.\n\n**Workaround**: Use `eslint-plugin-jsdoc`:\n\n```bash\nbun add -D eslint eslint-plugin-jsdoc\n```\n\n**Configure ESLint**:\n```json\n{\n \"extends\": [\"plugin:jsdoc/recommended\"],\n \"rules\": {\n \"jsdoc/require-param-description\": \"error\"\n }\n}\n```\n\n---\n\n## Configuration Limitations\n\n### No `.js` Config Files\n\n**Limitation**: Biome only supports `.json` or `.jsonc` config files, not JavaScript.\n\n**Workaround**: Use environment-specific configs:\n\n**Development**:\n```bash\nultracite check --config-path=biome.dev.json\n```\n\n**Production/CI**:\n```bash\nultracite check --config-path=biome.ci.json\n```\n\n**Or**: Use scripts to generate config dynamically:\n\n**`scripts/generate-config.js`**:\n```javascript\nimport fs from 'fs';\n\nconst config = {\n $schema: \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n extends: [\"ultracite/core\"],\n linter: {\n rules: {\n suspicious: {\n noConsoleLog: process.env.NODE_ENV === 'production' ? 'error' : 'off',\n },\n },\n },\n};\n\nfs.writeFileSync('biome.json', JSON.stringify(config, null, 2));\n```\n\n**Usage**:\n```bash\nnode scripts/generate-config.js && ultracite check\n```\n\n---\n\n### No Per-File Overrides (Yet)\n\n**Limitation**: Biome doesn't support per-file rule overrides like ESLint's `overrides`.\n\n**GitHub Issue**: https://github.com/biomejs/biome/issues/2228\n\n**Workaround**: Use separate configs per directory:\n\n**`src/biome.json`**:\n```jsonc\n{\n \"extends\": [\"../biome.json\"],\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"noConsoleLog\": \"off\" // Allow in src/\n }\n }\n }\n}\n```\n\n**`tests/biome.json`**:\n```jsonc\n{\n \"extends\": [\"../biome.json\"],\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"noConsoleLog\": \"off\" // Allow in tests/\n }\n }\n }\n}\n```\n\n---\n\n## Editor Integration\n\n### IntelliJ IDEA / WebStorm\n\n**Limitation**: No official Biome plugin for JetBrains IDEs.\n\n**Workaround 1**: Use File Watcher\n\n**Settings → Tools → File Watchers → Add**:\n- **File type**: JavaScript/TypeScript\n- **Program**: `$ProjectFileDir$/node_modules/.bin/ultracite`\n- **Arguments**: `check --write $FilePath ultracite — Skillopedia \n- **Output paths to refresh**: `$FilePath ultracite — Skillopedia \n\n**Workaround 2**: Use \"Run on Save\" plugin\n\nInstall: https://plugins.jetbrains.com/plugin/7177-run-on-save\n\n**Configure**:\n```\nCommand: node_modules/.bin/ultracite check --write {file}\n```\n\n---\n\n### Neovim\n\n**Limitation**: No official Biome plugin.\n\n**Workaround**: Use `null-ls.nvim` with Biome:\n\n**Install**:\n```lua\n-- In your neovim config\nuse {\n 'jose-elias-alvarez/null-ls.nvim',\n requires = { 'nvim-lua/plenary.nvim' },\n}\n```\n\n**Configure**:\n```lua\nlocal null_ls = require(\"null-ls\")\n\nnull_ls.setup({\n sources = {\n null_ls.builtins.formatting.biome,\n null_ls.builtins.diagnostics.biome,\n },\n})\n```\n\n---\n\n## Monorepo Limitations\n\n### No Global Config Override\n\n**Limitation**: Can't override root config for all packages at once.\n\n**Workaround**: Use shared config file:\n\n**`.ultracite/shared.json`**:\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\"],\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"noConsoleLog\": \"off\"\n }\n }\n }\n}\n```\n\n**Each package extends shared config**:\n\n**`apps/web/biome.json`**:\n```jsonc\n{\n \"extends\": [\"../../.ultracite/shared.json\", \"ultracite/nextjs\"]\n}\n```\n\n**`packages/ui/biome.json`**:\n```jsonc\n{\n \"extends\": [\"../../.ultracite/shared.json\", \"ultracite/react\"]\n}\n```\n\n---\n\n## Performance Limitations\n\n### Large File Handling\n\n**Limitation**: Biome can be slow on very large files (>10,000 lines).\n\n**Workaround**: Exclude large generated files:\n\n`biome.json`:\n```jsonc\n{\n \"files\": {\n \"ignore\": [\n \"**/*.generated.ts\",\n \"**/*.bundle.js\"\n ],\n \"maxSize\": 1048576 // 1 MB limit\n }\n}\n```\n\n---\n\n### Memory Usage in CI\n\n**Limitation**: Biome can use significant memory in large codebases.\n\n**Workaround**: Increase Node memory limit:\n\n```bash\nNODE_OPTIONS=\"--max-old-space-size=4096\" ultracite check\n```\n\n---\n\n## Migration Limitations\n\n### No Auto-Fix for All ESLint Rules\n\n**Limitation**: `ultracite migrate eslint` doesn't convert all ESLint rules.\n\n**Workaround**: Manual mapping required for complex rules:\n\n**ESLint** (`no-restricted-syntax`):\n```json\n{\n \"rules\": {\n \"no-restricted-syntax\": [\"error\", \"ForInStatement\"]\n }\n}\n```\n\n**Biome** (no direct equivalent):\n```jsonc\n{\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"noForInLoop\": \"error\" // Manually add equivalent rule\n }\n }\n }\n}\n```\n\n---\n\n## Future Improvements\n\n**Planned in Biome v2.0**:\n- CSS/SCSS linting\n- Per-file rule overrides\n- Plugin system for custom rules\n- More framework presets (Angular, Astro, etc.)\n\n**Track progress**: https://github.com/biomejs/biome/issues\n\n---\n\n## Best Practices\n\n1. **Combine tools strategically**: Use Ultracite for JS/TS, Stylelint for CSS, markdownlint for docs\n2. **Document limitations**: Keep this guide updated as you discover gaps\n3. **Stay updated**: Follow Biome releases for new features\n4. **Contribute**: Report missing features to Biome GitHub\n5. **Use ESLint selectively**: Only for plugins without Biome equivalents\n6. **Test migrations**: Verify all rules work after migrating from ESLint/Prettier\n\n---\n\n**See also:**\n- `migration-guides.md` for ESLint/Prettier migration\n- `configuration-guide.md` for Ultracite setup\n- `troubleshooting.md` for common issues\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":11773,"content_sha256":"41223e38a79841064d910c0fceb19f7cb780da29e70faa6af30a9dedc7bc38c3"},{"filename":"references/mcp-integration.md","content":"---\ntitle: MCP Server Integration Reference\nfeature: Model Context Protocol (MCP) Server\nversion: v7.0+\npurpose: Integrate Ultracite knowledge with AI assistants\ndescription: Guide for integrating Ultracite with AI assistants via Model Context Protocol\n---\n\n# MCP Server Integration Reference\n\n**Feature**: Model Context Protocol (MCP) Server\n**Version**: v7.0+\n**Purpose**: Integrate Ultracite knowledge with AI assistants\n\n## Overview\n\nThe Ultracite MCP Server provides AI assistants (Claude Desktop, Cursor, etc.) with access to Ultracite's rule documentation, configuration guidance, and troubleshooting knowledge. This enables AI assistants to answer Ultracite-specific questions and provide better code suggestions.\n\n## What is MCP?\n\n**Model Context Protocol (MCP)** is an open protocol that enables AI assistants to access external tools and knowledge bases. The Ultracite MCP Server exposes:\n\n- Rule documentation (200+ rules)\n- Configuration schemas\n- Framework preset details\n- Troubleshooting guides\n- Provider comparison information\n\n## Installation\n\n### Prerequisites\n\n- Ultracite v7.0+\n- Supported AI client (Claude Desktop, Cursor, etc.)\n- Node.js v18+ (for MCP server runtime)\n\n### Install MCP Server\n\n```bash\n# Install Ultracite MCP server globally\nnpx ultracite mcp install\n\n# Or install locally in project\nnpx ultracite mcp install --local\n```\n\n### Configure AI Client\n\n#### Claude Desktop\n\n```bash\n# Auto-configure Claude Desktop\nnpx ultracite mcp configure --client claude-desktop\n\n# Manual configuration\n# Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)\n# or %APPDATA%\\Claude\\claude_desktop_config.json (Windows)\n```\n\n**Configuration file** (`claude_desktop_config.json`):\n```json\n{\n \"mcpServers\": {\n \"ultracite\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ultracite/mcp-server\"],\n \"env\": {\n \"ULTRACITE_PROJECT_PATH\": \"/path/to/your/project\"\n }\n }\n }\n}\n```\n\n#### Cursor\n\n```bash\n# Auto-configure Cursor\nnpx ultracite mcp configure --client cursor\n\n# Manual configuration\n# Add to ~/.cursor/mcp.json\n```\n\n**Configuration file** (`.cursor/mcp.json`):\n```json\n{\n \"servers\": {\n \"ultracite\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ultracite/mcp-server\"],\n \"env\": {\n \"ULTRACITE_PROJECT_PATH\": \"${workspaceFolder}\"\n }\n }\n }\n}\n```\n\n#### Other MCP Clients\n\nFor other MCP-compatible clients:\n\n```json\n{\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ultracite/mcp-server\"],\n \"env\": {\n \"ULTRACITE_PROJECT_PATH\": \"/path/to/project\"\n }\n}\n```\n\n## Available MCP Tools\n\nThe Ultracite MCP Server provides these tools to AI assistants:\n\n### 1. `ultracite_get_rule`\n\nGet detailed documentation for a specific rule.\n\n**Parameters**:\n- `rule_name` (string): Rule identifier (e.g., \"useConst\", \"noExplicitAny\")\n\n**Example**:\n```typescript\n// AI assistant can query:\nultracite_get_rule({ rule_name: \"noExplicitAny\" })\n\n// Returns:\n{\n \"name\": \"noExplicitAny\",\n \"category\": \"suspicious\",\n \"description\": \"Disallow the use of the 'any' type\",\n \"rationale\": \"The 'any' type defeats the purpose of TypeScript...\",\n \"examples\": { ... },\n \"fixes\": { ... }\n}\n```\n\n### 2. `ultracite_search_rules`\n\nSearch for rules by keyword or category.\n\n**Parameters**:\n- `query` (string): Search term\n- `category` (string, optional): Rule category filter\n\n**Example**:\n```typescript\nultracite_search_rules({ query: \"unused\", category: \"correctness\" })\n\n// Returns list of rules matching \"unused\" in \"correctness\" category\n```\n\n### 3. `ultracite_get_preset`\n\nGet preset configuration details.\n\n**Parameters**:\n- `preset_name` (string): Preset identifier (e.g., \"biome/core\", \"biome/react\")\n\n**Example**:\n```typescript\nultracite_get_preset({ preset_name: \"biome/react\" })\n\n// Returns:\n{\n \"name\": \"biome/react\",\n \"description\": \"React + JSX rules\",\n \"extends\": [\"biome/core\"],\n \"rules\": { ... }\n}\n```\n\n### 4. `ultracite_troubleshoot`\n\nGet troubleshooting guidance for common issues.\n\n**Parameters**:\n- `issue` (string): Issue description or error message\n\n**Example**:\n```typescript\nultracite_troubleshoot({ issue: \"format on save not working\" })\n\n// Returns troubleshooting steps and solutions\n```\n\n### 5. `ultracite_get_config_schema`\n\nGet configuration file schema for validation.\n\n**Parameters**:\n- `provider` (string): Provider name (biome, eslint, oxlint)\n\n**Example**:\n```typescript\nultracite_get_config_schema({ provider: \"biome\" })\n\n// Returns JSON schema for biome.jsonc\n```\n\n## Usage in AI Assistants\n\n### Claude Desktop\n\nOnce configured, you can ask Claude:\n\n```\nUser: \"What does the noExplicitAny rule do in Ultracite?\"\n\nClaude: [Uses ultracite_get_rule tool]\n\"The noExplicitAny rule (category: suspicious) disallows the use of the 'any' type in TypeScript. It's enabled by default in ultracite/biome/core because...\"\n```\n\n### Cursor\n\nAsk Cursor to help with Ultracite configuration:\n\n```\nUser: \"Help me configure Ultracite for React\"\n\nCursor: [Uses ultracite_get_preset tool]\n\"For a React project, you should use the ultracite/biome/react preset. Here's the recommended configuration...\"\n```\n\n## Environment Variables\n\nConfigure MCP server behavior:\n\n### `ULTRACITE_PROJECT_PATH`\n\n**Required**: Path to project root (where `biome.jsonc` is located)\n\n```json\n{\n \"env\": {\n \"ULTRACITE_PROJECT_PATH\": \"/Users/you/projects/my-app\"\n }\n}\n```\n\n### `ULTRACITE_LOG_LEVEL`\n\n**Optional**: Logging verbosity (debug, info, warn, error)\n\n```json\n{\n \"env\": {\n \"ULTRACITE_LOG_LEVEL\": \"debug\"\n }\n}\n```\n\n### `ULTRACITE_CACHE_DIR`\n\n**Optional**: Cache directory for rule documentation\n\n```json\n{\n \"env\": {\n \"ULTRACITE_CACHE_DIR\": \"/tmp/ultracite-mcp-cache\"\n }\n}\n```\n\n## Testing MCP Server\n\n### Verify Installation\n\n```bash\n# Test MCP server directly\nnpx @ultracite/mcp-server --test\n\n# Output:\n# ✓ MCP server running\n# ✓ 5 tools available\n# ✓ Rule database loaded (200+ rules)\n```\n\n### Test in AI Client\n\n**Claude Desktop**:\n1. Open Claude Desktop\n2. Start new conversation\n3. Ask: \"List available Ultracite tools\"\n4. Claude should list MCP tools if configured correctly\n\n**Cursor**:\n1. Open Cursor\n2. Use AI chat\n3. Ask: \"What Ultracite rules are available?\"\n4. Cursor should query MCP server\n\n## Troubleshooting\n\n### MCP Server Not Starting\n\n**Problem**: AI client can't connect to MCP server\n\n**Check**:\n1. Node.js v18+ installed: `node --version`\n2. `npx` available: `npx --version`\n3. MCP server package installed: `npx @ultracite/mcp-server --version`\n\n**Solution**:\n```bash\n# Reinstall MCP server\nnpx ultracite mcp install --force\n\n# Test standalone\nnpx @ultracite/mcp-server --test\n```\n\n### AI Client Not Detecting Tools\n\n**Problem**: Claude/Cursor doesn't see Ultracite tools\n\n**Check configuration file**:\n\n**macOS (Claude Desktop)**:\n```bash\ncat ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n```\n\n**Cursor**:\n```bash\ncat ~/.cursor/mcp.json\n```\n\n**Verify JSON syntax**:\n```bash\n# Validate JSON\ncat config.json | jq .\n```\n\n### \"Project Path Not Found\" Error\n\n**Problem**: MCP server can't find project\n\n**Solution**: Set correct `ULTRACITE_PROJECT_PATH`:\n\n```json\n{\n \"env\": {\n \"ULTRACITE_PROJECT_PATH\": \"/absolute/path/to/project\"\n }\n}\n```\n\n**Verify path**:\n```bash\n# Path should contain biome.jsonc or package.json\nls /path/to/project/biome.jsonc\n```\n\n### Rules Not Loading\n\n**Problem**: MCP server returns empty rule list\n\n**Solution**: Clear cache and reload:\n\n```bash\n# Clear MCP cache\nrm -rf /tmp/ultracite-mcp-cache\n\n# Restart AI client\n```\n\n## Advanced Configuration\n\n### Multi-Project Setup\n\nConfigure MCP server for multiple projects:\n\n```json\n{\n \"mcpServers\": {\n \"ultracite-project-a\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ultracite/mcp-server\"],\n \"env\": {\n \"ULTRACITE_PROJECT_PATH\": \"/path/to/project-a\",\n \"ULTRACITE_SERVER_NAME\": \"project-a\"\n }\n },\n \"ultracite-project-b\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ultracite/mcp-server\"],\n \"env\": {\n \"ULTRACITE_PROJECT_PATH\": \"/path/to/project-b\",\n \"ULTRACITE_SERVER_NAME\": \"project-b\"\n }\n }\n }\n}\n```\n\n### Custom Rule Database\n\nPoint MCP server to custom rule database:\n\n```json\n{\n \"env\": {\n \"ULTRACITE_RULES_DB\": \"/path/to/custom-rules.json\"\n }\n}\n```\n\n### Performance Tuning\n\nEnable caching for faster responses:\n\n```json\n{\n \"env\": {\n \"ULTRACITE_ENABLE_CACHE\": \"true\",\n \"ULTRACITE_CACHE_TTL\": \"3600\" // 1 hour\n }\n}\n```\n\n## Security Considerations\n\n### MCP Server Permissions\n\nThe MCP server:\n- ✅ Read-only access to rule documentation\n- ✅ Reads project configuration files\n- ❌ Does NOT modify files\n- ❌ Does NOT execute code\n- ❌ Does NOT access network (except for updates)\n\n### Environment Isolation\n\nMCP server runs in isolated environment:\n- No access to environment variables (except configured ones)\n- No access to file system outside project path\n- No network access\n\n## Resources\n\n- [MCP Protocol Spec](https://modelcontextprotocol.io/)\n- [Ultracite MCP Docs](https://www.ultracite.ai/mcp)\n- [Claude Desktop MCP Guide](https://docs.anthropic.com/claude/docs/mcp)\n- [MCP Server GitHub](https://github.com/ultracite/mcp-server)\n- [Troubleshooting](https://www.ultracite.ai/mcp/troubleshooting)\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":9193,"content_sha256":"f1f9e81cfa93b78d99834bffbf3005915f5d23c7cc9f74926d4744028bf19b65"},{"filename":"references/migration-guides.md","content":"# Ultracite Migration Guides\n\nComplete guides for migrating from ESLint, Prettier, and Biome to Ultracite.\n\n**Last Updated**: 2025-11-22\n\n---\n\n## ESLint Migration\n\n### Automatic Migration (Recommended)\n\n```bash\n# Install Ultracite\nbun add -D ultracite\n\n# Run migration tool\nbunx ultracite migrate eslint\n\n# Review changes\ngit diff\n```\n\n**What it does**:\n1. Analyzes your `.eslintrc` configuration\n2. Maps ESLint rules to Biome equivalents\n3. Creates `biome.json` with equivalent rules\n4. Generates migration report\n\n---\n\n### Manual Migration\n\n**1. Analyze Current ESLint Config**\n\n```bash\n# View your current ESLint rules\ncat .eslintrc.json\n```\n\n**2. Find Biome Equivalents**\n\n| ESLint Rule | Biome Equivalent |\n|-------------|------------------|\n| `no-unused-vars` | `noUnusedVariables` |\n| `eqeqeq` | `noDoubleEquals` |\n| `no-console` | `noConsoleLog` |\n| `prefer-const` | `useConst` |\n| `no-debugger` | `noDebugger` |\n| `no-unreachable` | `noUnreachable` |\n| `no-constant-condition` | `noConstantCondition` |\n\n**Full mapping**: https://biomejs.dev/linter/rules/\n\n---\n\n**3. Create `biome.json`**\n\n**From this ESLint config**:\n```json\n{\n \"extends\": [\"eslint:recommended\", \"plugin:react/recommended\"],\n \"rules\": {\n \"no-console\": \"warn\",\n \"prefer-const\": \"error\",\n \"eqeqeq\": \"error\"\n }\n}\n```\n\n**To this Biome config**:\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\", \"ultracite/react\"],\n\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"noConsoleLog\": \"warn\",\n \"noDoubleEquals\": \"error\"\n },\n \"style\": {\n \"useConst\": \"error\"\n }\n }\n }\n}\n```\n\n---\n\n**4. Remove ESLint**\n\n```bash\n# Remove ESLint packages\nbun remove eslint eslint-plugin-react eslint-config-prettier\n\n# Remove config files\nrm .eslintrc.json .eslintignore\n```\n\n---\n\n**5. Update Scripts**\n\n**Before**:\n```json\n{\n \"scripts\": {\n \"lint\": \"eslint . --ext .ts,.tsx\",\n \"lint:fix\": \"eslint . --ext .ts,.tsx --fix\"\n }\n}\n```\n\n**After**:\n```json\n{\n \"scripts\": {\n \"lint\": \"ultracite check\",\n \"lint:fix\": \"ultracite check --write\"\n }\n}\n```\n\n---\n\n### ESLint Plugins Without Biome Equivalents\n\n**Common plugins**:\n- `eslint-plugin-import` → **No equivalent** (some import rules in Biome core)\n- `eslint-plugin-jsx-a11y` → **Partial** (Biome has a11y category)\n- `eslint-plugin-testing-library` → **No equivalent**\n- `eslint-plugin-jest` → **No equivalent**\n\n**Solution**: Run ESLint alongside Ultracite for unsupported plugins:\n\n```json\n{\n \"scripts\": {\n \"lint\": \"ultracite check && eslint . --ext .test.ts --plugin testing-library\"\n }\n}\n```\n\n---\n\n### Migration Checklist\n\n- [ ] Run `ultracite migrate eslint`\n- [ ] Review generated `biome.json`\n- [ ] Test linting: `bunx ultracite check`\n- [ ] Update package.json scripts\n- [ ] Update CI configuration\n- [ ] Update pre-commit hooks\n- [ ] Remove ESLint dependencies\n- [ ] Remove `.eslintrc` and `.eslintignore`\n- [ ] Document any ESLint plugins still needed\n- [ ] Commit changes\n\n---\n\n## Prettier Migration\n\n### Automatic Migration (Recommended)\n\n```bash\n# Install Ultracite\nbun add -D ultracite\n\n# Run migration tool\nbunx ultracite migrate prettier\n\n# Review changes\ngit diff\n```\n\n**What it does**:\n1. Reads your `.prettierrc` configuration\n2. Maps Prettier options to Biome equivalents\n3. Updates `biome.json` formatter section\n4. Generates migration report\n\n---\n\n### Manual Migration\n\n**1. Compare Configurations**\n\n| Prettier Option | Biome Equivalent |\n|-----------------|------------------|\n| `printWidth` | `formatter.lineWidth` |\n| `tabWidth` | `formatter.indentWidth` |\n| `useTabs` | `formatter.indentStyle: \"tab\"` |\n| `semi` | `javascript.formatter.semicolons` |\n| `singleQuote` | `javascript.formatter.quoteStyle` |\n| `trailingComma` | `javascript.formatter.trailingCommas` |\n| `arrowParens` | `javascript.formatter.arrowParentheses` |\n\n---\n\n**2. Convert Configuration**\n\n**From this Prettier config**:\n```json\n{\n \"printWidth\": 100,\n \"tabWidth\": 2,\n \"useTabs\": false,\n \"semi\": true,\n \"singleQuote\": true,\n \"trailingComma\": \"es5\"\n}\n```\n\n**To this Biome config**:\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\"],\n\n \"formatter\": {\n \"enabled\": true,\n \"lineWidth\": 100,\n \"indentWidth\": 2,\n \"indentStyle\": \"space\"\n },\n\n \"javascript\": {\n \"formatter\": {\n \"semicolons\": \"always\",\n \"quoteStyle\": \"single\",\n \"trailingCommas\": \"es5\"\n }\n }\n}\n```\n\n---\n\n**3. Remove Prettier**\n\n```bash\n# Remove Prettier\nbun remove prettier\n\n# Remove config files\nrm .prettierrc .prettierignore\n```\n\n---\n\n**4. Update Scripts**\n\n**Before**:\n```json\n{\n \"scripts\": {\n \"format\": \"prettier --write .\"\n }\n}\n```\n\n**After**:\n```json\n{\n \"scripts\": {\n \"format\": \"ultracite format --write\"\n }\n}\n```\n\n---\n\n### Formatting Differences\n\n**Prettier**:\n```javascript\n// Object spacing\nconst obj = {foo: \"bar\"};\n\n// Arrow function parentheses (default)\nconst fn = x => x + 1;\n```\n\n**Biome**:\n```javascript\n// Object spacing\nconst obj = { foo: \"bar\" };\n\n// Arrow function parentheses (configurable)\nconst fn = (x) => x + 1;\n```\n\n**To match Prettier**:\n```jsonc\n{\n \"javascript\": {\n \"formatter\": {\n \"arrowParentheses\": \"asNeeded\" // Same as Prettier default\n }\n }\n}\n```\n\n---\n\n### Migration Checklist\n\n- [ ] Run `ultracite migrate prettier`\n- [ ] Review generated formatter config\n- [ ] Test formatting: `bunx ultracite format --write .`\n- [ ] Compare output with Prettier (spot check)\n- [ ] Update package.json scripts\n- [ ] Update CI configuration\n- [ ] Update pre-commit hooks\n- [ ] Remove Prettier dependencies\n- [ ] Remove `.prettierrc` and `.prettierignore`\n- [ ] Commit formatted code\n\n---\n\n## Biome Migration\n\n**Note**: Ultracite is built on Biome, so migration is minimal.\n\n### Automatic Migration\n\n```bash\n# Install Ultracite\nbun add -D ultracite\n\n# Ultracite automatically detects biome.json\nbunx ultracite check\n```\n\n---\n\n### Manual Migration\n\n**1. Install Ultracite**\n\n```bash\nbun add -D ultracite\n```\n\n---\n\n**2. Use Ultracite Presets**\n\n**Before** (vanilla Biome):\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n\n \"linter\": {\n \"enabled\": true,\n \"rules\": {\n \"recommended\": true,\n // ... 50+ manual rule configurations\n }\n }\n}\n```\n\n**After** (Ultracite preset):\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\", \"ultracite/react\"],\n\n // Only customize what differs from preset\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"noConsoleLog\": \"off\" // Single override\n }\n }\n }\n}\n```\n\n---\n\n**3. Update Package Name**\n\n**Before**:\n```json\n{\n \"scripts\": {\n \"lint\": \"biome check\",\n \"format\": \"biome format --write\"\n }\n}\n```\n\n**After**:\n```json\n{\n \"scripts\": {\n \"lint\": \"ultracite check\",\n \"format\": \"ultracite format --write\"\n }\n}\n```\n\n---\n\n**4. Remove Biome (Optional)**\n\n```bash\n# Ultracite includes Biome internally\nbun remove @biomejs/biome\n```\n\n---\n\n### Benefits of Migration\n\n| Feature | Vanilla Biome | Ultracite |\n|---------|---------------|-----------|\n| **Configuration** | Manual (~200 rules) | Presets (3-10 lines) |\n| **Framework Support** | Generic | React/Next.js/Vue/Svelte |\n| **Git Hooks** | Manual setup | Auto-detection + setup |\n| **AI Editor Rules** | Manual | Auto-generation |\n| **Monorepo Support** | Basic | Turborepo-optimized |\n\n---\n\n### Migration Checklist\n\n- [ ] Install Ultracite: `bun add -D ultracite`\n- [ ] Replace rules with presets in `biome.json`\n- [ ] Update package.json scripts\n- [ ] Test linting: `bunx ultracite check`\n- [ ] Test formatting: `bunx ultracite format --write .`\n- [ ] Remove Biome dependency (optional)\n- [ ] Commit changes\n\n---\n\n## Post-Migration\n\n### Verify Everything Works\n\n```bash\n# 1. Lint entire codebase\nbunx ultracite check\n\n# 2. Format entire codebase\nbunx ultracite format --write .\n\n# 3. Run tests\nbun test\n\n# 4. Commit formatted code\ngit add .\ngit commit -m \"chore: migrate to Ultracite\"\n```\n\n---\n\n### Update CI\n\n**GitHub Actions**:\n```yaml\nname: Lint\n\non: [push, pull_request]\n\njobs:\n lint:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: oven-sh/setup-bun@v1\n\n - name: Install dependencies\n run: bun install\n\n - name: Run Ultracite\n run: bun ultracite ci\n```\n\n---\n\n### Update Pre-Commit Hooks\n\n**Husky**:\n```bash\n# .husky/pre-commit\n#!/usr/bin/env sh\n. \"$(dirname -- \"$0\")/_/husky.sh\"\n\nultracite check --staged --write\n```\n\n**Lefthook**:\n```yaml\n# lefthook.yml\npre-commit:\n commands:\n ultracite:\n glob: \"*.{js,jsx,ts,tsx,json}\"\n run: ultracite check --write --no-errors-on-unmatched {staged_files}\n```\n\n---\n\n### Update Editor Settings\n\n**VS Code** (`.vscode/settings.json`):\n\n**Before** (ESLint/Prettier):\n```json\n{\n \"editor.defaultFormatter\": \"esbenp.prettier-vscode\",\n \"editor.codeActionsOnSave\": {\n \"source.fixAll.eslint\": true\n }\n}\n```\n\n**After** (Ultracite/Biome):\n```json\n{\n \"editor.defaultFormatter\": \"biomejs.biome\",\n \"editor.codeActionsOnSave\": {\n \"quickfix.biome\": \"explicit\"\n }\n}\n```\n\n---\n\n## Troubleshooting\n\n### Rules Not Equivalent\n\n**Issue**: Biome doesn't have exact equivalent for an ESLint rule\n\n**Solution**: Document missing rules and keep ESLint for those specific checks:\n\n```json\n{\n \"scripts\": {\n \"lint\": \"ultracite check && eslint . --plugin testing-library --ext .test.ts\"\n }\n}\n```\n\n---\n\n### Formatting Differences\n\n**Issue**: Biome formats code differently than Prettier\n\n**Solution 1**: Adjust Biome config to match Prettier:\n```jsonc\n{\n \"javascript\": {\n \"formatter\": {\n \"arrowParentheses\": \"asNeeded\", // Match Prettier\n \"quoteStyle\": \"single\"\n }\n }\n}\n```\n\n**Solution 2**: Accept Biome's style (often more consistent)\n\n---\n\n### Migration Breaks CI\n\n**Issue**: CI fails after migration due to formatting changes\n\n**Solution**: Commit formatted code first:\n```bash\nbunx ultracite format --write .\ngit add .\ngit commit -m \"chore: format code with Ultracite\"\n```\n\n---\n\n**See also:**\n- `configuration-guide.md` for Ultracite setup\n- `troubleshooting.md` for common issues\n- `limitations-and-workarounds.md` for feature gaps\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":10193,"content_sha256":"bd4517098b6649b5ff3091d3587f7f06e69f98fbc186b9d50a7a9f766da505e1"},{"filename":"references/monorepo-configuration.md","content":"# Ultracite Monorepo Configuration\n\nComplete guide for configuring Ultracite in monorepos with Turborepo, Nx, and pnpm workspaces.\n\n**Last Updated**: 2025-11-22\n\n---\n\n## Overview\n\nUltracite supports monorepos with:\n- **Shared configurations** across packages\n- **Package-specific overrides** for custom rules\n- **Performance optimizations** for large codebases\n- **Workspace-aware linting** (Turborepo, Nx, pnpm)\n\n**Benefits**:\n- Single source of truth for linting rules\n- Per-package customization when needed\n- Faster linting with caching (Turborepo)\n- Consistent code quality across all packages\n\n---\n\n## Configuration Strategies\n\n### Strategy 1: Single Root Config (Simplest)\n\n**Best for**: Small monorepos (\u003c 10 packages) with similar requirements\n\n**Structure**:\n```\nmonorepo/\n├── biome.json # ← Single config for entire repo\n├── apps/\n│ ├── web/\n│ └── mobile/\n└── packages/\n ├── ui/\n └── utils/\n```\n\n**Root `biome.json`**:\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\", \"ultracite/react\"],\n\n \"files\": {\n \"ignore\": [\n \"**/dist\",\n \"**/build\",\n \"**/.next\",\n \"**/node_modules\"\n ]\n }\n}\n```\n\n**Usage**:\n```bash\n# Lint entire monorepo\nultracite check\n\n# Lint specific package\nultracite check apps/web\n```\n\n---\n\n### Strategy 2: Shared Config + Overrides (Recommended)\n\n**Best for**: Medium monorepos (10-50 packages) with some variation\n\n**Structure**:\n```\nmonorepo/\n├── biome.json # ← Shared base config\n├── apps/\n│ ├── web/\n│ │ └── biome.json # ← Next.js-specific overrides\n│ └── mobile/\n│ └── biome.json # ← React Native overrides\n└── packages/\n ├── ui/\n │ └── biome.json # ← React component overrides\n └── utils/\n └── biome.json # ← Utility library overrides\n```\n\n**Root `biome.json`** (shared):\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\"],\n\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"noConsoleLog\": \"error\",\n \"noDebugger\": \"error\"\n }\n }\n }\n}\n```\n\n**`apps/web/biome.json`** (Next.js):\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"../../biome.json\", \"ultracite/nextjs\"],\n\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"noConsoleLog\": \"off\" // Allow console.log in Next.js app\n }\n }\n }\n}\n```\n\n**`packages/ui/biome.json`** (React library):\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"../../biome.json\", \"ultracite/react\"],\n\n \"linter\": {\n \"rules\": {\n \"a11y\": {\n \"all\": \"error\" // Strict accessibility for UI library\n }\n }\n }\n}\n```\n\n---\n\n### Strategy 3: Per-Package Configs (Flexible)\n\n**Best for**: Large monorepos (50+ packages) with diverse requirements\n\n**Structure**:\n```\nmonorepo/\n├── .ultracite/\n│ ├── base.json # ← Shared base\n│ ├── react.json # ← React apps/packages\n│ └── node.json # ← Node.js packages\n├── apps/\n│ └── web/\n│ └── biome.json # extends .ultracite/react.json\n└── packages/\n └── api/\n └── biome.json # extends .ultracite/node.json\n```\n\n**`.ultracite/base.json`**:\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\"],\n\n \"formatter\": {\n \"indentWidth\": 2,\n \"lineWidth\": 100\n }\n}\n```\n\n**`.ultracite/react.json`**:\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"./base.json\", \"ultracite/react\"]\n}\n```\n\n**`apps/web/biome.json`**:\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"../../.ultracite/react.json\", \"ultracite/nextjs\"]\n}\n```\n\n---\n\n## Turborepo Integration\n\n### Setup\n\n**Install**:\n```bash\nbun add -D ultracite\n```\n\n**`turbo.json`**:\n```json\n{\n \"tasks\": {\n \"lint\": {\n \"cache\": true,\n \"inputs\": [\n \"**/*.ts\",\n \"**/*.tsx\",\n \"**/*.js\",\n \"**/*.jsx\",\n \"biome.json\"\n ],\n \"outputs\": []\n },\n \"lint:fix\": {\n \"cache\": false,\n \"dependsOn\": [\"^lint:fix\"]\n }\n }\n}\n```\n\n---\n\n### Package Scripts\n\n**Root `package.json`**:\n```json\n{\n \"scripts\": {\n \"lint\": \"turbo run lint\",\n \"lint:fix\": \"turbo run lint:fix\"\n }\n}\n```\n\n**`apps/web/package.json`**:\n```json\n{\n \"scripts\": {\n \"lint\": \"ultracite check\",\n \"lint:fix\": \"ultracite check --write\"\n }\n}\n```\n\n**`packages/ui/package.json`**:\n```json\n{\n \"scripts\": {\n \"lint\": \"ultracite check\",\n \"lint:fix\": \"ultracite check --write\"\n }\n}\n```\n\n---\n\n### Running Lints\n\n```bash\n# Lint all packages (parallel, cached)\nturbo run lint\n\n# Lint all packages and fix\nturbo run lint:fix\n\n# Lint specific package\nturbo run lint --filter=web\n\n# Lint changed packages only\nturbo run lint --filter=[HEAD^1]\n```\n\n---\n\n### Cache Benefits\n\n**First run** (no cache):\n```\nTasks: 5 successful, 5 total\nCached: 0 cached, 5 total\nTime: 12.3s\n```\n\n**Second run** (with cache):\n```\nTasks: 5 successful, 5 total\nCached: 5 cached, 5 total\nTime: 0.1s ← 99% faster!\n```\n\n---\n\n## Nx Integration\n\n### Setup\n\n**Install**:\n```bash\nbun add -D ultracite\n```\n\n**`nx.json`**:\n```json\n{\n \"targetDefaults\": {\n \"lint\": {\n \"cache\": true,\n \"inputs\": [\n \"{projectRoot}/**/*.ts\",\n \"{projectRoot}/**/*.tsx\",\n \"{projectRoot}/biome.json\",\n \"{workspaceRoot}/biome.json\"\n ]\n }\n }\n}\n```\n\n---\n\n### Project Configuration\n\n**`apps/web/project.json`**:\n```json\n{\n \"name\": \"web\",\n \"targets\": {\n \"lint\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"command\": \"ultracite check\",\n \"cwd\": \"apps/web\"\n }\n },\n \"lint:fix\": {\n \"executor\": \"nx:run-commands\",\n \"options\": {\n \"command\": \"ultracite check --write\",\n \"cwd\": \"apps/web\"\n }\n }\n }\n}\n```\n\n---\n\n### Running Lints\n\n```bash\n# Lint all projects\nnx run-many --target=lint --all\n\n# Lint specific project\nnx run web:lint\n\n# Lint affected projects only\nnx affected --target=lint\n\n# Lint and fix\nnx run web:lint:fix\n```\n\n---\n\n## pnpm Workspaces\n\n### Setup\n\n**`pnpm-workspace.yaml`**:\n```yaml\npackages:\n - 'apps/*'\n - 'packages/*'\n```\n\n**Root `package.json`**:\n```json\n{\n \"scripts\": {\n \"lint\": \"pnpm --recursive --parallel run lint\",\n \"lint:fix\": \"pnpm --recursive run lint:fix\"\n },\n \"devDependencies\": {\n \"ultracite\": \"^0.9.0\"\n }\n}\n```\n\n---\n\n### Package Scripts\n\n**`apps/web/package.json`**:\n```json\n{\n \"scripts\": {\n \"lint\": \"ultracite check\",\n \"lint:fix\": \"ultracite check --write\"\n }\n}\n```\n\n---\n\n### Running Lints\n\n```bash\n# Lint all packages (parallel)\npnpm lint\n\n# Lint specific package\npnpm --filter web lint\n\n# Lint and fix all packages\npnpm lint:fix\n\n# Lint changed packages only\npnpm --filter \"...[HEAD^1]\" lint\n```\n\n---\n\n## Package-Specific Overrides\n\n### Example: Strict Library, Relaxed App\n\n**`packages/ui/biome.json`** (strict):\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"../../biome.json\", \"ultracite/react\"],\n\n \"linter\": {\n \"rules\": {\n \"a11y\": {\n \"all\": \"error\" // Strict accessibility\n },\n \"suspicious\": {\n \"noConsoleLog\": \"error\", // No console.log\n \"noDebugger\": \"error\" // No debugger\n },\n \"complexity\": {\n \"noExcessiveCognitiveComplexity\": {\n \"level\": \"error\",\n \"options\": { \"maxComplexity\": 10 } // Lower complexity limit\n }\n }\n }\n }\n}\n```\n\n**`apps/web/biome.json`** (relaxed):\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"../../biome.json\", \"ultracite/nextjs\"],\n\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"noConsoleLog\": \"off\" // Allow console.log in app\n },\n \"complexity\": {\n \"noExcessiveCognitiveComplexity\": \"off\" // No complexity limit\n }\n }\n }\n}\n```\n\n---\n\n## Performance Optimizations\n\n### 1. Use Workspace-Aware Commands\n\n**Turborepo**:\n```bash\n# ✓ Only lints changed packages\nturbo run lint --filter=[HEAD^1]\n\n# ✗ Lints all packages\nturbo run lint\n```\n\n**Nx**:\n```bash\n# ✓ Only lints affected projects\nnx affected --target=lint\n\n# ✗ Lints all projects\nnx run-many --target=lint --all\n```\n\n---\n\n### 2. Leverage Caching\n\n**Turborepo** (automatic):\n```json\n{\n \"tasks\": {\n \"lint\": {\n \"cache\": true // ← Enables caching\n }\n }\n}\n```\n\n**Nx** (automatic):\n```json\n{\n \"targetDefaults\": {\n \"lint\": {\n \"cache\": true // ← Enables caching\n }\n }\n}\n```\n\n---\n\n### 3. Parallel Execution\n\n**Turborepo** (default):\n```bash\nturbo run lint # Runs in parallel automatically\n```\n\n**pnpm**:\n```bash\npnpm --recursive --parallel run lint\n```\n\n**Nx** (configurable):\n```bash\nnx run-many --target=lint --all --parallel=3\n```\n\n---\n\n### 4. Incremental Linting\n\n**Git hook integration** (only lint staged files):\n\n```bash\n# .husky/pre-commit\n#!/usr/bin/env sh\n. \"$(dirname -- \"$0\")/_/husky.sh\"\n\n# Only lint staged files\nultracite check --staged --write\n```\n\n---\n\n## Troubleshooting\n\n### Config Not Found\n\n**Error**:\n```\nConfiguration file not found\n```\n\n**Fix**: Ensure `biome.json` exists in package root or parent directory:\n\n```bash\n# Check config path\nultracite check --verbose\n\n# Specify config explicitly\nultracite check --config-path=../../biome.json\n```\n\n---\n\n### Rules Overridden Unexpectedly\n\n**Issue**: Child config doesn't override parent rules\n\n**Fix**: Use explicit rule values:\n\n```jsonc\n{\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"noConsoleLog\": \"off\" // ← Must be explicit, not inherited\n }\n }\n }\n}\n```\n\n---\n\n### Slow Linting in Large Monorepo\n\n**Solutions**:\n\n1. **Enable caching** (Turborepo/Nx)\n2. **Lint changed packages only**:\n ```bash\n turbo run lint --filter=[HEAD^1]\n ```\n3. **Use parallel execution**:\n ```bash\n pnpm --recursive --parallel run lint\n ```\n4. **Exclude unnecessary files**:\n ```jsonc\n {\n \"files\": {\n \"ignore\": [\n \"**/dist\",\n \"**/.next\",\n \"**/coverage\",\n \"**/*.generated.ts\"\n ]\n }\n }\n ```\n\n---\n\n## Best Practices\n\n1. **Use root config for shared rules** (DRY principle)\n2. **Override only when necessary** (avoid config duplication)\n3. **Leverage workspace caching** (Turborepo/Nx)\n4. **Lint changed packages only** in CI\n5. **Run lints in parallel** for speed\n6. **Use `--filter` flags** to target specific packages\n7. **Document config strategy** in root README\n8. **Keep configs close to code** (per-package `biome.json`)\n\n---\n\n**See also:**\n- `configuration-guide.md` for Ultracite configuration details\n- `git-hooks-setup.md` for pre-commit integration\n- `troubleshooting.md` for common issues\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":10951,"content_sha256":"5a78d5ad5d7cda79c265288646061a25ee584d09561cc2235303300c778c9950"},{"filename":"references/provider-biome.md","content":"---\ntitle: Biome Provider Reference\ndescription: Rust-based linting and formatting provider for modern TypeScript development\nprovider: Biome\nskill: ultracite\ncategory: reference\nspeed: Fastest (10-100x faster than ESLint)\nbestFor: New projects, TypeScript-first development, performance-critical builds\nsummary: Rust-based linting and formatting provider\n---\n\n# Biome Provider Reference\n\n**Provider**: Biome (Default)\n**Speed**: Fastest (10-100x faster than ESLint)\n**Best for**: New projects, TypeScript-first development, performance-critical builds\n\n## Overview\n\nBiome is the default Ultracite provider, offering blazing-fast Rust-based linting and formatting. It provides zero-configuration setup with 200+ preconfigured rules optimized for modern TypeScript development.\n\n## Installation\n\n```bash\n# Install with Biome provider (default)\nbun x ultracite init --linter biome\n\n# Or without explicit flag (defaults to Biome)\nbun x ultracite init\n```\n\n## Configuration File\n\nBiome uses `biome.jsonc` for configuration:\n\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\n \"ultracite/biome/core\", // v7 path (required)\n \"ultracite/biome/react\" // Framework preset\n ],\n \"files\": {\n \"ignore\": [\"dist\", \"node_modules\", \".next\", \"build\"]\n },\n \"formatter\": {\n \"enabled\": true,\n \"indentStyle\": \"space\",\n \"indentWidth\": 2,\n \"lineWidth\": 100\n },\n \"linter\": {\n \"enabled\": true\n }\n}\n```\n\n## V7 Preset Paths (Breaking Change)\n\n**v6 paths (old - deprecated)**:\n```jsonc\n{\n \"extends\": [\"ultracite/core\", \"ultracite/react\"]\n}\n```\n\n**v7 paths (new - required)**:\n```jsonc\n{\n \"extends\": [\"ultracite/biome/core\", \"ultracite/biome/react\"]\n}\n```\n\n**Migration**: Add `/biome/` segment to all preset paths.\n\n## Available Presets\n\n### Core Preset\n- `ultracite/biome/core` - Base rules (200+ rules)\n - TypeScript strict mode\n - Null/undefined safety\n - Import organization\n - Security rules\n - Performance optimizations\n\n### Framework Presets\n- `ultracite/biome/react` - React + JSX rules\n- `ultracite/biome/next` - Next.js optimization\n- `ultracite/biome/vue` - Vue 3 SFC support\n- `ultracite/biome/svelte` - Svelte components\n- `ultracite/biome/solid` - Solid.js patterns\n- `ultracite/biome/qwik` - Qwik framework\n- `ultracite/biome/angular` - Angular components\n- `ultracite/biome/remix` - Remix framework\n- `ultracite/biome/astro` - Astro framework\n\n## Rule Customization\n\nOverride or extend rules in `biome.jsonc`:\n\n```jsonc\n{\n \"extends\": [\"ultracite/biome/core\", \"ultracite/biome/react\"],\n \"linter\": {\n \"rules\": {\n \"style\": {\n \"useConst\": \"error\",\n \"noVar\": \"error\"\n },\n \"correctness\": {\n \"noUnusedVariables\": \"warn\" // Downgrade to warning\n },\n \"suspicious\": {\n \"noExplicitAny\": \"off\" // Disable rule\n }\n }\n }\n}\n```\n\n## Performance Optimization\n\n### For Large Codebases\n\n```jsonc\n{\n \"extends\": [\"ultracite/biome/core\"],\n \"files\": {\n \"maxSize\": 1000000, // 1MB file size limit\n \"ignore\": [\n \"**/node_modules/**\",\n \"**/dist/**\",\n \"**/.next/**\",\n \"**/build/**\",\n \"**/*.generated.ts\" // Ignore generated files\n ]\n }\n}\n```\n\n### Parallel Processing\n\nBiome automatically uses all CPU cores. No configuration needed.\n\n## Editor Integration\n\n### VS Code\n\nInstall the Biome extension:\n\n```bash\ncode --install-extension biomejs.biome\n```\n\nAdd to `.vscode/settings.json`:\n\n```json\n{\n \"[javascript]\": {\n \"editor.defaultFormatter\": \"biomejs.biome\",\n \"editor.formatOnSave\": true\n },\n \"[typescript]\": {\n \"editor.defaultFormatter\": \"biomejs.biome\",\n \"editor.formatOnSave\": true\n },\n \"[javascriptreact]\": {\n \"editor.defaultFormatter\": \"biomejs.biome\",\n \"editor.formatOnSave\": true\n },\n \"[typescriptreact]\": {\n \"editor.defaultFormatter\": \"biomejs.biome\",\n \"editor.formatOnSave\": true\n }\n}\n```\n\n## CLI Commands\n\n```bash\n# Check files (linting only)\nnpx ultracite check .\n\n# Format files\nnpx ultracite format .\n\n# Fix issues automatically\nnpx ultracite fix .\n\n# Check with verbose output\nnpx ultracite check . --verbose\n\n# Dry run (no changes)\nnpx ultracite fix . --dry-run\n\n# Check specific files\nnpx ultracite check src/**/*.ts\n```\n\n## Diagnostics\n\nRun diagnostics to validate configuration:\n\n```bash\nnpx ultracite doctor\n```\n\nChecks:\n- Configuration file validity\n- Preset path correctness (v6 vs v7)\n- File permissions\n- Editor integration\n- Git hooks status\n\n## Limitations\n\n### CSS Linting\n- Basic CSS support only\n- For advanced CSS/SCSS linting, use ESLint provider or add Stylelint separately\n\n### ESLint Plugin Ecosystem\n- No direct ESLint plugin support\n- Most common patterns covered by Biome's built-in rules\n- For specific ESLint plugins, consider ESLint provider\n\n### Framework Support\n- Angular/Ember support is basic\n- Vue/Svelte support improving with each release\n\n## Troubleshooting\n\n### \"Preset not found\" Error\n\n**Problem**: `ultracite/core` not found\n\n**Solution**: Update to v7 preset paths:\n```jsonc\n{\n \"extends\": [\"ultracite/biome/core\"] // Add /biome/ segment\n}\n```\n\n### Format on Save Not Working\n\n**Check**:\n1. Biome extension installed in VS Code\n2. `editor.formatOnSave: true` in settings\n3. `biomejs.biome` set as default formatter\n\n**Fix**:\n```bash\n# Reinstall Biome extension\ncode --install-extension biomejs.biome --force\n```\n\n### Slow Performance\n\n**Solutions**:\n1. Add `files.ignore` patterns for large directories\n2. Set `files.maxSize` limit\n3. Exclude generated files\n\n## Resources\n\n- [Biome Official Docs](https://biomejs.dev/)\n- [Ultracite Biome Docs](https://www.ultracite.ai/providers/biome)\n- [Rule Reference](https://biomejs.dev/linter/rules/)\n- [Migration Guide](https://biomejs.dev/guides/migrate-eslint/)\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":5744,"content_sha256":"a8da3c51992056d9788702185ff0fb75fb3a8cc374b73f70e829cbc339e4eb68"},{"filename":"references/provider-eslint.md","content":"---\ntitle: ESLint Provider Reference\ndescription: ESLint + Prettier + Stylelint provider for maximum compatibility\nprovider: ESLint\nspeed: Moderate (JavaScript-based)\nbestFor: Maximum compatibility, existing ESLint plugin ecosystem, advanced CSS/SCSS linting\n---\n\n# ESLint Provider Reference\n\n**Provider**: ESLint + Prettier + Stylelint\n**Speed**: Moderate (JavaScript-based)\n**Best for**: Maximum compatibility, existing ESLint plugin ecosystem, advanced CSS/SCSS linting\n\n## Overview\n\nThe ESLint provider integrates ESLint, Prettier, and Stylelint into Ultracite's unified workflow. This provider is ideal for projects that require specific ESLint plugins or advanced CSS linting capabilities.\n\n## Installation\n\n```bash\n# Install with ESLint provider\nbun x ultracite init --linter eslint\n\n# Installs: eslint, prettier, stylelint, and necessary plugins\n```\n\n## Configuration Files\n\nESLint provider uses three configuration files:\n\n### `.eslintrc.js` (or `.eslintrc.json`)\n\n```javascript\nmodule.exports = {\n extends: [\n 'ultracite/eslint/core',\n 'ultracite/eslint/react', // Framework preset\n 'ultracite/eslint/prettier' // Prettier integration\n ],\n rules: {\n // Custom rule overrides\n }\n};\n```\n\n### `.prettierrc.json`\n\n```json\n{\n \"semi\": true,\n \"singleQuote\": true,\n \"tabWidth\": 2,\n \"trailingComma\": \"es5\",\n \"printWidth\": 100\n}\n```\n\n### `.stylelintrc.json` (if using CSS/SCSS)\n\n```json\n{\n \"extends\": [\"ultracite/stylelint/core\"],\n \"rules\": {\n // CSS-specific rules\n }\n}\n```\n\n## Available Presets\n\n### Core Preset\n- `ultracite/eslint/core` - Base ESLint rules\n - TypeScript support\n - Import/export rules\n - Code quality rules\n\n### Framework Presets\n- `ultracite/eslint/react` - React + JSX\n- `ultracite/eslint/next` - Next.js\n- `ultracite/eslint/vue` - Vue 3\n- `ultracite/eslint/solid` - Solid.js\n\n### Integration Presets\n- `ultracite/eslint/prettier` - Prettier integration\n- `ultracite/eslint/jest` - Jest testing\n- `ultracite/eslint/vitest` - Vitest testing\n\n### Stylelint Presets\n- `ultracite/stylelint/core` - Base CSS rules\n- `ultracite/stylelint/scss` - SCSS support\n- `ultracite/stylelint/css-modules` - CSS Modules\n\n## Adding ESLint Plugins\n\nThe ESLint provider allows you to use any ESLint plugin:\n\n```javascript\n// .eslintrc.js\nmodule.exports = {\n extends: ['ultracite/eslint/core'],\n plugins: [\n 'security', // eslint-plugin-security\n 'sonarjs', // eslint-plugin-sonarjs\n 'jsx-a11y' // eslint-plugin-jsx-a11y\n ],\n rules: {\n 'security/detect-object-injection': 'warn',\n 'sonarjs/cognitive-complexity': ['error', 15]\n }\n};\n```\n\nInstall additional plugins:\n\n```bash\nbun add -D eslint-plugin-security eslint-plugin-sonarjs eslint-plugin-jsx-a11y\n```\n\n## Editor Integration\n\n### VS Code\n\nInstall extensions:\n\n```bash\ncode --install-extension dbaeumer.vscode-eslint\ncode --install-extension esbenp.prettier-vscode\ncode --install-extension stylelint.vscode-stylelint\n```\n\nAdd to `.vscode/settings.json`:\n\n```json\n{\n \"editor.formatOnSave\": true,\n \"editor.defaultFormatter\": \"esbenp.prettier-vscode\",\n \"editor.codeActionsOnSave\": {\n \"source.fixAll.eslint\": true,\n \"source.fixAll.stylelint\": true\n },\n \"eslint.validate\": [\n \"javascript\",\n \"javascriptreact\",\n \"typescript\",\n \"typescriptreact\"\n ]\n}\n```\n\n## CLI Commands\n\n```bash\n# Lint with ESLint\nnpx ultracite lint .\n\n# Format with Prettier\nnpx ultracite format .\n\n# Fix ESLint issues\nnpx ultracite fix .\n\n# Lint CSS with Stylelint\nnpx stylelint \"**/*.css\"\n\n# Fix Stylelint issues\nnpx stylelint \"**/*.css\" --fix\n```\n\n## Performance Optimization\n\n### Enable Caching\n\n```javascript\n// .eslintrc.js\nmodule.exports = {\n extends: ['ultracite/eslint/core'],\n cache: true,\n cacheLocation: '.eslintcache'\n};\n```\n\n### Parallel Linting\n\nUltracite automatically runs ESLint with `--max-workers` based on CPU cores.\n\n### Ignore Patterns\n\n```javascript\n// .eslintrc.js\nmodule.exports = {\n extends: ['ultracite/eslint/core'],\n ignorePatterns: [\n 'dist',\n 'build',\n 'node_modules',\n '*.generated.ts'\n ]\n};\n```\n\n## Advanced CSS Linting\n\nThe ESLint provider includes Stylelint for comprehensive CSS/SCSS linting:\n\n```json\n// .stylelintrc.json\n{\n \"extends\": [\"ultracite/stylelint/scss\"],\n \"rules\": {\n \"property-no-unknown\": true,\n \"selector-class-pattern\": \"^[a-z][a-zA-Z0-9]+$\",\n \"color-no-invalid-hex\": true,\n \"declaration-block-no-duplicate-properties\": true,\n \"order/properties-alphabetical-order\": true\n }\n}\n```\n\n## Diagnostics\n\n```bash\n# Check ESLint configuration\nnpx eslint --debug src/**/*.ts\n\n# Check Prettier configuration\nnpx prettier --check .\n\n# Check Stylelint configuration\nnpx stylelint \"**/*.css\" --formatter verbose\n```\n\n## Advantages Over Biome\n\n### ESLint Plugin Ecosystem\n- Access to 1000+ ESLint plugins\n- Security plugins (e.g., `eslint-plugin-security`)\n- Framework-specific plugins (e.g., `eslint-plugin-react-hooks`)\n- Custom company/team plugins\n\n### Advanced CSS Linting\n- Property ordering enforcement\n- BEM methodology validation\n- SCSS/Less/Stylus support\n- CSS-in-JS linting\n\n### Mature Ecosystem\n- Extensive documentation\n- Large community support\n- Well-established best practices\n\n## Disadvantages vs Biome\n\n### Performance\n- 10-100x slower than Biome (JavaScript vs Rust)\n- Requires separate tools (ESLint + Prettier + Stylelint)\n\n### Configuration Complexity\n- More configuration files to manage\n- Potential conflicts between tools\n- Requires plugin management\n\n## Migration from ESLint to Ultracite ESLint Provider\n\nIf you have existing ESLint configuration:\n\n```bash\n# Ultracite will detect and merge existing config\nbun x ultracite init --linter eslint --migrate eslint\n```\n\nSteps:\n1. Backs up existing `.eslintrc.*` files\n2. Merges custom rules into Ultracite presets\n3. Adds Prettier integration\n4. Optionally adds Stylelint for CSS\n\n## Troubleshooting\n\n### Prettier vs ESLint Conflicts\n\n**Problem**: ESLint reports formatting errors that Prettier should handle\n\n**Solution**: Ensure `ultracite/eslint/prettier` preset is loaded last:\n\n```javascript\nmodule.exports = {\n extends: [\n 'ultracite/eslint/core',\n 'ultracite/eslint/react',\n 'ultracite/eslint/prettier' // MUST be last\n ]\n};\n```\n\n### Stylelint Not Running\n\n**Problem**: CSS files not being linted\n\n**Solution**: Add glob pattern:\n\n```bash\nnpx stylelint \"**/*.{css,scss,sass}\"\n```\n\n### Slow Linting Performance\n\n**Solutions**:\n1. Enable ESLint cache: `cache: true`\n2. Reduce `ignorePatterns` scope\n3. Consider switching to Biome provider for speed\n\n## Resources\n\n- [ESLint Official Docs](https://eslint.org/)\n- [Prettier Official Docs](https://prettier.io/)\n- [Stylelint Official Docs](https://stylelint.io/)\n- [Ultracite ESLint Docs](https://www.ultracite.ai/providers/eslint)\n- [ESLint Plugin Registry](https://www.npmjs.com/search?q=keywords:eslint-plugin)\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":6843,"content_sha256":"6d7bf9f20f8a6e35eada8b972666db453e48c3532a1c59cf5905c813a48ea76f"},{"filename":"references/provider-oxlint.md","content":"---\ntitle: Oxlint Provider Reference\ndescription: Oxlint + Oxfmt provider for type-aware linting and maximum performance\nprovider: Oxlint\nspeed: Fastest\nbestFor: Large TypeScript codebases, type-safety-critical projects, maximum performance\n---\n\n# Oxlint Provider Reference\n\n**Provider**: Oxlint + Oxfmt\n**Speed**: Fastest linting (even faster than Biome for linting)\n**Best for**: Large TypeScript codebases, type-safety-critical projects, maximum performance\n\n## Overview\n\nOxlint is the newest Ultracite provider, offering ultra-fast Rust-based linting with **type-aware** capabilities. It uses TypeScript's type system to catch errors that traditional linters miss. Combined with Oxfmt for formatting, this provider delivers the fastest linting experience available.\n\n## Installation\n\n```bash\n# Install with Oxlint provider\nbun x ultracite init --linter oxlint\n\n# Installs: oxlint, oxfmt, and TypeScript integration\n```\n\n## Configuration File\n\nOxlint uses `oxlintrc.json` for configuration:\n\n```json\n{\n \"extends\": [\n \"ultracite/oxlint/core\",\n \"ultracite/oxlint/react\"\n ],\n \"rules\": {\n \"typescript\": \"error\",\n \"react\": \"error\"\n },\n \"typeAware\": true,\n \"tsconfig\": \"./tsconfig.json\"\n}\n```\n\n## Type-Aware Linting\n\nOxlint's killer feature is **type-aware linting** using TypeScript's type system:\n\n### Enabled by Default\n\n```json\n{\n \"extends\": [\"ultracite/oxlint/core\"],\n \"typeAware\": true,\n \"tsconfig\": \"./tsconfig.json\"\n}\n```\n\n### What Type-Aware Linting Catches\n\n#### Example 1: Unnecessary null checks\n\n```typescript\nfunction greet(name: string) {\n // Oxlint detects: 'name' is always defined (type is 'string', not 'string | undefined')\n if (name !== null) { // ❌ Unnecessary check\n console.log(`Hello, ${name}`);\n }\n}\n```\n\n#### Example 2: Type mismatches\n\n```typescript\ninterface User {\n id: number;\n name: string;\n}\n\nfunction getUserName(user: User) {\n // Oxlint detects: 'user.age' doesn't exist on type 'User'\n return user.age; // ❌ Type error\n}\n```\n\n#### Example 3: Promise handling\n\n```typescript\nasync function fetchData(): Promise\u003cstring> {\n return \"data\";\n}\n\n// Oxlint detects: Missing 'await' for Promise\nconst data = fetchData(); // ❌ Returns Promise\u003cstring>, not string\nconsole.log(data.toUpperCase()); // Runtime error\n```\n\n## Available Presets\n\n### Core Preset\n- `ultracite/oxlint/core` - Base rules with type-awareness\n - TypeScript type checking\n - Null/undefined safety (via types)\n - Promise handling\n - Import organization\n\n### Framework Presets\n- `ultracite/oxlint/react` - React + JSX with type-aware hooks\n- `ultracite/oxlint/next` - Next.js optimization\n- `ultracite/oxlint/vue` - Vue 3 with TypeScript\n- `ultracite/oxlint/solid` - Solid.js patterns\n\n## Performance Characteristics\n\n### Linting Speed Comparison\n\n**Benchmark**: 10,000 TypeScript files\n- **Oxlint**: ~2 seconds (fastest)\n- **Biome**: ~5 seconds\n- **ESLint**: ~200 seconds\n\n### Type-Aware Performance\n\nType-aware linting is slightly slower than regular linting, but still faster than ESLint:\n\n- **Oxlint (type-aware)**: ~5 seconds\n- **ESLint (type-aware)**: ~300 seconds\n\n## Editor Integration\n\n### VS Code\n\nInstall the Oxlint extension:\n\n```bash\ncode --install-extension oxlint.vscode-oxlint\n```\n\nAdd to `.vscode/settings.json`:\n\n```json\n{\n \"[typescript]\": {\n \"editor.defaultFormatter\": \"oxlint.vscode-oxlint\",\n \"editor.formatOnSave\": true\n },\n \"[typescriptreact]\": {\n \"editor.defaultFormatter\": \"oxlint.vscode-oxlint\",\n \"editor.formatOnSave\": true\n },\n \"oxlint.typeAware\": true,\n \"oxlint.tsconfig\": \"./tsconfig.json\"\n}\n```\n\n## CLI Commands\n\n```bash\n# Lint with type-awareness\nnpx ultracite check .\n\n# Lint without type-awareness (faster)\nnpx ultracite check . --no-type-aware\n\n# Format with Oxfmt\nnpx ultracite format .\n\n# Fix issues automatically\nnpx ultracite fix .\n\n# Specific TypeScript project\nnpx ultracite check . --tsconfig ./tsconfig.app.json\n```\n\n## Type-Aware Configuration\n\n### Multiple TypeScript Configs\n\nFor monorepos or projects with multiple `tsconfig.json` files:\n\n```json\n{\n \"extends\": [\"ultracite/oxlint/core\"],\n \"typeAware\": true,\n \"projects\": [\n \"./tsconfig.json\",\n \"./packages/*/tsconfig.json\"\n ]\n}\n```\n\n### Disabling Type-Aware for Specific Files\n\n```json\n{\n \"extends\": [\"ultracite/oxlint/core\"],\n \"typeAware\": true,\n \"tsconfig\": \"./tsconfig.json\",\n \"overrides\": [\n {\n \"files\": [\"**/*.generated.ts\"],\n \"typeAware\": false\n }\n ]\n}\n```\n\n## Rule Customization\n\nOverride or extend rules:\n\n```json\n{\n \"extends\": [\"ultracite/oxlint/core\", \"ultracite/oxlint/react\"],\n \"rules\": {\n \"typescript/no-explicit-any\": \"error\",\n \"typescript/no-unused-vars\": \"warn\",\n \"react/no-unstable-nested-components\": \"error\"\n }\n}\n```\n\n## Performance Optimization\n\n### Incremental Type Checking\n\nOxlint caches type information for faster subsequent runs:\n\n```json\n{\n \"typeAware\": true,\n \"incremental\": true,\n \"tsBuildInfoFile\": \".oxlint-cache\"\n}\n```\n\n### Parallel Processing\n\nOxlint automatically uses all CPU cores. For monorepos:\n\n```json\n{\n \"parallel\": true,\n \"maxWorkers\": 8 // Or auto-detect\n}\n```\n\n## Advantages Over Biome\n\n### Type-Aware Linting\n- Catches errors traditional linters miss\n- Uses TypeScript's type system\n- Detects type mismatches, unnecessary null checks, Promise errors\n\n### Even Faster Linting\n- 2-3x faster than Biome for linting (non-type-aware mode)\n- Comparable speed to Biome when type-aware enabled\n\n### TypeScript-First Design\n- Built specifically for TypeScript codebases\n- Better TypeScript integration\n\n## Advantages Over ESLint\n\n### Performance\n- 100x faster than ESLint with type-aware rules\n- Rust-based (vs JavaScript)\n\n### Simpler Configuration\n- Single tool for linting + formatting (vs ESLint + Prettier)\n- Type-awareness built-in (vs separate `@typescript-eslint/*` packages)\n\n## Limitations\n\n### Newer Ecosystem\n- Fewer community plugins than ESLint\n- Less documentation and examples\n- Smaller community\n\n### Rule Coverage\n- Fewer total rules than ESLint (but covers most common cases)\n- Missing some niche ESLint plugins\n\n### CSS Linting\n- No CSS/SCSS support\n- Use ESLint provider or add Stylelint separately\n\n## When to Choose Oxlint Over Other Providers\n\n### ✅ Choose Oxlint When:\n- TypeScript is primary language (>80% of codebase)\n- Type safety is critical (financial, healthcare, security apps)\n- Large codebase (10,000+ files) needs fast CI\n- Want to catch type-related bugs early\n- Performance is top priority\n\n### ⚠️ Consider Alternatives When:\n- Need ESLint plugin ecosystem\n- CSS/SCSS linting is important\n- Team unfamiliar with type-aware linting\n- JavaScript-heavy project (not TypeScript)\n\n## Diagnostics\n\n```bash\n# Check Oxlint configuration\nnpx ultracite doctor\n\n# Validate TypeScript config integration\nnpx oxlint --print-config\n\n# Test type-aware linting\nnpx oxlint --type-aware --debug\n```\n\n## Troubleshooting\n\n### Type-Aware Linting Not Working\n\n**Problem**: Type errors not being detected\n\n**Check**:\n1. `typeAware: true` in `oxlintrc.json`\n2. Valid `tsconfig.json` path\n3. TypeScript installed as dependency\n\n**Fix**:\n```bash\n# Ensure TypeScript is installed\nbun add -D typescript\n\n# Validate tsconfig.json\nnpx tsc --noEmit\n```\n\n### Slow Type-Aware Performance\n\n**Solutions**:\n1. Enable incremental type checking\n2. Exclude large directories from type checking\n3. Use `--no-type-aware` for quick checks\n\n```json\n{\n \"typeAware\": true,\n \"incremental\": true,\n \"exclude\": [\n \"node_modules\",\n \"dist\",\n \"**/*.test.ts\" // Exclude tests from type checking\n ]\n}\n```\n\n### \"Cannot find tsconfig.json\" Error\n\n**Problem**: Oxlint can't locate TypeScript config\n\n**Solution**: Specify path explicitly:\n\n```json\n{\n \"typeAware\": true,\n \"tsconfig\": \"./tsconfig.app.json\" // Explicit path\n}\n```\n\n## Resources\n\n- [Oxlint Official Docs](https://oxc-project.github.io/docs/guide/usage/linter)\n- [Ultracite Oxlint Docs](https://www.ultracite.ai/providers/oxlint)\n- [Type-Aware Linting Guide](https://www.ultracite.ai/guides/type-aware-linting)\n- [GitHub](https://github.com/oxc-project/oxc)\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":8061,"content_sha256":"e610b70d98428e5342a44a52e9f317b080b3fe861d0c682369e3890f77ef4479"},{"filename":"references/troubleshooting.md","content":"# Ultracite Troubleshooting Guide\n\nSolutions for common issues, errors, and configuration problems when using Ultracite.\n\n**Last Updated**: 2025-11-22\n\n---\n\n## VS Code Issues\n\n### VS Code Not Formatting on Save\n\n**Symptom**: Files don't format when saving in VS Code\n\n**Solution 1**: Install Biome extension\n\n```bash\n# Install from VS Code Marketplace\ncode --install-extension biomejs.biome\n```\n\n**Solution 2**: Configure VS Code settings\n\n`.vscode/settings.json`:\n```json\n{\n \"editor.defaultFormatter\": \"biomejs.biome\",\n \"editor.formatOnSave\": true,\n \"editor.codeActionsOnSave\": {\n \"quickfix.biome\": \"explicit\",\n \"source.organizeImports.biome\": \"explicit\"\n }\n}\n```\n\n**Solution 3**: Reload VS Code\n\n```\nCmd+Shift+P → \"Developer: Reload Window\"\n```\n\n---\n\n### VS Code Shows \"Biome Not Found\"\n\n**Symptom**:\n```\nBiome executable not found in PATH\n```\n\n**Solution 1**: Install Ultracite locally\n\n```bash\nbun add -D ultracite\n```\n\n**Solution 2**: Specify Biome path in VS Code settings\n\n`.vscode/settings.json`:\n```json\n{\n \"biome.lspBin\": \"./node_modules/.bin/biome\"\n}\n```\n\n**Solution 3**: Restart VS Code after installation\n\n---\n\n### VS Code Shows Lint Errors But CLI Doesn't\n\n**Symptom**: VS Code shows errors that `ultracite check` doesn't report\n\n**Cause**: VS Code extension uses different config than CLI\n\n**Solution**: Ensure both use same config\n\n```bash\n# Check CLI config path\nbunx ultracite check --verbose\n\n# Verify VS Code uses same path\n# .vscode/settings.json\n{\n \"biome.configPath\": \"./biome.json\"\n}\n```\n\n---\n\n## Conflicts with ESLint/Prettier\n\n### ESLint and Ultracite Disagreeing\n\n**Symptom**: ESLint errors contradict Ultracite rules\n\n**Solution 1**: Disable ESLint (recommended)\n\n```bash\n# Remove ESLint\nbun remove eslint\n\n# Remove config\nrm .eslintrc.json\n```\n\n**Solution 2**: Run only Ultracite\n\n**Before**:\n```json\n{\n \"scripts\": {\n \"lint\": \"eslint . && ultracite check\"\n }\n}\n```\n\n**After**:\n```json\n{\n \"scripts\": {\n \"lint\": \"ultracite check\"\n }\n}\n```\n\n**Solution 3**: Keep ESLint for specific plugins\n\nIf you need ESLint plugins without Biome equivalents:\n\n```json\n{\n \"scripts\": {\n \"lint\": \"ultracite check\",\n \"lint:tests\": \"eslint **/*.test.ts --plugin testing-library\"\n }\n}\n```\n\n---\n\n### Prettier and Ultracite Formatting Conflicts\n\n**Symptom**: Files reformatted differently by Prettier vs Ultracite\n\n**Solution 1**: Remove Prettier (recommended)\n\n```bash\nbun remove prettier\nrm .prettierrc\n```\n\n**Solution 2**: Disable Prettier in pre-commit hooks\n\n**Before** (`.husky/pre-commit`):\n```bash\nprettier --write . && ultracite check --write\n```\n\n**After**:\n```bash\nultracite check --write\n```\n\n**Solution 3**: Disable Prettier in VS Code\n\n`.vscode/settings.json`:\n```json\n{\n \"editor.defaultFormatter\": \"biomejs.biome\", // Not Prettier\n \"prettier.enable\": false\n}\n```\n\n---\n\n## Parse Errors\n\n### \"Unexpected token\" Error\n\n**Symptom**:\n```\nParse error: Unexpected token '\u003c' at line 5\n```\n\n**Cause**: Biome doesn't support JSX in `.js` files by default\n\n**Solution**: Configure JSX support\n\n`biome.json`:\n```jsonc\n{\n \"javascript\": {\n \"parser\": {\n \"unsafeParameterDecoratorsEnabled\": true\n }\n },\n \"jsx\": {\n \"runtime\": \"reactClassic\" // or \"automatic\" for React 17+\n }\n}\n```\n\n---\n\n### \"Invalid JSON\" Error\n\n**Symptom**:\n```\nConfiguration file contains invalid JSON\n```\n\n**Cause**: JSON syntax error in `biome.json`\n\n**Solution**: Validate JSON\n\n```bash\n# Use JSONC (supports comments)\nmv biome.json biome.jsonc\n\n# Validate syntax\njq . biome.jsonc\n```\n\n**Common mistakes**:\n- Trailing commas in JSON (use JSONC instead)\n- Missing quotes around keys\n- Unclosed brackets/braces\n\n---\n\n### \"Schema Validation Failed\"\n\n**Symptom**:\n```\nSchema validation failed: Unknown property 'extends'\n```\n\n**Cause**: Using Biome v1.8 or earlier (no `extends` support)\n\n**Solution**: Update to Biome v1.9+\n\n```bash\nbun update ultracite\n```\n\n---\n\n## Pre-Commit Hook Failures\n\n### Hook Fails Silently\n\n**Symptom**: Git commits succeed even when linting fails\n\n**Cause**: Hook script missing `set -e` or has incorrect exit code\n\n**Solution**: Add error handling\n\n`.husky/pre-commit`:\n```bash\n#!/usr/bin/env sh\nset -e # ← Exit on error\n\n. \"$(dirname -- \"$0\")/_/husky.sh\"\n\nultracite check --staged --write\n```\n\n---\n\n### Hook Says \"Command Not Found\"\n\n**Symptom**:\n```\n.husky/pre-commit: line 4: ultracite: command not found\n```\n\n**Cause**: Hook runs before `node_modules` is in PATH\n\n**Solution 1**: Use `bunx`\n\n```bash\nbunx ultracite check --staged --write\n```\n\n**Solution 2**: Use absolute path\n\n```bash\n./node_modules/.bin/ultracite check --staged --write\n```\n\n**Solution 3**: Install Ultracite globally (not recommended)\n\n```bash\nbun add -g ultracite\n```\n\n---\n\n### Hook is Too Slow\n\n**Symptom**: Pre-commit hook takes >10 seconds\n\n**Solution 1**: Lint only staged files\n\n```bash\n# ✓ Fast (only staged files)\nultracite check --staged --write\n\n# ✗ Slow (entire codebase)\nultracite check --write\n```\n\n**Solution 2**: Use lint-staged\n\n```json\n{\n \"lint-staged\": {\n \"*.{js,jsx,ts,tsx}\": [\n \"ultracite check --write --no-errors-on-unmatched\"\n ]\n }\n}\n```\n\n**Solution 3**: Skip hook for WIP commits\n\n```bash\ngit commit --no-verify -m \"WIP: work in progress\"\n```\n\n---\n\n## CI Failures\n\n### CI Fails But Local Passes\n\n**Symptom**: `ultracite check` passes locally but fails in CI\n\n**Cause 1**: Different Node/Bun versions\n\n**Solution**: Pin versions in CI\n\n**GitHub Actions**:\n```yaml\n- uses: oven-sh/setup-bun@v1\n with:\n bun-version: 1.0.20 # Match local version\n```\n\n**Cause 2**: Different config files\n\n**Solution**: Verify same config in CI\n\n```bash\n# In CI, print config path\nbunx ultracite check --verbose\n```\n\n---\n\n### CI Runs Out of Memory\n\n**Symptom**:\n```\nFATAL ERROR: Reached heap limit Allocation failed\n```\n\n**Solution**: Increase Node memory limit\n\n**GitHub Actions**:\n```yaml\n- name: Run Ultracite\n run: NODE_OPTIONS=\"--max-old-space-size=4096\" bunx ultracite check\n```\n\n**GitLab CI**:\n```yaml\nlint:\n variables:\n NODE_OPTIONS: \"--max-old-space-size=4096\"\n script:\n - bunx ultracite check\n```\n\n---\n\n### CI Fails on Formatting\n\n**Symptom**:\n```\nerror[OrganizeImports]: Imports not organized\n```\n\n**Cause**: Code formatted locally but not committed\n\n**Solution**: Format before committing\n\n```bash\nbunx ultracite format --write .\ngit add .\ngit commit -m \"chore: format code\"\n```\n\n**Or**: Auto-format in pre-commit hook\n\n```bash\n# .husky/pre-commit\nultracite format --write --staged\n```\n\n---\n\n## TypeScript Strictness Errors\n\n### Ultracite Enables Strict Mode\n\n**Symptom**: New TypeScript errors after enabling Ultracite\n\n**Cause**: Ultracite enforces stricter TypeScript rules\n\n**Solution 1**: Fix TypeScript errors (recommended)\n\n```bash\n# Find all TypeScript errors\ntsc --noEmit\n```\n\n**Solution 2**: Disable strict checks temporarily\n\n`biome.json`:\n```jsonc\n{\n \"linter\": {\n \"rules\": {\n \"correctness\": {\n \"noUndeclaredVariables\": \"off\",\n \"noUnusedVariables\": \"warn\" // Warn instead of error\n }\n }\n }\n}\n```\n\n**Solution 3**: Use `// @ts-expect-error` for known issues\n\n```typescript\n// @ts-expect-error - Legacy code, will fix later\nconst result = unsafeFunction();\n```\n\n---\n\n### \"Type is not assignable\" Errors\n\n**Symptom**:\n```\nType 'string | undefined' is not assignable to type 'string'\n```\n\n**Cause**: Ultracite enforces stricter null checking\n\n**Solution**: Add type guards\n\n**Before**:\n```typescript\nconst name = user.name; // Error if name is optional\n```\n\n**After**:\n```typescript\nconst name = user.name ?? \"Anonymous\";\n// or\nif (user.name) {\n const name = user.name;\n}\n```\n\n---\n\n## Installation Issues\n\n### \"Package Not Found\"\n\n**Symptom**:\n```\nerror: package \"ultracite\" not found\n```\n\n**Solution**: Install from correct registry\n\n```bash\n# Bun\nbun add -D ultracite\n\n# npm\nnpm install -D ultracite\n\n# pnpm\npnpm add -D ultracite\n\n# Yarn\nyarn add -D ultracite\n```\n\n---\n\n### Version Conflict\n\n**Symptom**:\n```\npeer dependency conflict: ultracite requires @biomejs/biome ^1.9.0\n```\n\n**Solution**: Update dependencies\n\n```bash\nbun update ultracite @biomejs/biome\n```\n\n---\n\n### Installation Fails on Windows\n\n**Symptom**:\n```\nError: EPERM: operation not permitted\n```\n\n**Solution 1**: Run as Administrator\n\n**Solution 2**: Use WSL (Windows Subsystem for Linux)\n\n```bash\n# Install in WSL\nwsl\nbun add -D ultracite\n```\n\n**Solution 3**: Disable antivirus temporarily\n\n---\n\n## Performance Issues\n\n### Linting Takes Too Long\n\n**Symptom**: `ultracite check` takes >30 seconds\n\n**Solution 1**: Exclude unnecessary files\n\n`biome.json`:\n```jsonc\n{\n \"files\": {\n \"ignore\": [\n \"**/node_modules\",\n \"**/dist\",\n \"**/.next\",\n \"**/build\",\n \"**/coverage\",\n \"**/*.generated.ts\"\n ]\n }\n}\n```\n\n**Solution 2**: Use `--changed` flag (lint only changed files)\n\n```bash\nbunx ultracite check --changed\n```\n\n**Solution 3**: Enable caching in monorepos (Turborepo/Nx)\n\n---\n\n### High CPU Usage\n\n**Symptom**: Ultracite uses 100% CPU\n\n**Cause**: Linting large files or many files in parallel\n\n**Solution 1**: Limit file size\n\n`biome.json`:\n```jsonc\n{\n \"files\": {\n \"maxSize\": 1048576 // 1 MB limit\n }\n}\n```\n\n**Solution 2**: Reduce parallelism\n\n```bash\nbunx ultracite check --max-diagnostics=50\n```\n\n---\n\n## Configuration Issues\n\n### Config Not Loaded\n\n**Symptom**: Rules in `biome.json` ignored\n\n**Cause**: Config file not found or invalid\n\n**Solution 1**: Verify config path\n\n```bash\nbunx ultracite check --verbose\n# Output shows: \"Loaded configuration from: /path/to/biome.json\"\n```\n\n**Solution 2**: Check config syntax\n\n```bash\n# Validate JSON\njq . biome.json\n```\n\n**Solution 3**: Use explicit config path\n\n```bash\nbunx ultracite check --config-path=./biome.json\n```\n\n---\n\n### Extends Not Working\n\n**Symptom**: Preset rules not applied\n\n**Cause**: Using Biome v1.8 or earlier\n\n**Solution**: Update to v1.9+\n\n```bash\nbun update ultracite\n```\n\nVerify version:\n```bash\nbunx ultracite --version # Should be 1.9.0+\n```\n\n---\n\n### Rules Randomly Change\n\n**Symptom**: Same code lints differently on different runs\n\n**Cause 1**: Config file changed (check git history)\n\n**Solution**:\n```bash\ngit diff biome.json\n```\n\n**Cause 2**: Ultracite version changed\n\n**Solution**: Pin version in `package.json`:\n```json\n{\n \"devDependencies\": {\n \"ultracite\": \"0.9.4\" // Pin exact version\n }\n}\n```\n\n---\n\n## Best Practices to Avoid Issues\n\n1. **Pin Ultracite version** in `package.json`\n2. **Commit `biome.json`** to version control\n3. **Use `bunx`** instead of global installs\n4. **Test locally** before pushing to CI\n5. **Enable verbose mode** (`--verbose`) when debugging\n6. **Keep dependencies updated** (quarterly)\n7. **Use presets** (`ultracite/core`, `ultracite/react`) to avoid manual config\n8. **Document custom rules** in comments\n\n---\n\n**See also:**\n- `configuration-guide.md` for config details\n- `migration-guides.md` for ESLint/Prettier migration\n- `limitations-and-workarounds.md` for known issues\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":10927,"content_sha256":"45275b1fc37b7ddb01347f1f973ce4250e9fdeb6df7f569b694f93aa5a10d4a0"},{"filename":"references/v6-migration.md","content":"# Ultracite v6 Migration Guide\n\n**Version**: v5 → v6\n**Released**: 2025-09\n**Key Change**: Framework-specific presets introduced\n\n## Overview\n\nUltracite v6 introduced framework-specific presets to provide better out-of-the-box configurations for React, Next.js, Vue, Svelte, and other popular frameworks. This version maintains backward compatibility with v5 configurations while offering enhanced framework support.\n\n## What's New in v6\n\n### Framework-Specific Presets\n\n**Before v5** (generic configuration):\n```jsonc\n{\n \"extends\": [\"ultracite/core\"]\n // Manual framework rules configuration required\n}\n```\n\n**After v6** (framework-optimized):\n```jsonc\n{\n \"extends\": [\n \"ultracite/core\",\n \"ultracite/react\" // Framework preset\n ]\n}\n```\n\n### Available Framework Presets\n\n- `ultracite/react` - React + JSX rules\n- `ultracite/next` - Next.js optimization (Image, Link components)\n- `ultracite/vue` - Vue 3 SFC, composables, reactivity\n- `ultracite/svelte` - Svelte components, reactive declarations\n- `ultracite/solid` - Solid.js patterns\n- `ultracite/qwik` - Qwik framework\n- `ultracite/angular` - Angular components\n- `ultracite/remix` - Remix framework\n- `ultracite/astro` - Astro framework\n\n## Migration Steps\n\n### Step 1: Update Ultracite Package\n\n```bash\n# Using Bun\nbun update ultracite @biomejs/biome\n\n# Using npm\nnpm update ultracite @biomejs/biome\n\n# Using pnpm\npnpm update ultracite @biomejs/biome\n\n# Using yarn\nyarn upgrade ultracite @biomejs/biome\n```\n\n### Step 2: Add Framework Preset\n\nIdentify your framework and add the appropriate preset:\n\n**React Projects**:\n```jsonc\n{\n \"extends\": [\n \"ultracite/core\",\n \"ultracite/react\" // Add this\n ]\n}\n```\n\n**Next.js Projects**:\n```jsonc\n{\n \"extends\": [\n \"ultracite/core\",\n \"ultracite/next\" // Next.js preset includes React rules\n ]\n}\n```\n\n**Vue Projects**:\n```jsonc\n{\n \"extends\": [\n \"ultracite/core\",\n \"ultracite/vue\"\n ]\n}\n```\n\n**Svelte Projects**:\n```jsonc\n{\n \"extends\": [\n \"ultracite/core\",\n \"ultracite/svelte\"\n ]\n}\n```\n\n### Step 3: Remove Manual Framework Rules\n\nIf you manually configured framework rules in v5, you can now remove them:\n\n**Before** (v5 manual configuration):\n```jsonc\n{\n \"extends\": [\"ultracite/core\"],\n \"linter\": {\n \"rules\": {\n \"jsx-a11y\": {\n \"useKeyWithClickEvents\": \"error\",\n \"noAccessKey\": \"error\"\n },\n \"react\": {\n \"useJsxKeyInIterable\": \"error\",\n \"useValidAriaProps\": \"error\"\n }\n }\n }\n}\n```\n\n**After** (v6 with preset):\n```jsonc\n{\n \"extends\": [\n \"ultracite/core\",\n \"ultracite/react\" // Includes all standard React rules\n ]\n // Manual rules removed\n}\n```\n\n### Step 4: Test Configuration\n\n```bash\n# Check for linting errors\nnpx ultracite check .\n\n# Format files\nnpx ultracite format .\n\n# Fix issues\nnpx ultracite fix .\n```\n\n### Step 5: Review and Customize\n\nFramework presets provide sensible defaults. Customize if needed:\n\n```jsonc\n{\n \"extends\": [\"ultracite/core\", \"ultracite/react\"],\n \"linter\": {\n \"rules\": {\n \"react\": {\n \"useJsxKeyInIterable\": \"warn\" // Downgrade to warning\n }\n }\n }\n}\n```\n\n## Breaking Changes\n\n### None (v6 is Backward Compatible)\n\nv6 maintains full backward compatibility with v5 configurations. You can continue using `ultracite/core` without framework presets if desired.\n\n## New Features in v6\n\n### 1. Framework-Specific Rule Tuning\n\nEach framework preset includes optimized rules:\n\n**React Preset** includes:\n- JSX accessibility rules\n- Hook dependency validation\n- Component prop validation\n- React-specific best practices\n\n**Next.js Preset** includes:\n- Image component optimization warnings\n- Link component usage\n- Next.js-specific patterns\n- SEO best practices\n\n**Vue Preset** includes:\n- SFC structure validation\n- Composition API patterns\n- Reactivity best practices\n- Vue 3 specific rules\n\n### 2. Automatic Framework Detection\n\nWhen running `ultracite init`, framework detection is now automatic:\n\n```bash\n# v6 automatically detects React and suggests preset\nbun x ultracite init\n\n# Output:\n# ✓ Detected framework: React\n# ✓ Adding preset: ultracite/react\n```\n\n### 3. Improved Error Messages\n\nFramework-specific error messages:\n\n**Before v5**:\n```\nError: Missing key prop (correctness/useJsxKeyInIterable)\n```\n\n**After v6**:\n```\nError: Missing key prop in React list rendering\n → Each child in a list should have a unique \"key\" prop\n → Framework: React\n → Preset: ultracite/react\n```\n\n## Framework Preset Details\n\n### React Preset Rules\n\n```jsonc\n// Included in ultracite/react\n{\n \"jsx-a11y\": {\n \"useKeyWithClickEvents\": \"error\",\n \"noAccessKey\": \"error\",\n \"useAltText\": \"error\",\n \"useAnchorContent\": \"error\"\n },\n \"react\": {\n \"useJsxKeyInIterable\": \"error\",\n \"useValidAriaProps\": \"error\",\n \"useButtonType\": \"error\",\n \"noChildrenProp\": \"error\",\n \"noDangerouslySetInnerHtml\": \"warn\"\n }\n}\n```\n\n### Next.js Preset Rules\n\n```jsonc\n// Included in ultracite/next (extends ultracite/react)\n{\n \"next\": {\n \"useImageImport\": \"error\", // Use next/image\n \"useLinkImport\": \"error\", // Use next/link\n \"noHtmlLinkForPages\": \"error\", // Avoid \u003ca> for internal links\n \"noImgElement\": \"warn\" // Prefer \u003cImage>\n }\n}\n```\n\n## Compatibility\n\n### v5 Configurations Still Work\n\nYour existing v5 `biome.jsonc` will continue to work without changes:\n\n```jsonc\n// v5 configuration (still valid in v6)\n{\n \"extends\": [\"ultracite/core\"],\n \"linter\": {\n \"rules\": {\n // ... custom rules\n }\n }\n}\n```\n\n### When to Upgrade to Framework Presets\n\n**Upgrade if**:\n- You want framework-specific optimizations\n- You're manually maintaining framework rules\n- You want better error messages\n- You're starting a new project\n\n**Keep v5 config if**:\n- You have heavily customized rules\n- Migration effort outweighs benefits\n- You prefer manual control\n\n## Troubleshooting\n\n### \"Preset not found\" Error\n\n**Problem**: `ultracite/react` not found\n\n**Solution**: Update Ultracite to v6:\n\n```bash\nbun update ultracite\n# Verify version\nnpx ultracite --version # Should be >= 6.0.0\n```\n\n### Conflicting Rules After Adding Preset\n\n**Problem**: Custom rules conflict with preset rules\n\n**Solution**: Preset rules have lower priority. Your custom rules override:\n\n```jsonc\n{\n \"extends\": [\"ultracite/core\", \"ultracite/react\"],\n \"linter\": {\n \"rules\": {\n \"react\": {\n \"useJsxKeyInIterable\": \"off\" // Overrides preset\n }\n }\n }\n}\n```\n\n### Which Preset for My Framework?\n\n**Detection**:\n```bash\n# Let Ultracite detect framework\nbun x ultracite init\n\n# Manual detection\ngrep -E \"(react|vue|svelte)\" package.json\n```\n\n## Next Steps\n\nAfter migrating to v6:\n\n1. **Test thoroughly**: Run linting on entire codebase\n2. **Review new errors**: Framework presets may surface new issues\n3. **Customize as needed**: Override preset rules if necessary\n4. **Update team docs**: Document which preset is being used\n5. **Consider v7**: Plan for v7 migration (multi-provider support)\n\n## Resources\n\n- v6 Announcement: https://www.ultracite.ai/blog/v6-release\n- Framework Presets Guide: https://www.ultracite.ai/guides/framework-presets\n- Migration FAQ: https://www.ultracite.ai/faq#v6-migration\n- GitHub Changelog: https://github.com/ultracite/ultracite/releases/tag/v6.0.0\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":7267,"content_sha256":"c0b9ee3578bd6815c2894d77941e45a3478f7c71425232a102cb32ca1e703b8d"},{"filename":"references/v7-migration.md","content":"---\ntitle: Ultracite v7 Migration Guide\nversion: v7\nreleased: 2025-11\ndescription: Migration guide from Ultracite v6 to v7 with multi-provider architecture and preset path changes\ntags: [migration, v7, multi-provider, breaking-changes]\n---\n\n# Ultracite v7 Migration Guide\n\n**Version**: v6 → v7\n**Released**: 2025-11\n**Key Changes**: Multi-provider architecture, preset path migration, MCP server, AI hooks\n\n## Overview\n\nUltracite v7 represents a **major architectural change** introducing multi-provider support (Biome, ESLint, Oxlint) and breaking changes to preset paths. This guide helps you migrate from v6 to v7 smoothly.\n\n## What's New in v7\n\n### 1. Multi-Provider Architecture\n\nv7 supports three linting providers:\n\n- **Biome** (default) - Fastest, Rust-based\n- **ESLint + Prettier + Stylelint** - Maximum compatibility\n- **Oxlint + Oxfmt** - Type-aware, ultra-fast\n\n### 2. Breaking Change: Preset Paths\n\n**v6 paths (deprecated)**:\n```jsonc\n{\n \"extends\": [\"ultracite/core\", \"ultracite/react\"]\n}\n```\n\n**v7 paths (required)**:\n```jsonc\n{\n \"extends\": [\"ultracite/biome/core\", \"ultracite/biome/react\"]\n}\n```\n\n### 3. New Features\n\n- **MCP Server**: AI assistant integration via Model Context Protocol\n- **AI Hooks**: Auto-format after AI edits (separate from AI rules)\n- **Type-Aware Linting**: Oxlint provider uses TypeScript type system\n- **`ultracite doctor`**: Diagnostic command to validate configuration\n- **Programmatic API**: `--quiet` flag for CI/CD automation\n\n## Migration Steps\n\n### Step 1: Update Ultracite Package\n\n```bash\n# Using Bun (recommended)\nbun update ultracite @biomejs/biome\n\n# Using npm\nnpm update ultracite @biomejs/biome\n\n# Using pnpm\npnpm update ultracite @biomejs/biome\n\n# Using yarn\nyarn upgrade ultracite @biomejs/biome\n```\n\nVerify version:\n```bash\nnpx ultracite --version\n# Should output: v7.x.x\n```\n\n### Step 2: Migrate Preset Paths (BREAKING CHANGE)\n\n**Automatic Migration** (recommended):\n```bash\n# Ultracite will auto-migrate preset paths\nnpx ultracite migrate --from v6 --to v7\n\n# Or use the doctor command to detect issues\nnpx ultracite doctor\n```\n\n**Manual Migration**:\n\nFind all instances of `ultracite/` in `biome.jsonc` and add `/biome/` segment:\n\n**Before (v6)**:\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\n \"ultracite/core\", // ❌ Old path\n \"ultracite/react\" // ❌ Old path\n ]\n}\n```\n\n**After (v7)**:\n```jsonc\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\n \"ultracite/biome/core\", // ✅ New path (added /biome/)\n \"ultracite/biome/react\" // ✅ New path (added /biome/)\n ]\n}\n```\n\n### Preset Path Migration Table\n\n| v6 Path | v7 Path (Biome) |\n|---------|----------------|\n| `ultracite/core` | `ultracite/biome/core` |\n| `ultracite/react` | `ultracite/biome/react` |\n| `ultracite/next` | `ultracite/biome/next` |\n| `ultracite/vue` | `ultracite/biome/vue` |\n| `ultracite/svelte` | `ultracite/biome/svelte` |\n| `ultracite/solid` | `ultracite/biome/solid` |\n| `ultracite/qwik` | `ultracite/biome/qwik` |\n| `ultracite/angular` | `ultracite/biome/angular` |\n| `ultracite/remix` | `ultracite/biome/remix` |\n| `ultracite/astro` | `ultracite/biome/astro` |\n\n### Step 3: Choose Your Provider (Optional)\n\n**Keep Biome (default)** - No action needed if you want to continue using Biome.\n\n**Switch to ESLint Provider**:\n```bash\n# Migrate to ESLint + Prettier + Stylelint\nnpx ultracite migrate --to-provider eslint\n\n# Manual setup\nbun add -D eslint prettier stylelint\n# Creates .eslintrc.js, .prettierrc.json, .stylelintrc.json\n```\n\n**Switch to Oxlint Provider**:\n```bash\n# Migrate to Oxlint + Oxfmt (type-aware)\nnpx ultracite migrate --to-provider oxlint\n\n# Manual setup\nbun add -D oxlint oxfmt\n# Creates oxlintrc.json\n```\n\n### Step 4: Run Diagnostics\n\n```bash\n# Validate v7 configuration\nnpx ultracite doctor\n\n# Check for issues:\n# ✓ Preset paths correct (v7 format)\n# ✓ Configuration file valid\n# ✓ Editor integration working\n# ✓ Git hooks configured\n# ⚠ Old v6 preset paths detected → migrate to v7\n```\n\n### Step 5: Test Configuration\n\n```bash\n# Lint codebase\nnpx ultracite check .\n\n# Format codebase\nnpx ultracite format .\n\n# Fix issues\nnpx ultracite fix .\n```\n\n### Step 6: Update CI/CD (if applicable)\n\nUpdate CI pipelines to use v7:\n\n**Before (v6)**:\n```yaml\n# .github/workflows/lint.yml\n- name: Lint\n run: npx ultracite check .\n```\n\n**After (v7)** - No changes needed unless using provider flags:\n```yaml\n# .github/workflows/lint.yml\n- name: Lint\n run: npx ultracite check . # Auto-detects provider\n\n# Or explicitly specify provider\n- name: Lint with Biome\n run: npx ultracite check . --provider biome\n```\n\n## Breaking Changes\n\n### 1. Preset Paths Require `/biome/` Segment\n\n**Impact**: All `ultracite/*` preset paths must include `/biome/`\n\n**Migration**: Add `/biome/` between `ultracite/` and preset name\n\n**Error if not migrated**:\n```\nError: Preset \"ultracite/core\" not found\n → Did you mean \"ultracite/biome/core\"?\n → Run: npx ultracite doctor\n```\n\n### 2. Configuration File Structure\n\nv7 maintains backward compatibility with v6 configuration structure. Only preset paths need updating.\n\n### 3. CLI Flags\n\nNew flags in v7:\n\n- `--linter`: Choose provider during init (biome, eslint, oxlint)\n- `--provider`: Specify provider for commands\n- `--quiet`: Suppress output for CI/CD\n\n**Example**:\n```bash\n# v7 new flag\nbun x ultracite init --linter oxlint\n\n# v6 equivalent (always used Biome)\nbun x ultracite init\n```\n\n## New Features in v7\n\n### 1. Multi-Provider Support\n\n**Choose at installation**:\n```bash\n# Biome (default)\nbun x ultracite init --linter biome\n\n# ESLint + Prettier + Stylelint\nbun x ultracite init --linter eslint\n\n# Oxlint + Oxfmt (type-aware)\nbun x ultracite init --linter oxlint\n```\n\n**See provider-specific docs**:\n- `references/provider-biome.md`\n- `references/provider-eslint.md`\n- `references/provider-oxlint.md`\n\n### 2. MCP Server Integration\n\nIntegrate Ultracite with AI assistants via Model Context Protocol:\n\n```bash\n# Install MCP server\nnpx ultracite mcp install\n\n# Configure for Claude Desktop\nnpx ultracite mcp configure --client claude-desktop\n\n# Configure for Cursor\nnpx ultracite mcp configure --client cursor\n```\n\n**See**: `references/mcp-integration.md`\n\n### 3. AI Hooks (New in v7)\n\nAI hooks auto-format code after AI edits (distinct from AI rules):\n\n**AI Rules** (existing): Guide AI to write better code\n**AI Hooks** (new): Auto-run `ultracite fix` after AI edits\n\n```bash\n# Install AI hooks for Cursor\nnpx ultracite ai-hooks install --editor cursor\n\n# Install for Claude Code\nnpx ultracite ai-hooks install --editor claude-code\n```\n\n**See**: `references/ai-hooks.md`\n\n### 4. Type-Aware Linting (Oxlint Provider)\n\nOxlint provider uses TypeScript's type system:\n\n```json\n// oxlintrc.json\n{\n \"extends\": [\"ultracite/oxlint/core\"],\n \"typeAware\": true,\n \"tsconfig\": \"./tsconfig.json\"\n}\n```\n\nCatches errors like:\n- Unnecessary null checks (type is non-nullable)\n- Promise handling errors (missing await)\n- Type mismatches\n\n**See**: `references/provider-oxlint.md`\n\n### 5. `ultracite doctor` Command\n\nDiagnostic tool to validate configuration:\n\n```bash\nnpx ultracite doctor\n\n# Output:\n# ✓ Ultracite version: v7.0.0\n# ✓ Provider: biome\n# ✓ Configuration file: biome.jsonc (valid)\n# ✓ Preset paths: v7 format\n# ✓ Editor integration: VS Code (Biome extension installed)\n# ✓ Git hooks: Husky configured\n# ⚠ TypeScript strictNullChecks: false (recommended: true)\n```\n\n### 6. Programmatic Usage\n\n`--quiet` flag for CI/CD:\n\n```bash\n# Suppress output, exit code only\nnpx ultracite check . --quiet\n\n# Exit codes:\n# 0 = No errors\n# 1 = Linting errors found\n# 2 = Configuration error\n```\n\n## Provider Comparison\n\n| Feature | Biome | ESLint | Oxlint |\n|---------|-------|--------|--------|\n| Speed | 🚀 Fastest | 🐢 Slowest | 🚀🚀 Fastest linting |\n| Setup | Zero-config | Requires config | Type-aware config |\n| Ecosystem | Growing | Mature (1000+ plugins) | Newer |\n| Type-Aware | ❌ No | ⚠️ Via plugins | ✅ Built-in |\n| CSS Linting | ⚠️ Basic | ✅ Stylelint integration | ❌ No |\n\n**Recommendation**:\n- **Biome**: Default choice for most projects\n- **ESLint**: Need specific ESLint plugins or advanced CSS linting\n- **Oxlint**: Large TypeScript codebases, type-safety critical\n\n## Troubleshooting\n\n### \"Preset not found\" Error\n\n**Problem**:\n```\nError: Preset \"ultracite/core\" not found\n```\n\n**Solution**: Migrate to v7 preset paths\n\n```bash\n# Auto-migrate\nnpx ultracite doctor --fix\n\n# Or manually add /biome/\n{\n \"extends\": [\"ultracite/biome/core\"] // Added /biome/\n}\n```\n\n### Mixed v6 and v7 Paths\n\n**Problem**: Some paths updated, others not\n\n```jsonc\n{\n \"extends\": [\n \"ultracite/biome/core\", // ✅ v7\n \"ultracite/react\" // ❌ v6 (missed)\n ]\n}\n```\n\n**Solution**: Update all paths consistently\n\n```bash\n# Use doctor to detect\nnpx ultracite doctor\n\n# Auto-fix\nnpx ultracite doctor --fix\n```\n\n### Provider-Specific Issues\n\n**Biome**: See `references/provider-biome.md`\n**ESLint**: See `references/provider-eslint.md`\n**Oxlint**: See `references/provider-oxlint.md`\n\n## Compatibility\n\n### v6 Configurations\n\nv6 configurations are **not compatible** with v7 without preset path migration.\n\n**Required changes**:\n- Add `/biome/` to all preset paths\n- OR migrate to different provider\n\n### TypeScript Version\n\n- Biome: No TypeScript dependency\n- ESLint: TypeScript 4.x+ recommended\n- Oxlint: TypeScript 5.x+ required for type-aware linting\n\n## Rollback to v6\n\nIf you need to roll back:\n\n```bash\n# Reinstall v6\nbun add -D ultracite@6 @biomejs/[email protected]\n\n# Revert preset paths in biome.jsonc\n# ultracite/biome/core → ultracite/core\n```\n\n## Next Steps\n\nAfter migrating to v7:\n\n1. **Test thoroughly**: Run linting on entire codebase\n2. **Update team docs**: Document provider choice and v7 paths\n3. **Explore new features**: MCP server, AI hooks, type-aware linting (Oxlint)\n4. **Monitor performance**: Benchmark v7 vs v6 linting speed\n5. **Consider provider switch**: Evaluate if different provider better suits needs\n\n## Resources\n\n- [v7 Release Notes](https://www.ultracite.ai/blog/v7-release)\n- [v7 Migration FAQ](https://www.ultracite.ai/faq#v7-migration)\n- [Multi-Provider Guide](https://www.ultracite.ai/guides/providers)\n- [Breaking Changes](https://www.ultracite.ai/breaking-changes/v7)\n- [GitHub Changelog](https://github.com/ultracite/ultracite/releases/tag/v7.0.0)\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":10431,"content_sha256":"db2f46383425184347fca515916d8af812526116190dfc1be5c0eb57c8e5e390"},{"filename":"scripts/install-ultracite.sh","content":"#!/usr/bin/env bash\n\n# Ultracite Installation Script\n# Automated setup for Ultracite with framework, editor, and Git hook integrations\n\nset -e\n\n# Colors for output\nRED='\\033[0;31m'\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nBLUE='\\033[0;34m'\nNC='\\033[0m' # No Color\n\n# Helper functions\ninfo() {\n echo -e \"${BLUE}ℹ${NC} $1\"\n}\n\nsuccess() {\n echo -e \"${GREEN}✓${NC} $1\"\n}\n\nwarning() {\n echo -e \"${YELLOW}⚠${NC} $1\"\n}\n\nerror() {\n echo -e \"${RED}✗${NC} $1\"\n}\n\n# Check if we're in a Node.js project\nif [ ! -f \"package.json\" ]; then\n error \"No package.json found. Please run this script from a Node.js project root.\"\n exit 1\nfi\n\ninfo \"Ultracite Installation Script\"\necho \"\"\n\n# Detect package manager\ndetect_package_manager() {\n if [ -f \"bun.lockb\" ] || command -v bun &> /dev/null; then\n echo \"bun\"\n elif [ -f \"pnpm-lock.yaml\" ] || command -v pnpm &> /dev/null; then\n echo \"pnpm\"\n elif [ -f \"yarn.lock\" ]; then\n echo \"yarn\"\n else\n echo \"npm\"\n fi\n}\n\nPM=$(detect_package_manager)\nsuccess \"Detected package manager: $PM\"\n\n# Detect framework\ndetect_framework() {\n if grep -q '\"next\"' package.json; then\n echo \"next\"\n elif grep -q '\"react\"' package.json; then\n echo \"react\"\n elif grep -q '\"vue\"' package.json; then\n echo \"vue\"\n elif grep -q '\"svelte\"' package.json; then\n echo \"svelte\"\n elif grep -q '\"solid-js\"' package.json; then\n echo \"solid\"\n elif grep -q '\"@angular/core\"' package.json; then\n echo \"angular\"\n elif grep -q '\"@remix-run\"' package.json; then\n echo \"remix\"\n else\n echo \"none\"\n fi\n}\n\nFRAMEWORK=$(detect_framework)\nif [ \"$FRAMEWORK\" != \"none\" ]; then\n success \"Detected framework: $FRAMEWORK\"\nelse\n info \"No framework detected, using core preset\"\nfi\n\n# Check for existing linting tools\ncheck_existing_tools() {\n local has_eslint=false\n local has_prettier=false\n local has_biome=false\n\n if grep -q '\"eslint\"' package.json 2>/dev/null || [ -f \".eslintrc.js\" ] || [ -f \".eslintrc.json\" ] || [ -f \"eslint.config.js\" ]; then\n has_eslint=true\n warning \"ESLint detected\"\n fi\n\n if grep -q '\"prettier\"' package.json 2>/dev/null || [ -f \".prettierrc\" ] || [ -f \".prettierrc.json\" ] || [ -f \"prettier.config.js\" ]; then\n has_prettier=true\n warning \"Prettier detected\"\n fi\n\n if grep -q '\"@biomejs/biome\"' package.json 2>/dev/null || [ -f \"biome.json\" ] || [ -f \"biome.jsonc\" ]; then\n has_biome=true\n info \"Biome detected\"\n fi\n\n if $has_eslint || $has_prettier; then\n echo \"\"\n warning \"Existing linting/formatting tools detected.\"\n echo \"Ultracite can migrate from these tools automatically.\"\n echo \"\"\n read -p \"Migrate and remove ESLint/Prettier? (y/n) \" -n 1 -r\n echo \"\"\n if [[ $REPLY =~ ^[Yy]$ ]]; then\n MIGRATE=true\n else\n MIGRATE=false\n warning \"Keeping existing tools. Note: May cause conflicts.\"\n fi\n fi\n}\n\ncheck_existing_tools\n\n# Check for existing Git hook managers\ncheck_git_hooks() {\n local has_husky=false\n local has_lefthook=false\n local has_lint_staged=false\n\n if grep -q '\"husky\"' package.json 2>/dev/null || [ -d \".husky\" ]; then\n has_husky=true\n info \"Husky detected\"\n fi\n\n if grep -q '\"lefthook\"' package.json 2>/dev/null || [ -f \"lefthook.yml\" ]; then\n has_lefthook=true\n info \"Lefthook detected\"\n fi\n\n if grep -q '\"lint-staged\"' package.json 2>/dev/null || [ -f \".lintstagedrc.json\" ]; then\n has_lint_staged=true\n info \"lint-staged detected\"\n fi\n\n if $has_husky || $has_lefthook || $has_lint_staged; then\n warning \"Git hook manager already installed. Skipping Git hooks setup.\"\n SKIP_HOOKS=true\n else\n echo \"\"\n info \"Would you like to set up Git hooks for automatic formatting?\"\n echo \" 1) Husky (most popular)\"\n echo \" 2) Lefthook (fastest, native Go)\"\n echo \" 3) lint-staged (only staged files)\"\n echo \" 4) None\"\n read -p \"Choose [1-4]: \" -n 1 -r\n echo \"\"\n case $REPLY in\n 1) GIT_HOOK=\"husky\" ;;\n 2) GIT_HOOK=\"lefthook\" ;;\n 3) GIT_HOOK=\"lint-staged\" ;;\n *) GIT_HOOK=\"none\" ;;\n esac\n fi\n}\n\ncheck_git_hooks\n\n# Build init command\nbuild_init_command() {\n local cmd=\"\"\n\n case $PM in\n bun) cmd=\"bun x ultracite init\" ;;\n pnpm) cmd=\"pnpm dlx ultracite init\" ;;\n yarn) cmd=\"yarn dlx ultracite init\" ;;\n npm) cmd=\"npx ultracite init\" ;;\n esac\n\n # Add package manager flag\n cmd=\"$cmd --pm $PM\"\n\n # Add framework flag\n if [ \"$FRAMEWORK\" != \"none\" ]; then\n cmd=\"$cmd --frameworks $FRAMEWORK\"\n fi\n\n # Add editor flags\n cmd=\"$cmd --editors vscode\"\n\n # Add migration flags\n if [ \"${MIGRATE:-false}\" = true ]; then\n if grep -q '\"eslint\"' package.json && grep -q '\"prettier\"' package.json; then\n cmd=\"$cmd --migrate eslint,prettier\"\n elif grep -q '\"eslint\"' package.json; then\n cmd=\"$cmd --migrate eslint\"\n elif grep -q '\"prettier\"' package.json; then\n cmd=\"$cmd --migrate prettier\"\n fi\n fi\n\n # Add Git hooks flag\n if [ \"${SKIP_HOOKS:-false}\" = false ] && [ \"${GIT_HOOK:-none}\" != \"none\" ]; then\n cmd=\"$cmd --integrations $GIT_HOOK\"\n fi\n\n echo \"$cmd\"\n}\n\nINIT_CMD=$(build_init_command)\n\necho \"\"\ninfo \"Running: $INIT_CMD\"\necho \"\"\n\n# Run the init command\neval $INIT_CMD\n\n# Verify installation\necho \"\"\ninfo \"Verifying installation...\"\n\nif [ -f \"biome.jsonc\" ] || [ -f \"biome.json\" ]; then\n success \"Configuration file created\"\nelse\n error \"Configuration file not found\"\n exit 1\nfi\n\nif grep -q '\"ultracite\"' package.json; then\n success \"Ultracite installed\"\nelse\n warning \"Ultracite not found in package.json\"\nfi\n\n# Run doctor command\necho \"\"\ninfo \"Running health check...\"\ncase $PM in\n bun) bun x ultracite doctor ;;\n pnpm) pnpm dlx ultracite doctor ;;\n yarn) yarn dlx ultracite doctor ;;\n npm) npx ultracite doctor ;;\nesac\n\necho \"\"\nsuccess \"Ultracite installation complete!\"\necho \"\"\ninfo \"Next steps:\"\necho \" 1. Restart your editor (VS Code, Cursor, etc.)\"\necho \" 2. Install the Biome extension if not already installed\"\necho \" 3. Save any file to see auto-formatting in action\"\necho \" 4. Run 'npx ultracite check' to see linting results\"\necho \" 5. Run 'npx ultracite fix' to auto-fix issues\"\necho \"\"\n\nif [ \"$FRAMEWORK\" != \"none\" ]; then\n info \"Framework preset applied: $FRAMEWORK\"\n echo \" - Review biome.jsonc for framework-specific rules\"\nfi\n\nif [ \"${GIT_HOOK:-none}\" != \"none\" ]; then\n info \"Git hooks configured: $GIT_HOOK\"\n echo \" - Pre-commit formatting will run automatically\"\nfi\n\necho \"\"\ninfo \"Documentation: https://www.ultracite.ai\"\nsuccess \"Happy coding!\"\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":6466,"content_sha256":"06d87e65cea80e2cd3b5bc13cbbadba30cbc70410a21a1d7b69258978eddf49b"},{"filename":"scripts/migrate-to-ultracite.sh","content":"#!/usr/bin/env bash\n\n# Ultracite Migration Script\n# Migrate from ESLint and/or Prettier to Ultracite\n\nset -e\n\n# Colors for output\nRED='\\033[0;31m'\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nBLUE='\\033[0;34m'\nNC='\\033[0m' # No Color\n\n# Helper functions\ninfo() {\n echo -e \"${BLUE}ℹ${NC} $1\"\n}\n\nsuccess() {\n echo -e \"${GREEN}✓${NC} $1\"\n}\n\nwarning() {\n echo -e \"${YELLOW}⚠${NC} $1\"\n}\n\nerror() {\n echo -e \"${RED}✗${NC} $1\"\n}\n\n# Check if we're in a Node.js project\nif [ ! -f \"package.json\" ]; then\n error \"No package.json found. Please run this script from a Node.js project root.\"\n exit 1\nfi\n\ninfo \"Ultracite Migration Script\"\necho \"\"\n\n# Detect current tools\nHAS_ESLINT=false\nHAS_PRETTIER=false\nHAS_BIOME=false\n\nif grep -q '\"eslint\"' package.json 2>/dev/null || [ -f \".eslintrc.js\" ] || [ -f \".eslintrc.json\" ] || [ -f \"eslint.config.js\" ] || [ -f \".eslintrc.cjs\" ]; then\n HAS_ESLINT=true\n warning \"ESLint detected\"\nfi\n\nif grep -q '\"prettier\"' package.json 2>/dev/null || [ -f \".prettierrc\" ] || [ -f \".prettierrc.json\" ] || [ -f \"prettier.config.js\" ] || [ -f \".prettierrc.cjs\" ]; then\n HAS_PRETTIER=true\n warning \"Prettier detected\"\nfi\n\nif grep -q '\"@biomejs/biome\"' package.json 2>/dev/null || [ -f \"biome.json\" ] || [ -f \"biome.jsonc\" ]; then\n HAS_BIOME=true\n info \"Biome detected (will extend with Ultracite presets)\"\nfi\n\nif ! $HAS_ESLINT && ! $HAS_PRETTIER && ! $HAS_BIOME; then\n error \"No linting/formatting tools detected.\"\n echo \" This script is for migration. For new setup, use install-ultracite.sh\"\n exit 1\nfi\n\necho \"\"\ninfo \"Migration targets:\"\n$HAS_ESLINT && echo \" - ESLint → Ultracite\"\n$HAS_PRETTIER && echo \" - Prettier → Ultracite\"\n$HAS_BIOME && echo \" - Biome → Ultracite (preset extension)\"\n\necho \"\"\nwarning \"This will modify your project configuration.\"\necho \" ⚠ ESLint and Prettier configs will be removed\"\necho \" ⚠ Dependencies will be uninstalled\"\necho \" ⚠ .vscode/settings.json will be updated\"\necho \"\"\nread -p \"Continue with migration? (y/n) \" -n 1 -r\necho \"\"\nif [[ ! $REPLY =~ ^[Yy]$ ]]; then\n info \"Migration cancelled.\"\n exit 0\nfi\n\n# Detect package manager\ndetect_package_manager() {\n if [ -f \"bun.lockb\" ] || command -v bun &> /dev/null; then\n echo \"bun\"\n elif [ -f \"pnpm-lock.yaml\" ] || command -v pnpm &> /dev/null; then\n echo \"pnpm\"\n elif [ -f \"yarn.lock\" ]; then\n echo \"yarn\"\n else\n echo \"npm\"\n fi\n}\n\nPM=$(detect_package_manager)\nsuccess \"Using package manager: $PM\"\n\n# Backup existing configs\nbackup_configs() {\n local backup_dir=\".ultracite-migration-backup-$(date +%Y%m%d-%H%M%S)\"\n mkdir -p \"$backup_dir\"\n\n info \"Backing up existing configs to $backup_dir/\"\n\n # ESLint configs\n [ -f \".eslintrc.js\" ] && cp .eslintrc.js \"$backup_dir/\" && success \"Backed up .eslintrc.js\"\n [ -f \".eslintrc.json\" ] && cp .eslintrc.json \"$backup_dir/\" && success \"Backed up .eslintrc.json\"\n [ -f \".eslintrc.cjs\" ] && cp .eslintrc.cjs \"$backup_dir/\" && success \"Backed up .eslintrc.cjs\"\n [ -f \"eslint.config.js\" ] && cp eslint.config.js \"$backup_dir/\" && success \"Backed up eslint.config.js\"\n [ -f \".eslintignore\" ] && cp .eslintignore \"$backup_dir/\" && success \"Backed up .eslintignore\"\n\n # Prettier configs\n [ -f \".prettierrc\" ] && cp .prettierrc \"$backup_dir/\" && success \"Backed up .prettierrc\"\n [ -f \".prettierrc.json\" ] && cp .prettierrc.json \"$backup_dir/\" && success \"Backed up .prettierrc.json\"\n [ -f \".prettierrc.js\" ] && cp .prettierrc.js \"$backup_dir/\" && success \"Backed up .prettierrc.js\"\n [ -f \".prettierrc.cjs\" ] && cp .prettierrc.cjs \"$backup_dir/\" && success \"Backed up .prettierrc.cjs\"\n [ -f \"prettier.config.js\" ] && cp prettier.config.js \"$backup_dir/\" && success \"Backed up prettier.config.js\"\n [ -f \".prettierignore\" ] && cp .prettierignore \"$backup_dir/\" && success \"Backed up .prettierignore\"\n\n # Biome config (if extending)\n [ -f \"biome.json\" ] && cp biome.json \"$backup_dir/\" && success \"Backed up biome.json\"\n [ -f \"biome.jsonc\" ] && cp biome.jsonc \"$backup_dir/\" && success \"Backed up biome.jsonc\"\n\n # VS Code settings\n [ -f \".vscode/settings.json\" ] && cp .vscode/settings.json \"$backup_dir/\" && success \"Backed up .vscode/settings.json\"\n\n success \"Backup complete: $backup_dir/\"\n}\n\nbackup_configs\n\necho \"\"\n\n# Detect framework\ndetect_framework() {\n if grep -q '\"next\"' package.json; then\n echo \"next\"\n elif grep -q '\"react\"' package.json; then\n echo \"react\"\n elif grep -q '\"vue\"' package.json; then\n echo \"vue\"\n elif grep -q '\"svelte\"' package.json; then\n echo \"svelte\"\n else\n echo \"core\"\n fi\n}\n\nFRAMEWORK=$(detect_framework)\nsuccess \"Detected framework: $FRAMEWORK\"\n\n# Build migration flags\nMIGRATE_FLAGS=\"\"\n$HAS_ESLINT && MIGRATE_FLAGS=\"${MIGRATE_FLAGS}eslint,\"\n$HAS_PRETTIER && MIGRATE_FLAGS=\"${MIGRATE_FLAGS}prettier,\"\n$HAS_BIOME && MIGRATE_FLAGS=\"${MIGRATE_FLAGS}biome,\"\nMIGRATE_FLAGS=${MIGRATE_FLAGS%,} # Remove trailing comma\n\n# Run Ultracite init with migration\necho \"\"\ninfo \"Running Ultracite init with migration...\"\n\nINIT_CMD=\"\"\ncase $PM in\n bun) INIT_CMD=\"bun x ultracite init\" ;;\n pnpm) INIT_CMD=\"pnpm dlx ultracite init\" ;;\n yarn) INIT_CMD=\"yarn dlx ultracite init\" ;;\n npm) INIT_CMD=\"npx ultracite init\" ;;\nesac\n\nINIT_CMD=\"$INIT_CMD --pm $PM --frameworks $FRAMEWORK --migrate $MIGRATE_FLAGS --editors vscode\"\n\ninfo \"Command: $INIT_CMD\"\necho \"\"\n\neval $INIT_CMD\n\n# Remove old config files (Ultracite init may not remove all)\necho \"\"\ninfo \"Cleaning up old configuration files...\"\n\nif $HAS_ESLINT; then\n rm -f .eslintrc.js .eslintrc.json .eslintrc.cjs eslint.config.js .eslintignore\n success \"Removed ESLint config files\"\nfi\n\nif $HAS_PRETTIER; then\n rm -f .prettierrc .prettierrc.json .prettierrc.js .prettierrc.cjs prettier.config.js .prettierignore\n success \"Removed Prettier config files\"\nfi\n\n# Uninstall old dependencies\necho \"\"\ninfo \"Removing old dependencies...\"\n\nREMOVE_CMD=\"\"\ncase $PM in\n bun) REMOVE_CMD=\"bun remove\" ;;\n pnpm) REMOVE_CMD=\"pnpm remove\" ;;\n yarn) REMOVE_CMD=\"yarn remove\" ;;\n npm) REMOVE_CMD=\"npm uninstall\" ;;\nesac\n\nif $HAS_ESLINT; then\n # Common ESLint packages\n ESLINT_PACKAGES=\"eslint\"\n\n # TypeScript ESLint\n grep -q '@typescript-eslint/parser' package.json && ESLINT_PACKAGES=\"$ESLINT_PACKAGES @typescript-eslint/parser\"\n grep -q '@typescript-eslint/eslint-plugin' package.json && ESLINT_PACKAGES=\"$ESLINT_PACKAGES @typescript-eslint/eslint-plugin\"\n\n # Framework-specific\n grep -q 'eslint-config-next' package.json && ESLINT_PACKAGES=\"$ESLINT_PACKAGES eslint-config-next\"\n grep -q 'eslint-plugin-react' package.json && ESLINT_PACKAGES=\"$ESLINT_PACKAGES eslint-plugin-react\"\n grep -q 'eslint-plugin-react-hooks' package.json && ESLINT_PACKAGES=\"$ESLINT_PACKAGES eslint-plugin-react-hooks\"\n grep -q 'eslint-plugin-vue' package.json && ESLINT_PACKAGES=\"$ESLINT_PACKAGES eslint-plugin-vue\"\n\n # Integrations\n grep -q 'eslint-config-prettier' package.json && ESLINT_PACKAGES=\"$ESLINT_PACKAGES eslint-config-prettier\"\n grep -q 'eslint-plugin-prettier' package.json && ESLINT_PACKAGES=\"$ESLINT_PACKAGES eslint-plugin-prettier\"\n grep -q 'eslint-plugin-import' package.json && ESLINT_PACKAGES=\"$ESLINT_PACKAGES eslint-plugin-import\"\n\n if [ -n \"$ESLINT_PACKAGES\" ]; then\n eval \"$REMOVE_CMD $ESLINT_PACKAGES\" 2>/dev/null || warning \"Some ESLint packages may not have been removed\"\n success \"Removed ESLint packages\"\n fi\nfi\n\nif $HAS_PRETTIER; then\n PRETTIER_PACKAGES=\"prettier\"\n grep -q 'eslint-config-prettier' package.json && PRETTIER_PACKAGES=\"$PRETTIER_PACKAGES eslint-config-prettier\"\n grep -q 'eslint-plugin-prettier' package.json && PRETTIER_PACKAGES=\"$PRETTIER_PACKAGES eslint-plugin-prettier\"\n\n eval \"$REMOVE_CMD $PRETTIER_PACKAGES\" 2>/dev/null || warning \"Some Prettier packages may not have been removed\"\n success \"Removed Prettier packages\"\nfi\n\n# Verify migration\necho \"\"\ninfo \"Verifying migration...\"\n\nif [ -f \"biome.jsonc\" ] || [ -f \"biome.json\" ]; then\n success \"Ultracite configuration file exists\"\n\n # Check for extends\n if grep -q 'ultracite/core' biome.json* 2>/dev/null; then\n success \"Ultracite preset configured\"\n else\n warning \"Ultracite preset not found in config\"\n fi\nelse\n error \"Configuration file not found\"\n exit 1\nfi\n\nif grep -q '\"ultracite\"' package.json; then\n success \"Ultracite dependency installed\"\nelse\n warning \"Ultracite not found in package.json\"\nfi\n\n# Update VS Code settings\nif [ -f \".vscode/settings.json\" ]; then\n info \"Checking VS Code settings...\"\n if grep -q '\"biomejs.biome\"' .vscode/settings.json; then\n success \"VS Code configured for Biome\"\n else\n warning \"VS Code settings may need manual update\"\n fi\nfi\n\n# Run doctor\necho \"\"\ninfo \"Running health check...\"\ncase $PM in\n bun) bun x ultracite doctor ;;\n pnpm) pnpm dlx ultracite doctor ;;\n yarn) yarn dlx ultracite doctor ;;\n npm) npx ultracite doctor ;;\nesac\n\necho \"\"\nsuccess \"Migration complete!\"\necho \"\"\ninfo \"What changed:\"\n$HAS_ESLINT && echo \" ✓ ESLint removed → Ultracite installed\"\n$HAS_PRETTIER && echo \" ✓ Prettier removed → Ultracite handles formatting\"\n$HAS_BIOME && echo \" ✓ Biome extended with Ultracite presets\"\necho \" ✓ Configuration files migrated\"\necho \" ✓ Dependencies updated\"\necho \" ✓ VS Code settings configured\"\n\necho \"\"\nwarning \"Important next steps:\"\necho \" 1. RESTART YOUR EDITOR (VS Code, Cursor, etc.)\"\necho \" 2. Install Biome extension if not already installed:\"\necho \" - VS Code: biomejs.biome\"\necho \" 3. Disable/uninstall conflicting extensions:\"\necho \" - ESLint extension (dbaeumer.vscode-eslint)\"\necho \" - Prettier extension (esbenp.prettier-vscode)\"\necho \" 4. Test formatting: Save any file\"\necho \" 5. Check for issues: npx ultracite check\"\necho \" 6. Auto-fix issues: npx ultracite fix\"\n\necho \"\"\ninfo \"Backups saved to: .ultracite-migration-backup-*/\"\ninfo \"If you encounter issues, you can restore from backups\"\n\necho \"\"\ninfo \"Documentation: https://www.ultracite.ai\"\nsuccess \"Happy coding with Ultracite!\"\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":9915,"content_sha256":"29d6ef618374e332d27fd47abfa9d6477972c944ffcfe339d473f42b23ebeaff"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Ultracite Skill","type":"text"}]},{"type":"paragraph","content":[{"text":"Fast, zero-config linting and formatting for modern JavaScript/TypeScript projects","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"Ultracite is a unified linting and formatting solution that supports multiple providers: ","type":"text"},{"text":"Biome","type":"text","marks":[{"type":"strong"}]},{"text":" (default, Rust-based), ","type":"text"},{"text":"ESLint+Prettier+Stylelint","type":"text","marks":[{"type":"strong"}]},{"text":", and ","type":"text"},{"text":"Oxlint+Oxfmt","type":"text","marks":[{"type":"strong"}]},{"text":". It provides framework-specific presets and zero-configuration defaults, replacing traditional ESLint+Prettier setups with a faster, simpler alternative. Ultracite operates invisibly in the background, automatically formatting code and applying fixes on every save.","type":"text"}]},{"type":"paragraph","content":[{"text":"Version 7 Changes","type":"text","marks":[{"type":"strong"}]},{"text":": Multi-provider architecture, preset path migration, MCP server support, AI hooks ","type":"text"},{"text":"Version 6 Changes","type":"text","marks":[{"type":"strong"}]},{"text":": Framework-specific presets introduced (React, Next.js, Vue, Svelte, etc.)","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Core Goals","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Lightning-Fast Performance","type":"text","marks":[{"type":"strong"}]},{"text":": Leverages Biome's Rust implementation for instant linting/formatting","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Zero-Config Design","type":"text","marks":[{"type":"strong"}]},{"text":": Ships with 200+ sensible defaults optimized for modern TypeScript development","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Simplicity & Invisibility","type":"text","marks":[{"type":"strong"}]},{"text":": Operates with minimal user interaction","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Type Safety","type":"text","marks":[{"type":"strong"}]},{"text":": Enforces TypeScript strict mode and comprehensive null/undefined handling","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Tool Compatibility","type":"text","marks":[{"type":"strong"}]},{"text":": Works alongside other development tools without conflicts","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Key Benefits vs Alternatives","type":"text"}]},{"type":"paragraph","content":[{"text":"vs ESLint + Prettier:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"10-100x faster performance (Rust vs JavaScript)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Single tool instead of two","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Zero configuration needed","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Auto-fixes on save by default","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Built-in TypeScript strict mode","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"vs Biome alone:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"200+ preconfigured rules","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Framework-specific presets (React, Next.js, Vue, Svelte)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"AI editor integration (Cursor, Claude Code, Copilot)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Git hook integrations","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Migration tooling","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"When to Use This Skill","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"✅ Ideal Projects","type":"text"}]},{"type":"paragraph","content":[{"text":"Use Ultracite when:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Starting a new JavaScript/TypeScript project","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Building with React, Next.js, Vue, Svelte, or other modern frameworks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Working in monorepos (Turborepo, Nx, Lerna)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Teams want consistent formatting without bikeshedding","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Performance is critical (large codebases, CI/CD optimization)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Migrating from ESLint + Prettier to a faster solution","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Using AI coding assistants (Cursor, Claude Code, Windsurf)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"TypeScript projects requiring strict type safety","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Projects with accessibility requirements (ARIA, semantic HTML)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"⚠️ Consider Alternatives When","type":"text"}]},{"type":"paragraph","content":[{"text":"Limited framework support:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Need Angular/Ember-specific rules (Biome support is basic)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Require advanced CSS linting (Stylelint still recommended)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Specialized requirements:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Need specific ESLint plugins not replicated in Biome","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Require property ordering in CSS (Stylelint feature)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Team has extensive custom ESLint configurations","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Legacy projects:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Large codebases with custom ESLint rules (migration effort required)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Projects with extensive Prettier customization","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For detailed limitations and workarounds, see","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"references/limitations-and-workarounds.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Interactive Components","type":"text"}]},{"type":"paragraph","content":[{"text":"This skill provides interactive commands and autonomous agents for streamlined workflows:","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Commands","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"/ultracite:doctor","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Validate project setup, check for v6→v7 preset paths, detect conflicts","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"/ultracite:migrate","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Interactive migration wizard (ESLint/Prettier → Ultracite, v6→v7 upgrade)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Agents","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"config-validator","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Analyze biome.jsonc for syntax, preset paths, rule conflicts, performance","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"migration-assistant","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Guide ESLint/Prettier migrations with rule mapping and gap analysis","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"See README.md for complete interactive features documentation.","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Choosing a Provider","type":"text"}]},{"type":"paragraph","content":[{"text":"Ultracite v7 supports three linting providers. Choose based on your needs:","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"🚀 Biome (Default) - ","type":"text"},{"text":"Recommended for most projects","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Speed","type":"text","marks":[{"type":"strong"}]},{"text":": Fastest (10-100x faster than ESLint)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Setup","type":"text","marks":[{"type":"strong"}]},{"text":": Zero-config with 200+ preset rules","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Best for","type":"text","marks":[{"type":"strong"}]},{"text":": New projects, TypeScript-first development, performance-critical builds","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Limitations","type":"text","marks":[{"type":"strong"}]},{"text":": Fewer rules than ESLint, basic CSS/SCSS support","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"🔧 ESLint + Prettier + Stylelint - ","type":"text"},{"text":"Recommended for maximum compatibility","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Speed","type":"text","marks":[{"type":"strong"}]},{"text":": Slower but mature ecosystem","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Setup","type":"text","marks":[{"type":"strong"}]},{"text":": Requires more configuration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Best for","type":"text","marks":[{"type":"strong"}]},{"text":": Projects with existing ESLint plugins, advanced CSS/SCSS linting needs","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Limitations","type":"text","marks":[{"type":"strong"}]},{"text":": JavaScript-based (slower), requires multiple tools","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"⚡ Oxlint + Oxfmt - ","type":"text"},{"text":"Recommended for maximum speed","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Speed","type":"text","marks":[{"type":"strong"}]},{"text":": Fastest linting (even faster than Biome for linting only)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Setup","type":"text","marks":[{"type":"strong"}]},{"text":": Type-aware linting with TypeScript integration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Best for","type":"text","marks":[{"type":"strong"}]},{"text":": Large TypeScript codebases, type-safety-critical projects","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Limitations","type":"text","marks":[{"type":"strong"}]},{"text":": Newer ecosystem, fewer rules than ESLint","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Provider selection","type":"text","marks":[{"type":"strong"}]},{"text":" during init:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bun x ultracite init --linter biome # Default\nbun x ultracite init --linter eslint # ESLint + Prettier + Stylelint\nbun x ultracite init --linter oxlint # Oxlint + Oxfmt","type":"text"}]},{"type":"paragraph","content":[{"text":"Load provider-specific documentation","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Biome: ","type":"text"},{"text":"references/provider-biome.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ESLint: ","type":"text"},{"text":"references/provider-eslint.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Oxlint: ","type":"text"},{"text":"references/provider-oxlint.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Version Migration Guide","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Upgrading from v6 to v7","type":"text"}]},{"type":"paragraph","content":[{"text":"Breaking Change","type":"text","marks":[{"type":"strong"}]},{"text":": Preset paths have changed in v7.","type":"text"}]},{"type":"paragraph","content":[{"text":"v6 paths (old)","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"jsonc"},"content":[{"text":"{\n \"extends\": [\"ultracite/core\", \"ultracite/react\"]\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"v7 paths (new)","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"jsonc"},"content":[{"text":"{\n \"extends\": [\"ultracite/biome/core\", \"ultracite/biome/react\"]\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Migration steps","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update ","type":"text"},{"text":"ultracite","type":"text","marks":[{"type":"code_inline"}]},{"text":" package: ","type":"text"},{"text":"bun update ultracite","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update preset paths in ","type":"text"},{"text":"biome.jsonc","type":"text","marks":[{"type":"code_inline"}]},{"text":" (add ","type":"text"},{"text":"/biome/","type":"text","marks":[{"type":"code_inline"}]},{"text":" segment)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run ","type":"text"},{"text":"npx ultracite doctor","type":"text","marks":[{"type":"code_inline"}]},{"text":" to validate configuration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Test linting: ","type":"text"},{"text":"npx ultracite check .","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"New v7 features","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Multi-provider support (Biome, ESLint, Oxlint)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MCP server integration for AI assistants","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"AI hooks (auto-format after AI edits)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Type-aware linting (Oxlint)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ultracite doctor","type":"text","marks":[{"type":"code_inline"}]},{"text":" diagnostics command","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Load full v7 migration guide","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"references/v7-migration.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Upgrading from v5 to v6","type":"text"}]},{"type":"paragraph","content":[{"text":"Key Change","type":"text","marks":[{"type":"strong"}]},{"text":": Framework-specific presets introduced.","type":"text"}]},{"type":"paragraph","content":[{"text":"v5 approach (old)","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"jsonc"},"content":[{"text":"{\n \"extends\": [\"ultracite/core\"]\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"v6 approach (new)","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"jsonc"},"content":[{"text":"{\n \"extends\": [\"ultracite/core\", \"ultracite/react\"] // Framework preset\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Load full v6 migration guide","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"references/v6-migration.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Project Suitability Assessment","type":"text"}]},{"type":"paragraph","content":[{"text":"When this skill is invoked, scan the project and assess:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check existing tooling:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Check for ESLint\nls -la .eslintrc* eslint.config.* package.json | grep eslint\n\n# Check for Prettier\nls -la .prettierrc* prettier.config.* package.json | grep prettier\n\n# Check for Biome\nls -la biome.json* package.json | grep biome","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Identify framework:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check ","type":"text"},{"text":"package.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" for ","type":"text"},{"text":"react","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"next","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"vue","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"svelte","type":"text","marks":[{"type":"code_inline"}]},{"text":", etc.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Recommend appropriate preset","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Assess project size:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Large projects (1000+ files) benefit most from Rust performance","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Small projects may not notice speed difference","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check TypeScript config:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"tsconfig.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" exists, note that Ultracite requires ","type":"text"},{"text":"strictNullChecks: true","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Warn if disabled (will generate many warnings)","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Recommend or warn:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"✅ RECOMMENDED: This TypeScript + React project is ideal for Ultracite\n- 500+ files will benefit from Rust performance\n- React preset available\n- Can replace existing ESLint + Prettier setup\n\n⚠️ CONSIDER: This project uses advanced ESLint plugins\n- Custom rule: eslint-plugin-custom-security\n- May need to retain ESLint for these specific rules\n- Could use Ultracite for formatting only","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Installation & Setup","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Prerequisites","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Node.js v14.18+ (v18+ recommended)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Package manager: Bun (preferred), npm, pnpm, or yarn","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"package.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" file in project root","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Quick Start (Interactive)","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Using Bun (preferred for speed)\nbun x ultracite init\n\n# With provider selection (v7+)\nbun x ultracite init --linter biome # Default, fastest\nbun x ultracite init --linter eslint # ESLint + Prettier + Stylelint\nbun x ultracite init --linter oxlint # Oxlint + Oxfmt (type-aware)\n\n# Using npm\nnpx ultracite init\n\n# Using pnpm\npnpm dlx ultracite init\n\n# Using yarn\nyarn dlx ultracite init","type":"text"}]},{"type":"paragraph","content":[{"text":"The interactive setup will:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prompt for provider selection (Biome, ESLint, Oxlint) - ","type":"text"},{"text":"v7+ only","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Install Ultracite and provider dependencies","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prompt for framework selection (React, Next.js, Vue, etc.)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ask about editor setup (VS Code, Cursor, etc.)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Offer AI agent rules installation (Cursor, Claude Code, Copilot)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prompt for Git hook integration (Husky, Lefthook, lint-staged)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Offer to migrate from existing tools (ESLint, Prettier)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create/merge configuration file (","type":"text"},{"text":"biome.jsonc","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".eslintrc.js","type":"text","marks":[{"type":"code_inline"}]},{"text":", etc.)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update ","type":"text"},{"text":".vscode/settings.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" for editor integration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Enable ","type":"text"},{"text":"strictNullChecks","type":"text","marks":[{"type":"code_inline"}]},{"text":" in ","type":"text"},{"text":"tsconfig.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" (if TypeScript)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Non-Interactive Setup (CI/Automation)","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Auto-detect settings, skip prompts\nbunx ultracite init --quiet\n\n# Specify options explicitly (v7+)\nbunx ultracite init \\\n --linter biome \\\n --pm bun \\\n --frameworks react,next \\\n --editors vscode \\\n --agents cursor,claude \\\n --integrations husky \\\n --migrate eslint,prettier \\\n --quiet","type":"text"}]},{"type":"paragraph","content":[{"text":"Available flags:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"--linter","type":"text","marks":[{"type":"code_inline"}]},{"text":": Provider selection (biome, eslint, oxlint) - ","type":"text"},{"text":"v7+ only","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"--pm","type":"text","marks":[{"type":"code_inline"}]},{"text":": Package manager (bun, npm, pnpm, yarn)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"--frameworks","type":"text","marks":[{"type":"code_inline"}]},{"text":": react, next, solid, vue, qwik, angular, remix, svelte","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"--editors","type":"text","marks":[{"type":"code_inline"}]},{"text":": vscode, zed","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"--agents","type":"text","marks":[{"type":"code_inline"}]},{"text":": cursor, claude, cline, copilot, windsurf, etc.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"--integrations","type":"text","marks":[{"type":"code_inline"}]},{"text":": husky, lefthook, lint-staged","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"--migrate","type":"text","marks":[{"type":"code_inline"}]},{"text":": eslint, prettier, biome","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"--quiet","type":"text","marks":[{"type":"code_inline"}]},{"text":": Skip all prompts (auto-enabled when ","type":"text"},{"text":"CI=true","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Manual Setup (Advanced)","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# 1. Install dependencies\nbun add -D ultracite @biomejs/biome\n\n# 2. Create biome.jsonc\ncat > biome.jsonc \u003c\u003c 'EOF'\n{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\"]\n}\nEOF\n\n# 3. Create VS Code settings\nmkdir -p .vscode\ncat > .vscode/settings.json \u003c\u003c 'EOF'\n{\n \"editor.defaultFormatter\": \"biomejs.biome\",\n \"editor.formatOnSave\": true,\n \"editor.codeActionsOnSave\": {\n \"quickfix.biome\": \"explicit\",\n \"source.organizeImports.biome\": \"explicit\"\n }\n}\nEOF\n\n# 4. Enable TypeScript strict mode\n# Add to tsconfig.json:\n{\n \"compilerOptions\": {\n \"strictNullChecks\": true\n }\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Verify Installation","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Check installation\nbunx ultracite doctor\n\n# Expected output:\n# ✔ Biome is installed\n# ✔ Configuration file found: biome.jsonc\n# ✔ Editor integration configured\n# ✔ TypeScript strict mode enabled","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Configuration","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Basic Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"File structure:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"project-root/\n├── biome.jsonc # Main configuration\n├── .vscode/settings.json # VS Code integration\n├── tsconfig.json # TypeScript config (strictNullChecks required)\n└── package.json","type":"text"}]},{"type":"paragraph","content":[{"text":"Minimal biome.jsonc:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"jsonc"},"content":[{"text":"{\n \"$schema\": \"https://biomejs.dev/schemas/2.3.8/schema.json\",\n \"extends\": [\"ultracite/core\"],\n\n // Optional: Add framework preset\n // \"extends\": [\"ultracite/core\", \"ultracite/react\"],\n\n // Optional: Customize rules\n \"linter\": {\n \"rules\": {\n \"suspicious\": {\n \"noConsoleLog\": \"off\" // Disable specific rule\n }\n }\n },\n\n // Optional: Exclude files\n \"files\": {\n \"ignore\": [\"dist\", \"build\", \"coverage\", \"**/*.generated.ts\"]\n }\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Framework Presets","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ultracite/react","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": React Hooks, JSX a11y, component best practices","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ultracite/nextjs","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": React + Next.js App Router, image optimization, document structure","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ultracite/vue","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": Vue 3 Composition API, template syntax, reactivity","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ultracite/svelte","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": Svelte 4/5 syntax, reactive declarations","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Usage","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"jsonc"},"content":[{"text":"{\n \"extends\": [\"ultracite/core\", \"ultracite/react\"]\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Core Preset","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"ultracite/core","type":"text","marks":[{"type":"code_inline"}]},{"text":" preset includes ","type":"text"},{"text":"200+ rules","type":"text","marks":[{"type":"strong"}]},{"text":" across 7 categories:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Accessibility","type":"text","marks":[{"type":"strong"}]},{"text":": ARIA validation, semantic HTML, keyboard navigation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Correctness","type":"text","marks":[{"type":"strong"}]},{"text":": Type safety, unused code removal, exhaustive dependencies","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Performance","type":"text","marks":[{"type":"strong"}]},{"text":": Code optimization, barrel file warnings","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Security","type":"text","marks":[{"type":"strong"}]},{"text":": Prevents ","type":"text"},{"text":"eval()","type":"text","marks":[{"type":"code_inline"}]},{"text":", XSS risks, unsafe patterns","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Style","type":"text","marks":[{"type":"strong"}]},{"text":": Consistent patterns, ","type":"text"},{"text":"const","type":"text","marks":[{"type":"code_inline"}]},{"text":" preference, import organization","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Suspicious","type":"text","marks":[{"type":"strong"}]},{"text":": Catches loose equality, debugger statements, typos","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Complexity","type":"text","marks":[{"type":"strong"}]},{"text":": Cognitive complexity limits","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Formatting defaults","type":"text","marks":[{"type":"strong"}]},{"text":": 2 spaces, 80 chars/line, LF endings, single quotes","type":"text"}]},{"type":"paragraph","content":[{"text":"For detailed framework presets, rule descriptions, and advanced configuration, see","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"references/configuration-guide.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Usage","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"IDE Integration (Recommended)","type":"text"}]},{"type":"paragraph","content":[{"text":"VS Code Setup:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Install Biome extension: ","type":"text"},{"text":"biomejs.biome","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verify ","type":"text"},{"text":".vscode/settings.json","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"editor.defaultFormatter\": \"biomejs.biome\",\n \"editor.formatOnSave\": true,\n \"editor.codeActionsOnSave\": {\n \"quickfix.biome\": \"explicit\",\n \"source.organizeImports.biome\": \"explicit\"\n }\n}","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Disable conflicting extensions (ESLint, Prettier)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Features:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Auto-format on save","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Auto-fix on save (removes unused imports, fixes order, applies strict equality)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Format on paste","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Problems panel for unfixable issues","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Quick fixes via lightbulb indicators","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"CLI Usage","type":"text"}]},{"type":"paragraph","content":[{"text":"Check code (lint only)","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bunx ultracite check\nbunx ultracite check src/\nbunx ultracite check --diagnostic-level error # Only errors","type":"text"}]},{"type":"paragraph","content":[{"text":"Fix code (auto-fix)","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bunx ultracite check --write\nbunx ultracite check --write src/","type":"text"}]},{"type":"paragraph","content":[{"text":"Format code (format only)","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bunx ultracite format --write\nbunx ultracite format --write src/","type":"text"}]},{"type":"paragraph","content":[{"text":"Package.json scripts","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"scripts\": {\n \"lint\": \"ultracite check\",\n \"lint:fix\": \"ultracite check --write\",\n \"format\": \"ultracite format --write\"\n }\n}","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Git Hook Integrations","type":"text"}]},{"type":"paragraph","content":[{"text":"Ultracite auto-detects and integrates with:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Husky","type":"text","marks":[{"type":"strong"}]},{"text":": Node.js-based hook manager","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Lefthook","type":"text","marks":[{"type":"strong"}]},{"text":": Fast Go-based hook manager","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"lint-staged","type":"text","marks":[{"type":"strong"}]},{"text":": Runs linters on staged files only","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Quick setup","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Husky\nbunx ultracite init --integrations husky\n\n# Lefthook\nbunx ultracite init --integrations lefthook\n\n# lint-staged\nbunx ultracite init --integrations lint-staged","type":"text"}]},{"type":"paragraph","content":[{"text":"Example ","type":"text","marks":[{"type":"strong"}]},{"text":".husky/pre-commit","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"#!/usr/bin/env sh\n. \"$(dirname -- \"$0\")/_/husky.sh\"\n\nultracite check --staged --write","type":"text"}]},{"type":"paragraph","content":[{"text":"For complete Git hook setup guides (Husky, Lefthook, lint-staged), see","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"references/git-hooks-setup.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"AI Editor Rules","type":"text"}]},{"type":"paragraph","content":[{"text":"Ultracite generates AI editor rules that teach AI assistants about your linting/formatting standards.","type":"text"}]},{"type":"paragraph","content":[{"text":"Supported editors:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cursor (","type":"text"},{"text":".cursorrules","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Claude Code (","type":"text"},{"text":".windsurfrules","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GitHub Copilot (","type":"text"},{"text":".github/copilot-instructions.md","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Continue.dev (","type":"text"},{"text":".continuerules","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Codeium (","type":"text"},{"text":".codeiumrules","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Zed (","type":"text"},{"text":".zedrules","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Generate rules","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bunx ultracite generate-ai-rules\nbunx ultracite generate-ai-rules --all # All editors\nbunx ultracite generate-ai-rules --editor=cursor # Specific editor","type":"text"}]},{"type":"paragraph","content":[{"text":"For complete AI editor integration guide and customization, see","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"references/ai-editor-integration.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Monorepo Support","type":"text"}]},{"type":"paragraph","content":[{"text":"Ultracite optimizes for monorepos with:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Shared base configurations","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Package-specific overrides","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Turborepo/Nx caching integration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Performance optimization for large workspaces","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example monorepo structure","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"monorepo/\n├── biome.json # Shared base config\n├── apps/\n│ └── web/\n│ └── biome.json # Next.js-specific overrides\n└── packages/\n └── ui/\n └── biome.json # React-specific overrides","type":"text"}]},{"type":"paragraph","content":[{"text":"For complete monorepo setup, Turborepo/Nx integration, and performance tips, see","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"references/monorepo-configuration.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Migration from ESLint/Prettier/Biome","type":"text"}]},{"type":"paragraph","content":[{"text":"Automatic migration","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bunx ultracite migrate eslint\nbunx ultracite migrate prettier\nbunx ultracite migrate biome","type":"text"}]},{"type":"paragraph","content":[{"text":"Manual migration:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Analyze current configuration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Map rules to Biome equivalents","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create ","type":"text"},{"text":"biome.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" with equivalent rules","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update package.json scripts","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Remove old dependencies","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Test thoroughly","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For complete migration guides with detailed rule mappings, see","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"references/migration-guides.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Known Limitations","type":"text"}]},{"type":"paragraph","content":[{"text":"CSS/SCSS","type":"text","marks":[{"type":"strong"}]},{"text":": Biome does not lint CSS. Workaround: Use Stylelint ","type":"text"},{"text":"Framework gaps","type":"text","marks":[{"type":"strong"}]},{"text":": Limited Angular/Astro support. Workaround: Use ","type":"text"},{"text":"ultracite/core","type":"text","marks":[{"type":"code_inline"}]},{"text":" + manual rules ","type":"text"},{"text":"ESLint plugins","type":"text","marks":[{"type":"strong"}]},{"text":": Many ESLint plugins have no Biome equivalent. Workaround: Run ESLint alongside Ultracite for specific plugins ","type":"text"},{"text":"File types","type":"text","marks":[{"type":"strong"}]},{"text":": No Markdown, YAML, HTML linting. Workaround: Use dedicated tools (markdownlint, yamllint, htmlhint)","type":"text"}]},{"type":"paragraph","content":[{"text":"For complete list of limitations and detailed workarounds, see","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"references/limitations-and-workarounds.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Troubleshooting","type":"text"}]},{"type":"paragraph","content":[{"text":"Common issues:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"VS Code not formatting on save → Install Biome extension, configure settings","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ESLint conflicts → Disable ESLint or run selectively","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Parse errors → Configure JSX support in ","type":"text"},{"text":"biome.json","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pre-commit hooks failing → Use ","type":"text"},{"text":"bunx","type":"text","marks":[{"type":"code_inline"}]},{"text":" instead of global install","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CI failures → Pin Bun/Node versions, increase memory limit","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For complete troubleshooting guide, see","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"references/troubleshooting.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Templates & Scripts","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Initial Setup Script","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"scripts/install-ultracite.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":" for automated setup.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Migration Script","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"scripts/migrate-to-ultracite.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":" for ESLint/Prettier migration.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Example Configurations","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory for:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"configuration-guide.md","type":"text","marks":[{"type":"code_inline"}]},{"text":": Framework presets and rule details","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"git-hooks-setup.md","type":"text","marks":[{"type":"code_inline"}]},{"text":": Husky, Lefthook, lint-staged setup","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ai-editor-integration.md","type":"text","marks":[{"type":"code_inline"}]},{"text":": Cursor, Claude Code, Copilot rules","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"monorepo-configuration.md","type":"text","marks":[{"type":"code_inline"}]},{"text":": Turborepo, Nx, pnpm workspaces","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"migration-guides.md","type":"text","marks":[{"type":"code_inline"}]},{"text":": ESLint, Prettier, Biome migration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"troubleshooting.md","type":"text","marks":[{"type":"code_inline"}]},{"text":": Common issues and solutions","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"limitations-and-workarounds.md","type":"text","marks":[{"type":"code_inline"}]},{"text":": Known gaps and fixes","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Package Versions","type":"text"}]},{"type":"paragraph","content":[{"text":"Current versions (verified 2025-11-27):","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ultracite","type":"text","marks":[{"type":"code_inline"}]},{"text":": latest","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"@biomejs/biome","type":"text","marks":[{"type":"code_inline"}]},{"text":": >=1.9.0","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Check for updates:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"npm view ultracite version\nnpm view @biomejs/biome version","type":"text"}]},{"type":"paragraph","content":[{"text":"Update:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bun update ultracite @biomejs/biome","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Resources","type":"text"}]},{"type":"paragraph","content":[{"text":"Official Documentation:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"https://www.ultracite.ai/introduction","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"https://www.ultracite.ai/setup","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"https://www.ultracite.ai/configuration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"https://biomejs.dev/","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Examples:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"https://www.ultracite.ai/examples","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Troubleshooting:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"https://www.ultracite.ai/troubleshooting","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"https://www.ultracite.ai/faq","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Community:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GitHub Issues: https://github.com/ultracite/ultracite","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Biome Discord: https://discord.gg/biome","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"When to Load References","type":"text"}]},{"type":"paragraph","content":[{"text":"Load reference files on-demand based on user questions or task requirements:","type":"text"}]},{"type":"paragraph","content":[{"text":"references/provider-biome.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": When user asks about:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Biome provider specifics","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Biome-only configuration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Biome performance optimization","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Biome preset paths (v7: ","type":"text"},{"text":"ultracite/biome/*","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Biome rule customization","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"references/provider-eslint.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": When user asks about:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ESLint provider setup","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ESLint + Prettier + Stylelint integration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ESLint plugin configuration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ESLint migration to Ultracite","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Advanced CSS/SCSS linting","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"references/provider-oxlint.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": When user asks about:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Oxlint provider setup","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Type-aware linting features","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Oxlint performance benefits","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Oxlint vs Biome comparison","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"TypeScript integration","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"references/v6-migration.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": When user asks about:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Upgrading from v5 to v6","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Framework preset introduction","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"v6 configuration changes","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"v6 breaking changes","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"references/v7-migration.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": When user asks about:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Upgrading from v6 to v7","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Preset path migration (","type":"text"},{"text":"ultracite/core","type":"text","marks":[{"type":"code_inline"}]},{"text":" → ","type":"text"},{"text":"ultracite/biome/core","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Multi-provider setup","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"v7 breaking changes","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ultracite doctor","type":"text","marks":[{"type":"code_inline"}]},{"text":" command","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"references/mcp-integration.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": When user asks about:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MCP server setup","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"AI assistant integration via MCP","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Model Context Protocol","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MCP server configuration","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"references/ai-hooks.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": When user asks about:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"AI hooks setup (distinct from AI rules)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Auto-format after AI edits","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Editor hook configuration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Post-edit formatting automation","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"references/configuration-guide.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": When user asks about:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Framework presets (React, Next.js, Vue, Svelte)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Core preset rules (200+ rules breakdown)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Rule customization methods","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"File exclusion patterns","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Advanced configuration","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"references/git-hooks-setup.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": When user asks about:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pre-commit hooks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Husky integration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Lefthook integration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"lint-staged setup","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CI/CD integration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Hook troubleshooting","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"references/ai-editor-integration.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": When user asks about:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"AI editor rules generation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cursor integration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Claude Code integration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GitHub Copilot setup","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Custom AI rules","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Editor-specific setup","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"references/monorepo-configuration.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": When user asks about:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Monorepo setup","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Turborepo integration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Nx integration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Package-specific overrides","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Workspace configuration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Performance optimization","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"references/migration-guides.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": When user asks about:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ESLint migration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prettier migration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Biome migration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Rule mapping","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Migration checklist","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Post-migration steps","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"references/troubleshooting.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": When user asks about:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"VS Code issues","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ESLint/Prettier conflicts","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Parse errors","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pre-commit hook failures","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CI failures","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"TypeScript strictness errors","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Installation issues","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Performance problems","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"references/limitations-and-workarounds.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": When user asks about:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CSS linting","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Framework support gaps","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ESLint plugin ecosystem","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"File type support","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Editor integration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Migration limitations","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Secure Installation","type":"text"}]},{"type":"paragraph","content":[{"text":"When installing linting/formatting packages, follow supply chain security best practices:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Block post-install scripts","type":"text","marks":[{"type":"strong"}]},{"text":" — ","type":"text"},{"text":"npm config set ignore-scripts true","type":"text","marks":[{"type":"code_inline"}]},{"text":" (or Bun: disabled by default)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cooldown period","type":"text","marks":[{"type":"strong"}]},{"text":" — Wait 7 days for new package versions to be vetted by the community","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Audit before installing","type":"text","marks":[{"type":"strong"}]},{"text":" — Run ","type":"text"},{"text":"socket package score npm \u003cpkg>","type":"text","marks":[{"type":"code_inline"}]},{"text":" or use ","type":"text"},{"text":"socket npm install \u003cpkg>","type":"text","marks":[{"type":"code_inline"}]},{"text":" to check packages","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Load the ","type":"text"},{"text":"dependency-upgrade","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Summary","type":"text"}]},{"type":"paragraph","content":[{"text":"Ultracite provides a unified linting and formatting solution with multi-provider support:","type":"text"}]},{"type":"paragraph","content":[{"text":"✅ ","type":"text"},{"text":"Use when:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Starting new projects","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Building with React/Next/Vue/Svelte","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Working in monorepos","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Want consistent formatting without configuration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Performance matters (Biome/Oxlint providers)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Need ESLint compatibility (ESLint provider)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Using AI coding assistants","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Require type-aware linting (Oxlint)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"⚠️ ","type":"text"},{"text":"Consider alternatives when:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Need specific ESLint plugins not supported by any provider","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Advanced CSS linting required (though ESLint provider includes Stylelint)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Legacy framework support needed","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Key advantages:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Multi-provider","type":"text","marks":[{"type":"strong"}]},{"text":": Choose Biome (fastest), ESLint (most compatible), or Oxlint (type-aware)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Version 7","type":"text","marks":[{"type":"strong"}]},{"text":": Preset path migration, MCP server, AI hooks, multi-provider architecture","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Version 6","type":"text","marks":[{"type":"strong"}]},{"text":": Framework-specific presets (React, Next.js, Vue, Svelte, etc.)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"10-100x faster than traditional ESLint + Prettier (Biome/Oxlint)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Zero configuration (200+ rules preconfigured for Biome)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Framework-specific presets","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"AI editor integration + AI hooks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Git hook support","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"TypeScript strict mode enforced","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Installation:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bun x ultracite init --linter biome # Default (v7+)\nbun x ultracite init --linter eslint # ESLint provider (v7+)\nbun x ultracite init --linter oxlint # Oxlint provider (v7+)","type":"text"}]},{"type":"paragraph","content":[{"text":"Most common workflow:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Install with ","type":"text"},{"text":"bun x ultracite init","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Select framework preset (React, Next.js, etc.)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Choose Git hook integration (Husky, Lefthook, lint-staged)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Enable AI editor rules (Cursor, Claude Code, Copilot)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Optionally migrate from ESLint/Prettier","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Code with auto-formatting on save","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Commit with pre-commit hooks ensuring quality","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Remember:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Always check for existing Git hook managers before installing","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Assess project suitability (scan for ESLint/Prettier/frameworks)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Recommend or warn based on project characteristics","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Enable ","type":"text"},{"text":"strictNullChecks","type":"text","marks":[{"type":"code_inline"}]},{"text":" in TypeScript projects","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use framework-specific presets for best results","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Load reference files on-demand based on user questions","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"ultracite","author":"@skillopedia","source":{"stars":162,"repo_name":"claude-skills","origin_url":"https://github.com/secondsky/claude-skills/blob/HEAD/plugins/ultracite/skills/ultracite/SKILL.md","repo_owner":"secondsky","body_sha256":"8e69bf77a28ab24bb5c8e00f9d7cab80c7723370e2d500966759a1c5998eaa64","cluster_key":"a74cc05247354cf08941a3e0fd4f7c3f263cd2cfaff2a23f92906152b59b9d07","clean_bundle":{"format":"clean-skill-bundle-v1","source":"secondsky/claude-skills/plugins/ultracite/skills/ultracite/SKILL.md","attachments":[{"id":"4666e2e3-8bdd-55e0-8ad7-ca7ca84e015a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/4666e2e3-8bdd-55e0-8ad7-ca7ca84e015a/attachment.md","path":"agents/config-validator.md","size":10618,"sha256":"96fcaf2a85198cba8e7f8073fa083a83eb27cae0d467c6e157c38426fe7f11d8","contentType":"text/markdown; charset=utf-8"},{"id":"ad86a8a9-42f3-5938-beb1-5704c60568da","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/ad86a8a9-42f3-5938-beb1-5704c60568da/attachment.md","path":"agents/migration-assistant.md","size":19531,"sha256":"0214ee6aa0876438c5d5acde9456e50deaa2b62dfa3fa7e4cc81442f18ed1b19","contentType":"text/markdown; charset=utf-8"},{"id":"e4df8c9e-e42f-56eb-a5ca-7279f3ceb72b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/e4df8c9e-e42f-56eb-a5ca-7279f3ceb72b/attachment.md","path":"commands/doctor.md","size":5973,"sha256":"cff6eca6ee4c041b93dfba3eb3f6734a61a8b268e90a00eed42cae208a6aaeaf","contentType":"text/markdown; charset=utf-8"},{"id":"cd46d418-c5ce-5bc5-a212-e640b016b25d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/cd46d418-c5ce-5bc5-a212-e640b016b25d/attachment.md","path":"commands/migrate.md","size":11886,"sha256":"c532b0acb157a089a7c3ca652da9510a7e5db6e9e9a05ed3e5ad5a9121bc6828","contentType":"text/markdown; charset=utf-8"},{"id":"715022e7-fe3e-5af1-ad0e-37c126fc8cfe","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/715022e7-fe3e-5af1-ad0e-37c126fc8cfe/attachment.md","path":"references/ai-editor-integration.md","size":10603,"sha256":"60d57cd5dc00bf6350975e9c330748aabedb6c938553d2e8dc774152c1b2fbd4","contentType":"text/markdown; charset=utf-8"},{"id":"bda1f854-d934-59fb-b321-e8c8130751c8","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/bda1f854-d934-59fb-b321-e8c8130751c8/attachment.md","path":"references/ai-hooks.md","size":10252,"sha256":"16963f1ac2a9aa5f9df88c9b0836a9187a5a7bd0500167d6c506d0f6055f9fb5","contentType":"text/markdown; charset=utf-8"},{"id":"8fdf7754-44dc-5dfd-ba8a-14ee074b4fa6","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/8fdf7754-44dc-5dfd-ba8a-14ee074b4fa6/attachment.example","path":"references/biome.jsonc.monorepo.example","size":2257,"sha256":"4a7f1d1b361edffb4835e143969145c6cbd300a0faff61fb5f91dabe8d327bf2","contentType":"text/plain; charset=utf-8"},{"id":"d8f6092b-4400-594b-aa17-fc2c1d6eb4f2","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d8f6092b-4400-594b-aa17-fc2c1d6eb4f2/attachment.example","path":"references/biome.jsonc.nextjs.example","size":1403,"sha256":"768ba3b41006d07912be06db822a52e07a2931488597acd4f57b1b48652a74cd","contentType":"text/plain; charset=utf-8"},{"id":"5a96b7e0-be37-57ff-8fb9-d2a767a3562a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/5a96b7e0-be37-57ff-8fb9-d2a767a3562a/attachment.example","path":"references/biome.jsonc.react.example","size":1244,"sha256":"cf98afc1d9387987fcb3261925f3cc4dd6748dfa5bae9172db0726ba39d0dd6c","contentType":"text/plain; charset=utf-8"},{"id":"5aa427b2-4fd1-579c-92b3-6e293337df03","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/5aa427b2-4fd1-579c-92b3-6e293337df03/attachment.example","path":"references/biome.jsonc.svelte.example","size":1230,"sha256":"21ca9f34a9ec7096b4f482600ccebc08ab19a8925134c03db3dd73466d4180f7","contentType":"text/plain; charset=utf-8"},{"id":"4a5fd831-e4e2-56c7-8e14-265c29c868f6","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/4a5fd831-e4e2-56c7-8e14-265c29c868f6/attachment.example","path":"references/biome.jsonc.vue.example","size":1066,"sha256":"85675c086597b1c914de3b2eb6fbfa3ea37fab3c8c41074314c8c88e67295fdb","contentType":"text/plain; charset=utf-8"},{"id":"5eb3b2d2-6fbb-543e-8866-208e442a45b3","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/5eb3b2d2-6fbb-543e-8866-208e442a45b3/attachment.md","path":"references/configuration-guide.md","size":10362,"sha256":"f85e69365c6e31c56f612fd8a8007636c0a058210374693b3d471acf394fa209","contentType":"text/markdown; charset=utf-8"},{"id":"c2aaab55-20ab-5a05-ac56-85f1bf9e10f1","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/c2aaab55-20ab-5a05-ac56-85f1bf9e10f1/attachment.md","path":"references/git-hooks-setup.md","size":8615,"sha256":"6aecb947e6111f6eb8a1fda0f506d13af9e69172f82e5c517c48fbcb6e5ca354","contentType":"text/markdown; charset=utf-8"},{"id":"91629bb5-802f-54f2-ab5c-cdd124859228","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/91629bb5-802f-54f2-ab5c-cdd124859228/attachment.example","path":"references/lefthook.yml.example","size":693,"sha256":"e5a3c7b6ac52ea3ac155d3c9e031d694b126f019d55a1826e57b8f218cd2f078","contentType":"text/plain; charset=utf-8"},{"id":"93709adc-6506-5b2f-8ceb-43542ab9f64a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/93709adc-6506-5b2f-8ceb-43542ab9f64a/attachment.md","path":"references/limitations-and-workarounds.md","size":11773,"sha256":"41223e38a79841064d910c0fceb19f7cb780da29e70faa6af30a9dedc7bc38c3","contentType":"text/markdown; charset=utf-8"},{"id":"5fbb396e-3ece-53e5-add4-eccc17ac8515","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/5fbb396e-3ece-53e5-add4-eccc17ac8515/attachment.example","path":"references/lint-staged.config.example","size":950,"sha256":"210cf422db447f589c8e223318ed8d9874e375d356a6029250078c50f6bd0da2","contentType":"text/plain; charset=utf-8"},{"id":"22acd41d-ad15-5902-b8bd-4bb1530a387b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/22acd41d-ad15-5902-b8bd-4bb1530a387b/attachment.md","path":"references/mcp-integration.md","size":9193,"sha256":"f1f9e81cfa93b78d99834bffbf3005915f5d23c7cc9f74926d4744028bf19b65","contentType":"text/markdown; charset=utf-8"},{"id":"a235be53-03fa-5922-be82-3cdc965e71b6","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a235be53-03fa-5922-be82-3cdc965e71b6/attachment.md","path":"references/migration-guides.md","size":10193,"sha256":"bd4517098b6649b5ff3091d3587f7f06e69f98fbc186b9d50a7a9f766da505e1","contentType":"text/markdown; charset=utf-8"},{"id":"a1f9c954-8a9d-543a-bc58-b2f70e525b0d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a1f9c954-8a9d-543a-bc58-b2f70e525b0d/attachment.md","path":"references/monorepo-configuration.md","size":10951,"sha256":"5a78d5ad5d7cda79c265288646061a25ee584d09561cc2235303300c778c9950","contentType":"text/markdown; charset=utf-8"},{"id":"eb72bb02-51b5-5164-90f1-dba1cff2c662","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/eb72bb02-51b5-5164-90f1-dba1cff2c662/attachment.md","path":"references/provider-biome.md","size":5744,"sha256":"a8da3c51992056d9788702185ff0fb75fb3a8cc374b73f70e829cbc339e4eb68","contentType":"text/markdown; charset=utf-8"},{"id":"36ce05a4-531e-5fe7-8635-8133ca556317","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/36ce05a4-531e-5fe7-8635-8133ca556317/attachment.md","path":"references/provider-eslint.md","size":6843,"sha256":"6d7bf9f20f8a6e35eada8b972666db453e48c3532a1c59cf5905c813a48ea76f","contentType":"text/markdown; charset=utf-8"},{"id":"41e394ce-80e4-541c-8dd8-b818af0da620","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/41e394ce-80e4-541c-8dd8-b818af0da620/attachment.md","path":"references/provider-oxlint.md","size":8061,"sha256":"e610b70d98428e5342a44a52e9f317b080b3fe861d0c682369e3890f77ef4479","contentType":"text/markdown; charset=utf-8"},{"id":"81ef8fc3-c4da-5877-a2db-72fe937b7c5c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/81ef8fc3-c4da-5877-a2db-72fe937b7c5c/attachment.md","path":"references/troubleshooting.md","size":10927,"sha256":"45275b1fc37b7ddb01347f1f973ce4250e9fdeb6df7f569b694f93aa5a10d4a0","contentType":"text/markdown; charset=utf-8"},{"id":"16ba18cf-4f9f-5a5e-93a9-bbd9c0ff7075","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/16ba18cf-4f9f-5a5e-93a9-bbd9c0ff7075/attachment.md","path":"references/v6-migration.md","size":7267,"sha256":"c0b9ee3578bd6815c2894d77941e45a3478f7c71425232a102cb32ca1e703b8d","contentType":"text/markdown; charset=utf-8"},{"id":"7ee4dbbc-4225-5882-92c2-2e7ff00420a8","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7ee4dbbc-4225-5882-92c2-2e7ff00420a8/attachment.md","path":"references/v7-migration.md","size":10431,"sha256":"db2f46383425184347fca515916d8af812526116190dfc1be5c0eb57c8e5e390","contentType":"text/markdown; charset=utf-8"},{"id":"1635f1f9-d7a6-56b8-9d3f-16b763a46ca3","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/1635f1f9-d7a6-56b8-9d3f-16b763a46ca3/attachment.sh","path":"scripts/install-ultracite.sh","size":6466,"sha256":"06d87e65cea80e2cd3b5bc13cbbadba30cbc70410a21a1d7b69258978eddf49b","contentType":"application/x-sh; charset=utf-8"},{"id":"b59ccb0c-6096-57ce-9c91-109d323f0c37","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/b59ccb0c-6096-57ce-9c91-109d323f0c37/attachment.sh","path":"scripts/migrate-to-ultracite.sh","size":9915,"sha256":"29d6ef618374e332d27fd47abfa9d6477972c944ffcfe339d473f42b23ebeaff","contentType":"application/x-sh; charset=utf-8"}],"bundle_sha256":"0d4969af11178cbc3ed415aedc0b064ea1dfd3ff260dfdb800ee8ecf49ef18d6","attachment_count":27,"text_attachments":20,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":7,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"plugins/ultracite/skills/ultracite/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"security","category_label":"Security"},"exact_dupes_collapsed_into_this":0},"license":"MIT","version":"v1","category":"security","metadata":{"runtime":"Node.js v14.18+ (v18+ recommended)","version":"2.0.0","keywords":["ultracite","biome","linting","formatting","code quality","eslint replacement","prettier replacement","typescript strict mode","rust linter","fast formatter","auto-fix","git hooks","pre-commit","husky","lefthook","lint-staged","react linting","nextjs linting","vue linting","svelte linting","monorepo linting","turborepo","AI coding rules","cursor rules","claude code rules","copilot instructions","accessibility linting","security linting","performance linting","jsx linting","hooks linting","migration from eslint","migration from prettier","biome.jsonc","zero config","code formatting","import sorting","unused imports","strict equality","type safety","oxlint","oxfmt","eslint integration","multi-provider","provider selection","mcp server","ai hooks","type-aware linting","ultracite doctor","programmatic usage","v6 upgrade","v7 upgrade","preset migration"],"dependencies":{"eslint":">=8.0.0 (when using ESLint provider)","oxlint":">=0.1.0 (when using Oxlint provider)","ultracite":"latest","@biomejs/biome":">=1.9.0"},"package_managers":["bun (preferred)","npm","pnpm","yarn"],"editors_supported":["VS Code (Biome extension)","Cursor","Claude Code","Zed","Cline","Windsurf"],"git_hook_managers":["husky","lefthook","lint-staged"],"frameworks_supported":["React","Next.js","Vue","Svelte","Solid","Angular","Remix","Qwik","Astro"]},"import_tag":"clean-skills-v1","description":"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."}},"renderedAt":1782980866961}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.