Oxc Workflow

Table of Contents

Here’s how I like to setup new Node.js projects, with linting and formatting using Oxc.

Oxc

I wrote about Oxc (The JavaScript Oxidation Compiler) in Next Generation Tooling for Developers. When I first wrote this article, Oxc already included a linter (oxlint, which can replace ESLint), but the formatter was not available yet. Since then, VoidZero has continued the development of Oxc, not only launching Vite+ but also launching a formatter (oxfmt, which can replace Prettier). With the combination of oxlint and oxfmt, I now have a modern-alternative to ESLint + Prettier. Note that this might not work as a replacement in all existing projects that rely on specific configurations of ESLint and/or Prettier. However, for new Node.js projects, I will strive to go with the Oxc stack.

Why Oxc instead of ESLint + Prettier?

The two main reasons I prefer Oxc is speed and ease of configuration; as I have explained in Next Generation Tooling for Developers, the Rust-based tools are noticeably faster. In addition, they have a more modern design with more intutive configuration. In particular, ESLint has become a nightmare to configure after the breaking changes in ESLint v9.

Guide

One-time run

These tools can be run in a project without being installed or added to package.json using npx commands:

npx oxlint@latest

npx oxfmt@latest

Install Oxc tools in NPM project

For consistent usage in an npm project, Oxc packages can be added as devDependencies.

npm install --save-dev oxlint@latest oxlint-tsgolint@latest oxfmt@latest

Initialize configuration for oxlint

Quote

Configuration files for Oxlint are written in JSON, with support for comments (JSONC). Oxlint will automatically search for files named .oxlintrc.json and automatically use those. But you can name the file anything when you are using the --config CLI option.

Configuring Oxlint | The JavaScript Oxidation Compiler

Use the --init option to initialize a .oxlintrc.json file:

## If installed
./node_modules/.bin/oxlint --init

## If not installed
npx oxlint@latest --init

Initialize configuration for oxfmt

Quote

By default, oxfmt automatically tries to find the nearest .oxfmtrc.json or .oxfmtrc.jsonc file from current working directory. If not found, default configuration is used.

Also you can specify your config file by -c yourconfig.jsonc flag.

Almost all format options are compatible with Prettier’s options. So you may finish your setup by just renaming .prettierrc.json to .oxfmtrc.jsonc.

Formatter | The JavaScript Oxidation Compiler

Use the --init option to initialize a .oxfmtrc.json file:

## If installed
./node_modules/.bin/oxfmt --init

## If not installed
npx oxfmt@latest --init

A previous version of this article, suggested to use prettier-init (before oxfmt had the --init option).

The prettier-init tool can be used to help bootstrap configuration:

npx prettier-init@latest
mv ".prettierrc.json" ".oxfmtrc.json"

`scripts` block in `package.json`

For easy and consistent usage across the project, add to the scripts block in package.json:

  "scripts": {
    "lint": "oxlint --type-aware --type-check .",
    "lint:fix": "oxlint --type-aware --type-check . --fix",
    "lint:fix-all": "oxlint --type-aware --type-check . --fix --fix-suggestions --fix-dangerously",
    "format": "oxfmt .",
    "format:check": "oxfmt . --check"
  },

Commit and push all changed and added files

Commit and push all relevant files that were changed or added:

git add ".oxfmtrc.json" ".oxlintrc.json" "package.json" "package-lock.json"
git commit -s
git push

Featured image by Gabriel Heinzer on Unsplash.