---

name: oxlint-setup description: Use when adding oxlint (the Rust-based linter) to a JS/TS project as a fast pre-commit and CI gate. Covers config in .oxlintrc.json, the errors-must-be-zero rule, autofix, and how it coexists with a type gate rather than replacing it.

Oxlint as a Fast CI Gate

When to trigger

A project where ESLint is too slow to run on every commit, or you want a sub-second lint pass that gates pushes without waiting on a full typecheck.

Why oxlint

Oxlint is written in Rust and runs a large rule set in a fraction of ESLint's time, so it is cheap enough to run on every commit. It does not replace your type gate; it catches a different, faster class of issue (unused vars, obvious mistakes, correctness lints).

Setup

1. Add the scripts:

   { "scripts": { "lint:ox": "oxlint", "lint:ox:fix": "oxlint --fix" } }
   

2. Configure rules in .oxlintrc.json at the repo root. Start from the recommended set and tighten from there.

3. Adopt the rule: pnpm lint:ox must report zero errors before a commit. Warnings are advisory, not blocking, so the signal-to-noise stays high and a red error always means something.

4. Run pnpm lint:ox:fix to auto-apply the safe fixes, then review the diff before committing.

Where it sits in the pipeline

• Pre-commit / local: lint:ox (fast, zero errors).
• Deploy gate: the type check (tsc --noEmit or the native preview) plus the build. Oxlint is not a type checker; keep both.

Pitfalls

• Treating warnings as blocking floods the output and trains everyone to ignore it. Keep errors blocking and warnings advisory.
• Expecting oxlint to catch type errors: it does not do full type analysis. A green oxlint run is not a green build. Keep the type gate.
• Running --fix and committing without reading the diff can apply an unwanted change. Review autofixes.
• A missing or empty .oxlintrc.json runs a minimal rule set and quietly under-lints. Commit an explicit config.