Skip to main content
Technology & EngineeringTesting Services30 lines

Adopt Oxlint in a JavaScript or TypeScript Codebase

Migrate an ESLint setup to Oxlint with rule-level parity checks, controlled exceptions, and equivalent CI and editor behavior.

Quick Summary8 lines
Identify the package root and pinned ESLint, TypeScript, and Node versions. Capture the CI command, files and extensions it checks, project references or TypeScript configuration, parser options, ignored patterns, custom rules, plugins, and representative editor settings. In a workspace, inspect overrides in different package directories. Record the starting warning and error policy, including whether warnings can fail the build.

## Key Points

- [Oxc ESLint migration guide](https://www.oxcjs.com/guide/usage/linter/migrate-from-eslint.html)
- [Oxlint configuration](https://oxc.rs/docs/guide/usage/linter/config.html)
skilldb get testing-services-skills/oxlintFull skill: 30 lines
Paste into your CLAUDE.md or agent config

Adopt Oxlint in a JavaScript or TypeScript Codebase

Inventory what ESLint currently enforces

Identify the package root and pinned ESLint, TypeScript, and Node versions. Capture the CI command, files and extensions it checks, project references or TypeScript configuration, parser options, ignored patterns, custom rules, plugins, and representative editor settings. In a workspace, inspect overrides in different package directories. Record the starting warning and error policy, including whether warnings can fail the build.

Create a rule coverage matrix with the old rule name, its severity, intended files, and a minimal positive or negative fixture for behavior that matters. Include an ignored generated file, an ordinary JS file, a TS file requiring type information, and any custom rules relied on by production code. Preserve this baseline while evaluating the new command.

Stage the migration

Use Oxlint's documented migration tool or configure a small package first. Pin versions and review generated files before accepting them. Check rule names, enablement, categories, severity, overrides, and ignore handling against the old configuration. Confirm resolution of project configuration from the CI working directory. If type-aware rules are needed, check the installed version's setup and run the fixture that relies on semantic information. Keep TypeScript compilation or typechecking as an independent check.

Run both linters on the same code and compare by file, location range, rule meaning, and severity. Rule names and reported spans can change even when a behavior is covered. Investigate results present only on one side instead of treating the lower count as success. Record how each significant discrepancy will be handled. Unsupported custom checks can remain in a narrow ESLint command or be replaced with a targeted test. During this comparison, preserve the old gate as the enforceable baseline.

Validate developer and CI paths

Run the candidate from a clean checkout using the normal dependency installation and lint entry point. Prove that the expected package files were selected. Introduce a deliberate violation and verify that CI fails with a useful error. Run a fixture under the old custom rule or plugin, and confirm the replacement gate still catches it. Run the formatter and linter separately to avoid treating stylistic changes as proof of lint parity.

Move the CI job and editor configuration only after documenting retained checks and reviewed differences. Keep the rollback change small enough to restore the former command and config without undoing unrelated source edits. Report runtime separately from coverage, and store the exact commands, versions, remaining exceptions, and before-and-after fixture results.

References

Install this skill directly: skilldb add testing-services-skills

Get CLI access →