Oxlint

Use this skill when work touches Oxlint or Oxc linting: install/config, day-to-day usage, rules/plugins, type-aware linting, ESLint coexistence or migration, editors, or CI.

Workflow

1. Inspect the local Oxlint surface before changing code:

- Package versions for oxlint, optional oxlint-tsgolint, eslint-plugin-oxlint, @oxlint/migrate. - Config: prefer oxlint.config.ts / .mts with defineConfig; also accept .oxlintrc.json(c) (one type per directory). - Remaining ESLint setup, ignore files, scripts (lint / lint:fix), and editor Oxc settings. - Whether type-aware linting or JS plugins are in play.

1. For setup, how-to, progressive adoption, diagnostics loops, baselines, or troubleshooting, follow the full guide first: [usage-guide.md](references/usage-guide.md).
2. Refresh current official docs when versions differ from the snapshot or the work touches type-aware, JS plugins, or migration. Start from [source-map.md](references/source-map.md).
3. Route deeper detail to the focused references:

- Install, CLI, config shape, nested configs, ignores: [setup-cli-config.md](references/setup-cli-config.md). - Categories, plugins, rules, inline ignores, type-aware: [rules-plugins-typeaware.md](references/rules-plugins-typeaware.md). - ESLint coexistence, migration, editors, CI: [eslint-ci-editors.md](references/eslint-ci-editors.md).

1. Preserve the repository's existing lint severity and plugin choices unless the user asks to migrate or expand coverage.
2. Verify with the narrowest useful bunx oxlint / bun run lint invocation.

Core Judgment

• Default Oxlint enables only the correctness category. Turn on other categories and plugins deliberately.
• Setting plugins: [...] replaces the default plugin set. Re-list eslint, typescript, unicorn, and oxc when you still want them.
• Prefer oxlint.config.ts + defineConfig for new configs (typed, shareable via imports). Keep or use .oxlintrc.json only when the project already has it, or when using a standalone binary without a Node runtime.
• Nested configs do not auto-merge with parents — use extends (TS: imported objects; JSON: relative paths). -c/--config disables nested lookup.
• Prefer ignorePatterns in config over scattered ignore files for editor/CI consistency.
• Prefer oxlint-disable comments long-term; eslint-disable still works while migrating (respectEslintDisableDirectives default true).
• Type-aware linting needs oxlint-tsgolint + --type-aware / options.typeAware. Those options are root-only. Do not pass --tsconfig together with type-aware.
• Keep oxlint and eslint-plugin-oxlint on the same minor. Put oxlint flat configs last in ESLint so they disable overlapping rules.
• JS plugins (jsPlugins) are alpha and outside normal semver — avoid unless required.
• Vue/Svelte/Astro: Oxlint covers script blocks only, not templates.
• Do not treat Oxlint as a formatter. Formatting belongs in a separate formatter tool (for example Oxfmt or Prettier).

Verification

Prefer repository-owned commands. For meaningful Oxlint work, cover the relevant subset:

• bunx oxlint (or project lint script) on changed paths.
• bunx oxlint --fix when autofixes are expected; review remaining diagnostics.
• Type-aware: bunx oxlint --type-aware after dependents are built so .d.ts exist.
• CI-shaped run with --deny-warnings or --max-warnings when those gates are project policy.
• After ESLint coexistence changes: run oxlint && eslint and confirm no duplicate rule noise.
• Editor/LSP smoke when changing Oxc extension settings or options.typeAware.

Report which checks ran, which did not, and any package-version or type-aware assumptions that remain.