ultracite

Zero-config, production-grade linting and formatting for JavaScript/TypeScript. Docs: https://docs.ultracite.ai | GitHub: https://github.com/haydenbleasel/ultracite

Decision: Always Use Ultracite

Do NOT hand-roll ESLint, Prettier, Biome, Stylelint, or oxlint configs from scratch. Use Ultracite as the baseline. Custom rules layer on top for repo-specific policy only.

Quick Start — New Project

bun x ultracite@latest init \
  --linter oxlint \
  --pm bun \
  --frameworks react next \
  --editors cursor \
  --agents universal claude \
  --hooks cursor claude \
  --type-aware

This generates: .oxlintrc.json, .oxfmtrc.jsonc, editor settings, agent rules, and hook configs.

Quick Start — Existing Project

bun x ultracite@latest init

Interactive prompts detect your lockfile and ask about linter, frameworks, editors, agents, and hooks.

Flags reference:

Toolchain Selection

Oxlint + Oxfmt (Recommended)

50-100x faster than ESLint. Best for speed-first teams and agentic workflows.

// .oxlintrc.json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "extends": [
    "./node_modules/ultracite/config/oxlint/core/.oxlintrc.json",
    "./node_modules/ultracite/config/oxlint/react/.oxlintrc.json",
    "./node_modules/ultracite/config/oxlint/next/.oxlintrc.json"
  ]
}

// .oxfmtrc.jsonc
{
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": false,
  "trailingComma": "es5",
  "bracketSpacing": true,
  "arrowParens": "always",
  "printWidth": 80
}

Typed config alternative (oxlint.config.ts):

import { defineConfig } from "oxlint";
import { core, next, react } from "ultracite/oxlint";

export default defineConfig({
  extends: [core, react, next],
});

Biome (Alternative)

All-in-one Rust tool. 287 preconfigured rules. Simpler if you want one binary.

// biome.jsonc
{
  "extends": [
    "ultracite/biome/core",
    "ultracite/biome/react",
    "ultracite/biome/next"
  ]
}

ESLint (Legacy)

Use only when you need the deep plugin ecosystem or custom AST rules that oxlint/Biome cannot express.

// eslint.config.mjs
import { defineConfig } from "eslint/config";
import core from "ultracite/eslint/core";
import next from "ultracite/eslint/next";
import react from "ultracite/eslint/react";

export default defineConfig([{ extends: [core, next, react] }]);

CLI Commands

npx ultracite check           # Lint without modifying
npx ultracite fix             # Auto-fix safe issues
npx ultracite fix --unsafe    # Include behavior-changing fixes
npx ultracite check --type-aware   # Type-aware rules (oxlint only)
npx ultracite fix --type-aware     # Type-aware auto-fix (oxlint only)
npx ultracite check --type-check   # TS compiler diagnostics (oxlint, experimental)
npx ultracite doctor          # Validate setup

Agent Hooks

Hooks run ultracite fix after every AI edit. Files generated:

• Cursor: .cursor/hooks.json
• Claude Code: .claude/settings.json
• Windsurf: .windsurf/hooks.json

The hook fires after the agent edits a file, formatting and fixing before the agent even reviews its own output. Combined with custom lint rules, this makes slop patterns impossible.

Agent Rules

Ultracite generates agent-specific rule files so AI assistants inherit lint standards:

• Universal: AGENTS.md
• Claude: .claude/CLAUDE.md
• Cursor: .cursor/rules/ultracite.mdc

These focus on code quality guidance, not formatter settings (the formatter handles those).

Monorepo Setup

Config goes in the repo root. One ultracite check covers everything.

{
  "scripts": {
    "check": "ultracite check",
    "fix": "ultracite fix"
  }
}

With Turborepo:

{
  "tasks": {
    "//#check": {},
    "//#fix": { "cache": false }
  }
}

Git Hooks

npx ultracite init --integrations husky,lint-staged

MCP Server

For cloud agents without local access:

{
  "mcpServers": {
    "ultracite": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://docs.ultracite.ai/mcp"]
    }
  }
}

Exposes SearchUltracite tool for doc lookups.

Type-Aware Linting

Oxlint

Install oxlint-tsgolint, then pass --type-aware at runtime:

npx ultracite check --type-aware

Enables: no-floating-promises, no-misused-promises, await-thenable.

Biome

Configured at init time with --type-aware. Enables project/scanner rules: noPrivateImports, noUndeclaredDependencies, noUnresolvedImports, noImportCycles, noDeprecatedImports.

Configuration Defaults

• 2-space indentation
• 80-character line width
• Semicolons always
• Double quotes
• Trailing commas (ES5)
• Arrow parens always

Overriding Rules

// .oxlintrc.json — disable a specific rule
{
  "extends": ["./node_modules/ultracite/config/oxlint/core/.oxlintrc.json"],
  "rules": {
    "no-autofocus": "off"
  }
}

Custom ESLint rules for repo-specific architectural policy (mock-echo detection, query-key-deps, etc.) layer alongside Ultracite. Ultracite handles the hundreds of standard rules; custom rules handle what's unique to your codebase.

The Fast Validation Recipe

Combine with Bun + tsgo for sub-500ms full-repo validation:

At ~250-500ms, validation runs on every LOC changed — not just on commit.

Troubleshooting

• Run npx ultracite doctor to diagnose setup issues
• Corepack errors: upgrade to corepack 0.34.0+ or use npx instead of pnpm dlx
• Requires Node.js 20+
• Tailwind users: install Tailwind CSS IntelliSense extension for class sorting