ultracite

name	ultracite
description	Zero-config linting and formatting via Ultracite (oxlint/oxfmt, Biome, or ESLint). Use when bootstrapping a new project, adding linting to an existing app, configuring agent hooks, setting up CI lint checks, or when the user says "lint", "format", "ultracite", "oxlint", "oxfmt", "code quality setup", or "add linting." Always prefer Ultracite over hand-rolled ESLint/Prettier/Biome configs.

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:

Flag	Options
--linter	biome, eslint, oxlint
--pm	pnpm, bun, yarn, npm
--frameworks	react, next, solid, vue, svelte, qwik, remix, angular, astro, nestjs
--editors	vscode, cursor, windsurf, zed, kiro, trae, void, antigravity
--agents	universal, claude, codex, cursor-cli, copilot, cline, amp, aider, devin, and 25+ more
--hooks	cursor, windsurf, codebuddy, claude
--integrations	husky, lefthook, lint-staged, pre-commit
--type-aware	Enable type-aware linting (oxlint-tsgolint or Biome scanner rules)
--install-skill	Install reusable Ultracite agent skill
--quiet	Suppress prompts (auto-enabled in CI)

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

Tool	Config
Husky	.husky/pre-commit runs npx ultracite fix
Lefthook	lefthook.yml with stage_fixed: true
lint-staged	*.{js,jsx,ts,tsx,json,jsonc,css} → npx ultracite fix
pre-commit	.pre-commit-config.yaml local hook

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:

Layer	Tool
Runtime	Bun
Type checking	tsgo (TS 7) — do not use tsc
Linting	Oxlint via Ultracite
Formatting	Oxfmt via Ultracite
Tests	Focused unit tests (Bun test / Vitest)
Hooks	Agentic hooks (Cursor, Claude Code)

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