Adopt Oxlint

Recently, I started exploring with oxlint, the increasingly popular JavaScript linter in the community, especially for its ability of replacing ESLint, which tends to be a performance bottleneck during CI runs for large projects.

During the integration, I am definitely impressed with the extreme performance of this Rust-based linter, but also find that the current docs of oxlint are sometimes ambiguous and example-lacking. I take the chance to write down some notes for future reference and wish it could help others who are also interested in trying new JavaScript toolings.

Installation

Well, this is not the most interesting part. Reference the installation guide and you will be good to go.

Configuration

Without any configuration, 91 rules are enabled with oxlint by default, which are marked with ✅ in rules.

Plugins

Oxlint continuously implements new rules from various existing high-quality projects in the community, such as eslint-plugin-unicorn, eslint-plugin-jest, etc. Some of the rule sets are enabled by default, like eslint-plugin-unicorn and eslint-plugin-react, while some are not, like eslint-plugin-jest and eslint-plugin-import, which require manual opt-in via options listed in enable plugins.

The OXC Rules

As a base toolchain for future JavaScript projects, Oxlint does not only copy/paste existing eslint rules, but also develops its own brand new linting rules, which are labeled with source: oxc in the rules documentation.

While these rules seem really attractive, they are not well documented in the docs yet. To figure out the behavior of a specific rule from oxc, you have to dive into the source code of oxlint. Luckily, in its codebase, oxlint provides snapshot tests for each rule, which serves as a really good reference for understanding what the rule does for our project.

Take the rule misrefactored-assign-op as an example, it is placed in the suspicious category and is not enabled by default. To figure out what it does, we could navigate to the source code of oxc, and simply search “misrefactored-assign-op” in the codebase, then we will find the snapshot file misrefactored_assign_op.snap generated by the test case of the rule, the content of which is listed below:

---
source: crates/oxc_linter/src/tester.rs
---
  ⚠ oxc(misrefactored-assign-op): Misrefactored assign op. Variable appears on both sides of an assignment operation
   ╭─[misrefactored_assign_op.tsx:1:1]
 1 │ a += a + 1;
   · ──────────
   ╰────
  help: Did you mean `a += 1`?

We can clearly see what the rule is about now, and this approach could be applied to other oxc rules as well.

The Vitest Plugin

If you use Vitest as your test runner, you will be happy when seeing that a --vitest-plugin option appears in the enable plugins section. However, besides this command line interface option, no further detailed documentation is provided on how exactly to use this plugin, especially when there’s not a single rule labeled with source: vitest showing up in the rules doc.

In fact, the rules of vitest plugin are completely documented with a label of source: jest instead, which is quite confusing if the user does not know well about the relation between vitest and jest, where the former gets many enlightenments from the latter.

So when you run oxlint with --vitest-plugin, what you need to reference with are the rules labeled with source: jest, and before enabling a rule, remember to check whether it’s also included in eslint-plugin-vitest. This seems really counter-intuitive, but it’s the current status of the documentation.

VSCode Extension

Oxlint provides an official VSCode extension to provide a better development experience, yet the default configuration file path is set to .eslinrc rather than the .oxlintrc.json mentioned in configuration file. This could complicate integration with collaborative projects, as each developer would need to configure the extension for custom settings.

Functionality and Robustness

The performance of oxlint is extraordinary, really. But during my integration, I found that its automatic fix sometimes goes wrong and completely clear a file, which is a functionality problem.

Also, when executing oxlint multiple times in a terminal, it sometimes stuck during generating the report, thus causing the entire VSCode to freeze.

Conclusion

Anyway, oxlint is still a promising project for me, and many next-generation projects are being built on top of it, such as Rolldown, the future bundler for Vite. It does have some rough edges on documentation and umbrella features, but I believe the community will help to polish it in the near future.