ultracite

What this skill does

# 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 migration, MCP server support, AI hooks
**Version 6 Changes**: Framework-specific presets introduced (React, Next.js, Vue, Svelte, etc.)

### Core Goals

1. **Lightning-Fast Performance**: Leverages Biome's Rust implementation for instant linting/formatting
2. **Zero-Config Design**: Ships with 200+ sensible defaults optimized for modern TypeScript development
3. **Simplicity & Invisibility**: Operates with minimal user interaction
4. **Type Safety**: Enforces TypeScript strict mode and comprehensive null/undefined handling
5. **Tool Compatibility**: Works alongside other development tools without conflicts

### Key Benefits vs Alternatives

**vs ESLint + Prettier:**
- 10-100x faster performance (Rust vs JavaScript)
- Single tool instead of two
- Zero configuration needed
- Auto-fixes on save by default
- Built-in TypeScript strict mode

**vs Biome alone:**
- 200+ preconfigured rules
- Framework-specific presets (React, Next.js, Vue, Svelte)
- AI editor integration (Cursor, Claude Code, Copilot)
- Git hook integrations
- Migration tooling

## When to Use This Skill

### ✅ Ideal Projects

Use Ultracite when:
- Starting a new JavaScript/TypeScript project
- Building with React, Next.js, Vue, Svelte, or other modern frameworks
- Working in monorepos (Turborepo, Nx, Lerna)
- Teams want consistent formatting without bikeshedding
- Performance is critical (large codebases, CI/CD optimization)
- Migrating from ESLint + Prettier to a faster solution
- Using AI coding assistants (Cursor, Claude Code, Windsurf)
- TypeScript projects requiring strict type safety
- Projects with accessibility requirements (ARIA, semantic HTML)

### ⚠️ Consider Alternatives When

**Limited framework support:**
- Need Angular/Ember-specific rules (Biome support is basic)
- Require advanced CSS linting (Stylelint still recommended)

**Specialized requirements:**
- Need specific ESLint plugins not replicated in Biome
- Require property ordering in CSS (Stylelint feature)
- Team has extensive custom ESLint configurations

**Legacy projects:**
- Large codebases with custom ESLint rules (migration effort required)
- Projects with extensive Prettier customization

**For detailed limitations and workarounds, see**: `references/limitations-and-workarounds.md`

## Interactive Components

This skill provides interactive commands and autonomous agents for streamlined workflows:

### Commands
- `/ultracite:doctor` - Validate project setup, check for v6→v7 preset paths, detect conflicts
- `/ultracite:migrate` - Interactive migration wizard (ESLint/Prettier → Ultracite, v6→v7 upgrade)

### Agents
- `config-validator` - Analyze biome.jsonc for syntax, preset paths, rule conflicts, performance
- `migration-assistant` - Guide ESLint/Prettier migrations with rule mapping and gap analysis

**See README.md for complete interactive features documentation.**

## Choosing a Provider

Ultracite v7 supports three linting providers. Choose based on your needs:

### 🚀 Biome (Default) - **Recommended for most projects**
- **Speed**: Fastest (10-100x faster than ESLint)
- **Setup**: Zero-config with 200+ preset rules
- **Best for**: New projects, TypeScript-first development, performance-critical builds
- **Limitations**: Fewer rules than ESLint, basic CSS/SCSS support

### 🔧 ESLint + Prettier + Stylelint - **Recommended for maximum compatibility**
- **Speed**: Slower but mature ecosystem
- **Setup**: Requires more configuration
- **Best for**: Projects with existing ESLint plugins, advanced CSS/SCSS linting needs
- **Limitations**: JavaScript-based (slower), requires multiple tools

### ⚡ Oxlint + Oxfmt - **Recommended for maximum speed**
- **Speed**: Fastest linting (even faster than Biome for linting only)
- **Setup**: Type-aware linting with TypeScript integration
- **Best for**: Large TypeScript codebases, type-safety-critical projects
- **Limitations**: Newer ecosystem, fewer rules than ESLint

**Provider selection** during init:
```bash
bun x ultracite init --linter biome   # Default
bun x ultracite init --linter eslint  # ESLint + Prettier + Stylelint
bun x ultracite init --linter oxlint  # Oxlint + Oxfmt
```

**Load provider-specific documentation**:
- Biome: `references/provider-biome.md`
- ESLint: `references/provider-eslint.md`
- Oxlint: `references/provider-oxlint.md`

## Version Migration Guide

### Upgrading from v6 to v7

**Breaking Change**: Preset paths have changed in v7.

**v6 paths (old)**:
```jsonc
{
  "extends": ["ultracite/core", "ultracite/react"]
}
```

**v7 paths (new)**:
```jsonc
{
  "extends": ["ultracite/biome/core", "ultracite/biome/react"]
}
```

**Migration steps**:
1. Update `ultracite` package: `bun update ultracite`
2. Update preset paths in `biome.jsonc` (add `/biome/` segment)
3. Run `npx ultracite doctor` to validate configuration
4. Test linting: `npx ultracite check .`

**New v7 features**:
- Multi-provider support (Biome, ESLint, Oxlint)
- MCP server integration for AI assistants
- AI hooks (auto-format after AI edits)
- Type-aware linting (Oxlint)
- `ultracite doctor` diagnostics command

**Load full v7 migration guide**: `references/v7-migration.md`

### Upgrading from v5 to v6

**Key Change**: Framework-specific presets introduced.

**v5 approach (old)**:
```jsonc
{
  "extends": ["ultracite/core"]
}
```

**v6 approach (new)**:
```jsonc
{
  "extends": ["ultracite/core", "ultracite/react"]  // Framework preset
}
```

**Load full v6 migration guide**: `references/v6-migration.md`

### Project Suitability Assessment

When this skill is invoked, scan the project and assess:

1. **Check existing tooling:**
   ```bash
   # Check for ESLint
   ls -la .eslintrc* eslint.config.* package.json | grep eslint

   # Check for Prettier
   ls -la .prettierrc* prettier.config.* package.json | grep prettier

   # Check for Biome
   ls -la biome.json* package.json | grep biome
   ```

2. **Identify framework:**
   - Check `package.json` for `react`, `next`, `vue`, `svelte`, etc.
   - Recommend appropriate preset

3. **Assess project size:**
   - Large projects (1000+ files) benefit most from Rust performance
   - Small projects may not notice speed difference

4. **Check TypeScript config:**
   - If `tsconfig.json` exists, note that Ultracite requires `strictNullChecks: true`
   - Warn if disabled (will generate many warnings)

5. **Recommend or warn:**
   ```
   ✅ RECOMMENDED: This TypeScript + React project is ideal for Ultracite
   - 500+ files will benefit from Rust performance
   - React preset available
   - Can replace existing ESLint + Prettier setup

   ⚠️ CONSIDER: This project uses advanced ESLint plugins
   - Custom rule: eslint-plugin-custom-security
   - May need to retain ESLint for these specific rules
   - Could use Ultracite for formatting only
   ```

## Installation & Setup

### Prerequisites

- Node.js v14.18+ (v18+ recommended)
- Package manager: Bun (preferred), npm, pnpm, or yarn
- `package.json` file in project root

### Quick Start (Interactive)

```bash
# Using Bun (preferred for speed)
bun x ultracite init

# With provider selection (v7+)
bun x ultracite init --linter biome   # Default, fastest
bun x ultracite init --linter eslint  # ESLint + Prettier + Stylelint
bun x ultracite init --linter oxlint  # Oxlint + Oxfmt (type-aware)

# Using npm
npx ultracite init

# Using pnpm
pnpm dlx ultracite init

# Using yarn
yarn dlx ultracite init
```