Ultracite

Ultracite

Zero-config linting and formatting for JS/TS projects. Supports three linter backends: Biome (recommended), ESLint + Prettier, and Oxlint + Oxfmt.

Detecting Ultracite

Check if ultracite is in package.json devDependencies. Detect the active linter by looking for:

• biome.jsonc → Biome
• eslint.config.mjs → ESLint
• oxlint.config.ts → Oxlint

CLI Commands

# Check for issues (read-only)
bunx ultracite check

# Auto-fix issues
bunx ultracite fix

# Diagnose setup problems
bunx ultracite doctor

# Initialize in a new project
bunx ultracite init

Replace bunx with npx, pnpx, or yarn dlx depending on the package manager.

check and fix accept optional file paths: bunx ultracite check src/index.ts.

Initialization

bunx ultracite init runs an interactive setup. For non-interactive (CI) use, pass flags:

bunx ultracite init \
  --pm bun \
  --linter biome \
  --editors universal \
  --agents claude copilot \
  --frameworks react next \
  --integrations husky lint-staged \
  --quiet

Flags:

• --pm — npm | yarn | pnpm | bun
• --linter — biome (recommended) | eslint | oxlint
• --editors — universal (writes .vscode/settings.json for every VS Code-based editor) | vscode | zed | cursor | windsurf | antigravity | kiro | trae | void | bob | codebuddy
• --agents — claude | codex | copilot | cline | amp | gemini | cursor-cli + 19 more
• --frameworks — react | next | solid | vue | svelte | qwik | remix | angular | astro | nestjs
• --integrations — husky | lefthook | lint-staged | pre-commit
• --hooks — Enable auto-fix hooks for supported agents/editors
• --type-aware — Enable type-aware linting (oxlint only)
• --skip-install — Skip dependency installation
• --quiet — Suppress prompts (auto-detected when CI=true)

Init creates config that extends Ultracite presets:

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

Framework presets available per linter: core, react, next, solid, vue, svelte, qwik, remix, angular, astro, nestjs.

Code Standards

When writing code in a project with Ultracite, follow these standards. For the full rules reference, see references/code-standards.md.

Key rules at a glance:

Formatting is handled by the project's configured linter/formatter. Respect the repository's existing formatter settings instead of forcing one fixed line width, quote style, or trailing comma policy.

Type safety: Use explicit types when they improve clarity. Prefer unknown over any. Use as const for immutable values and rely on type narrowing over blunt assertions.

Modern JavaScript/TypeScript: Prefer const, destructuring, optional chaining, nullish coalescing, template literals, for...of, and concise arrow functions.

Async and correctness: Always await promises in async functions. Prefer async/await over promise chains. Remove console.log, debugger, and alert from production code.

React and accessibility: Use function components, keep hooks top-level with correct deps, avoid nested component definitions, and use semantic HTML with the right labels, headings, alt text, and keyboard affordances.

Organization, security, performance, and testing: Keep functions focused, prefer early returns, avoid dangerouslySetInnerHTML and eval(), prefer specific imports and top-level regex, and keep tests free of .only and .skip.

Troubleshooting

Run bunx ultracite doctor to diagnose. It checks:

1. Linter installation (biome/eslint/oxlint binary available) 2. Config validity (extends ultracite presets correctly) 3. Ultracite in package.json dependencies 4. Conflicting tools (old .eslintrc.*, .prettierrc.* files)

Common fixes:

• Conflicting configs: Delete legacy .eslintrc.* and .prettierrc.* files after migrating to Ultracite
• Missing dependency: Run bunx ultracite init again or manually add ultracite to devDependencies
• Rules not applying: Ensure config file extends the correct presets for your framework

Ultracite Code Standards

Formatting is intentionally handled by your project's configured linter or formatter. Respect the repository's existing quote, width, semicolon, trailing comma, and line ending settings instead of forcing one global formatting style.

Core Principles

Write code that is accessible, performant, type-safe, and maintainable. Focus on clarity and explicit intent over brevity.

Type Safety & Explicitness

• Use explicit types for function parameters and return values when they enhance clarity
• Prefer unknown over any when the type is genuinely unknown
• Use const assertions (as const) for immutable values and literal types
• Leverage TypeScript's type narrowing instead of type assertions
• Use meaningful variable names instead of magic numbers — extract constants with descriptive names

Modern JavaScript/TypeScript

• Use arrow functions for callbacks and short functions
• Prefer for...of loops over .forEach() and indexed for loops
• Use optional chaining (?.) and nullish coalescing (??) for safer property access
• Prefer template literals over string concatenation
• Use destructuring for object and array assignments
• Use const by default, let only when reassignment is needed, never var

Async & Promises

• Always await promises in async functions — don't forget to use the return value
• Use async/await syntax instead of promise chains for better readability
• Handle errors appropriately in async code with try-catch blocks
• Don't use async functions as Promise executors

React & JSX

• Use function components over class components
• Call hooks at the top level only, never conditionally
• Specify all dependencies in hook dependency arrays correctly
• Use the key prop for elements in iterables (prefer unique IDs over array indices)
• Nest children between opening and closing tags instead of passing as props
• Don't define components inside other components
• Use semantic HTML and ARIA attributes for accessibility:
• Provide meaningful alt text for images
• Use proper heading hierarchy
• Add labels for form inputs
• Include keyboard event handlers alongside mouse events
• Use semantic elements (<button>, <nav>, etc.) instead of divs with roles

Error Handling & Debugging

• Remove console.log, debugger, and alert statements from production code
• Throw Error objects with descriptive messages, not strings or other values
• Use try-catch blocks meaningfully — don't catch errors just to rethrow them
• Prefer early returns over nested conditionals for error cases

Code Organization

• Keep functions focused and under reasonable cognitive complexity limits
• Extract complex conditions into well-named boolean variables
• Use early returns to reduce nesting
• Prefer simple conditionals over nested ternary operators
• Group related code together and separate concerns

Security

• Add rel="noopener" when using target="_blank" on links
• Avoid dangerouslySetInnerHTML unless absolutely necessary
• Don't use eval() or assign directly to document.cookie
• Validate and sanitize user input

Performance

• Avoid spread syntax in accumulators within loops
• Use top-level regex literals instead of creating them in loops
• Prefer specific imports over namespace imports
• Avoid barrel files (index files that re-export everything)
• Use proper image components (e.g., Next.js <Image>) over <img> tags

Framework-Specific

Next.js: Use <Image> component for images. Use next/head or the App Router metadata API for head elements. Use Server Components for async data fetching instead of async Client Components.

React 19+: Use ref as a prop instead of React.forwardRef.

Solid/Svelte/Vue/Qwik: Use class and for attributes (not className or htmlFor).

Testing

• Write assertions inside it() or test() blocks
• Avoid done callbacks in async tests — use async/await instead
• Don't use .only or .skip in committed code
• Keep test suites reasonably flat — avoid excessive describe nesting

When Your Linter Can't Help

Your configured linter or formatter will catch most mechanical issues automatically. Focus your attention on:

1. Business logic correctness 2. Meaningful naming 3. Architecture decisions 4. Edge cases 5. User experience 6. Documentation for genuinely complex logic