Migrate OxlintSAFE

⚓ A collection of high-performance JavaScript tools.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: migrate-oxlint
description: Guide for migrating a project from ESLint to Oxlint. Use when asked to migrate, convert, or switch a JavaScript/TypeScript project's linter from ESLint to Oxlint.
---

This skill guides you through migrating a JavaScript/TypeScript project from ESLint to [Oxlint](https://oxc.rs/docs/guide/usage/linter/).

## Overview

Oxlint is a high-performance linter that implements many popular ESLint rules natively in Rust. It can be used alongside ESLint or as a full replacement.

An official migration tool is available, and will be used by this skill: [`@oxlint/migrate`](https://github.com/oxc-project/oxlint-migrate)

## Step 1: Run Automated Migration

Run the migration tool in the project root:

```bash
npx @oxlint/migrate
```

This reads your ESLint flat config (`eslint.config.js` for example) and generates a `.oxlintrc.json` file from it. It will find your ESLint config file automatically in most cases.

See options below for more info.

### Key Options

| Option                      | Description                                                                                                                     |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `--type-aware`              | Include type-aware rules from `@typescript-eslint` (will require the `oxlint-tsgolint` package to be installed after migrating) |
| `--with-nursery`            | Include experimental rules still under development, may not be fully stable or consistent with ESLint equivalents               |
| `--js-plugins [bool]`       | Enable/disable ESLint plugin migration via `jsPlugins` (default: enabled)                                                       |
| `--details`                 | List rules that could not be migrated                                                                                           |
| `--replace-eslint-comments` | Convert all `// eslint-disable` comments to `// oxlint-disable`                                                                 |
| `--output-file <file>`      | Specify a different output path (default: `.oxlintrc.json`)                                                                     |

If your ESLint config is not at the default location, pass the path explicitly:

```bash
npx @oxlint/migrate ./path/to/eslint.config.js
```

## Step 2: Review Generated Config

After migration, review the generated `.oxlintrc.json`.

### Plugin Mapping

The migration tool automatically maps ESLint plugins to oxlint's built-in equivalents. The following table is for reference when reviewing the generated config:

| ESLint Plugin                                         | Oxlint Plugin Name |
| ----------------------------------------------------- | ------------------ |
| `@typescript-eslint/eslint-plugin`                    | `typescript`       |
| `eslint-plugin-react` / `eslint-plugin-react-hooks`   | `react`            |
| `eslint-plugin-import` / `eslint-plugin-import-x`     | `import`           |
| `eslint-plugin-unicorn`                               | `unicorn`          |
| `eslint-plugin-jsx-a11y` / `eslint-plugin-jsx-a11y-x` | `jsx-a11y`         |
| `eslint-plugin-react-perf`                            | `react-perf`       |
| `eslint-plugin-promise`                               | `promise`          |
| `eslint-plugin-jest`                                  | `jest`             |
| `@vitest/eslint-plugin`                               | `vitest`           |
| `eslint-plugin-jsdoc`                                 | `jsdoc`            |
| `eslint-plugin-next`                                  | `nextjs`           |
| `eslint-plugin-node`                                  | `node`             |
| `eslint-plugin-vue`                                   | `vue`              |

Default plugins (enabled when `plugins` field is omitted): `unicorn`, `typescript`, `oxc`.
Setting the `plugins` array explicitly overrides these defaults.

ESLint core rules are usable in oxlint without needing to configure a plugin in the config file.

### Rule Categories

Oxlint groups rules into categories for bulk configuration, though only `correctness` is enabled by default:

```json
{
  "categories": {
    "correctness": "error",
    "suspicious": "warn"
  }
}
```

Available categories: `correctness` (default: enabled), `suspicious`, `pedantic`, `perf`, `style`, `restriction`, `nursery`.

Individual rule settings in `rules` override category settings.

`@oxlint/migrate` will turn `correctness` off to avoid enabling additional rules that weren't enabled by your ESLint config. You can choose to enable additional categories after migration if desired.

### Check Unmigrated Rules

Run with `--details` to see which ESLint rules could not be migrated:

```bash
npx @oxlint/migrate --details
```

Review the output and decide whether to keep ESLint for those rules or not. Some rules may be mentioned in the output from `--details` as having equivalents in oxlint that were not automatically mapped by the migration tool. In those cases, consider enabling the equivalent oxlint rule manually after migration.

## Step 3: Install Oxlint

Install the core oxlint package (use `yarn install`, `pnpm install`, `vp install`, `bun install`, etc. depending on your package manager):

```bash
npm install -D oxlint
```

If you want to add the `oxlint-tsgolint` package, if you intend to use type-aware rules that require TypeScript type information:

```bash
npm install -D oxlint-tsgolint
```

No other packages besides the above are needed by default, though you will need to keep/install any additional ESLint plugins that were migrated into `jsPlugins`. Do not add `@oxlint/migrate` to the package.json, it is meant for one-off usage.

## Step 4: Handle Unsupported Features

Some features require manual attention:

- Local plugins (relative path imports): Must be migrated manually to `j

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

apps/oxfmt/test/cli/config_symlink/fixtures/.oxfmtrc.json

apps/oxfmt/test/cli/config_symlink/fixtures/sub/.oxfmtrc.json

apps/oxfmt/test/cli/ignore_symlink/fixtures/bar.js

apps/oxfmt/test/lsp/format/fixtures/config-symlink/.oxfmtrc.json

apps/oxlint/fixtures/cli/ignore_patterns_symlink/testdir/.oxlintrc.json

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Migrate Oxlint](https://modelsatlas.com/skills/oxc-project/migrate-oxlint/badge.svg)](https://modelsatlas.com/skills/oxc-project/migrate-oxlint/)

Not your listing, or something out of date? Claim or update your listing.