Oxlint Configuration File

This configuration is aligned with ESLint v8's configuration schema (eslintrc.json).

Usage: oxlint -c oxlintrc.json

Example

.oxlintrc.json

{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "plugins": ["import", "typescript", "unicorn"],
  "env": {
    "browser": true
  },
  "globals": {
    "foo": "readonly"
  },
  "settings": {
    "react": {
      "version": "18.2.0"
    },
    "custom": {
      "option": true
    }
  },
  "rules": {
    "eqeqeq": "warn",
    "import/no-cycle": "error",
    "react/self-closing-comp": [
      "error",
      {
        "html": false
      }
    ]
  },
  "overrides": [
    {
      "files": ["*.test.ts", "*.spec.ts"],
      "rules": {
        "@typescript-eslint/no-explicit-any": "off"
      }
    }
  ]
}

oxlint.config.ts

import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: ["import", "typescript", "unicorn"],
  env: {
    browser: true,
  },
  globals: {
    foo: "readonly",
  },
  settings: {
    react: {
      version: "18.2.0",
    },
    custom: { option: true },
  },
  rules: {
    eqeqeq: "warn",
    "import/no-cycle": "error",
    "react/self-closing-comp": ["error", { html: false }],
  },
  overrides: [
    {
      files: ["*.test.ts", "*.spec.ts"],
      rules: {
        "@typescript-eslint/no-explicit-any": "off",
      },
    },
  ],
});

$schema

type: string

Schema URI for editor tooling.

categories

type: object

Configure an entire category of rules all at once.

Rules enabled or disabled this way will be overwritten by individual rules in the rules field.

Example

{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "categories": {
    "correctness": "warn"
  },
  "rules": {
    "eslint/no-unused-vars": "error"
  }
}

categories.correctness

categories.nursery

categories.pedantic

categories.perf

categories.restriction

categories.style

categories.suspicious

env

type: Record<string, boolean>

Predefine global variables.

Environments specify what global variables are predefined. Available environments:

• amd - require() and define() globals.
• applescript - AppleScript globals.
• astro - Astro globals.
• atomtest - Atom test globals.
• audioworklet - AudioWorklet globals.
• browser - browser globals.
• builtin - Latest ECMAScript globals, equivalent to es2026.
• commonjs - CommonJS globals and scoping.
• embertest - Ember test globals.
• es2015 - ECMAScript 2015 globals.
• es2016 - ECMAScript 2016 globals.
• es2017 - ECMAScript 2017 globals.
• es2018 - ECMAScript 2018 globals.
• es2019 - ECMAScript 2019 globals.
• es2020 - ECMAScript 2020 globals.
• es2021 - ECMAScript 2021 globals.
• es2022 - ECMAScript 2022 globals.
• es2023 - ECMAScript 2023 globals.
• es2024 - ECMAScript 2024 globals.
• es2025 - ECMAScript 2025 globals.
• es2026 - ECMAScript 2026 globals.
• es6 - ECMAScript 6 globals except modules.
• greasemonkey - GreaseMonkey globals.
• jasmine - Jasmine globals.
• jest - Jest globals.
• jquery - jQuery globals.
• meteor - Meteor globals.
• mocha - Mocha globals.
• mongo - MongoDB globals.
• nashorn - Java 8 Nashorn globals.
• node - Node.js globals and scoping.
• phantomjs - PhantomJS globals.
• prototypejs - Prototype.js globals.
• protractor - Protractor globals.
• qunit - QUnit globals.
• serviceworker - Service Worker globals.
• shared-node-browser - Node.js and Browser common globals.
• shelljs - ShellJS globals.
• svelte - Svelte globals.
• vitest - Vitest globals.
• vue - Vue globals.
• webextensions - WebExtensions globals.
• worker - Web Workers globals.

extends

type: string[]

Paths of configuration files that this configuration file extends (inherits from). The files are resolved relative to the location of the configuration file that contains the extends property. The configuration files are merged from the first to the last, with the last file overriding the previous ones.

globals

type: Record<string, string>

Add or remove global variables.

For each global variable, set the corresponding value equal to "writable" to allow the variable to be overwritten or "readonly" to disallow overwriting.

Globals can be disabled by setting their value to "off". For example, in an environment where most Es2015 globals are available but Promise is unavailable, you might use this config:

{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "env": {
    "es6": true
  },
  "globals": {
    "Promise": "off"
  }
}

You may also use "readable" or false to represent "readonly", and "writeable" or true to represent "writable".

ignorePatterns

type: string[]

default: []

Globs to ignore during linting. These are resolved from the configuration file path.

jsPlugins

type: array

JS plugins, allows usage of ESLint plugins with Oxlint.

Read more about JS plugins in the docs.

Note: JS plugins are in alpha and not subject to semver.

Examples:

Basic usage with a local plugin path.

{
  "jsPlugins": ["./custom-plugin.js"],
  "rules": {
    "custom/rule-name": "warn"
  }
}

Basic usage with a TypeScript plugin and a local plugin path.

TypeScript plugin files are supported in the following environments:

• Deno and Bun: TypeScript files are supported natively.
• Node.js >=22.18.0 and Node.js ^20.19.0: TypeScript files are supported natively with built-in type-stripping enabled by default.

For older Node.js versions, TypeScript plugins are not supported. Please use JavaScript plugins or upgrade your Node version.

{
  "jsPlugins": ["./custom-plugin.ts"],
  "rules": {
    "custom/rule-name": "warn"
  }
}

Using a built-in Rust plugin alongside a JS plugin with the same name by giving the JS plugin an alias.

{
  "plugins": ["import"],
  "jsPlugins": [{ "name": "import-js", "specifier": "eslint-plugin-import" }],
  "rules": {
    "import/no-cycle": "error",
    "import-js/no-unresolved": "warn"
  }
}

jsPlugins[n]

type: object | string

jsPlugins[n].name

type: string

Custom name/alias for the plugin.

Note: The following plugin names are reserved because they are implemented natively in Rust within oxlint and cannot be used for JS plugins:

• react (includes react-hooks)
• unicorn
• typescript (includes @typescript-eslint)
• oxc
• import (includes import-x)
• jsdoc
• jest
• vitest
• jsx-a11y
• nextjs
• react-perf
• promise
• node
• vue
• eslint

If you need to use the JavaScript version of any of these plugins, provide a custom alias to avoid conflicts.

jsPlugins[n].specifier

type: string

Path or package name of the plugin

options

type: object

Options for the linter.

options.denyWarnings

type: boolean

Ensure warnings produce a non-zero exit code.

Equivalent to passing --deny-warnings on the CLI.

options.maxWarnings

type: integer

Specify a warning threshold. Exits with an error status if warnings exceed this value.

Equivalent to passing --max-warnings on the CLI.

options.reportUnusedDisableDirectives

type: "allow" | "off" | "warn" | "error" | "deny" | integer

Report unused disable directives (e.g. // oxlint-disable-line or // eslint-disable-line).

Equivalent to passing --report-unused-disable-directives-severity on the CLI. CLI flags take precedence over this value when both are set. Only supported in the root configuration file.

options.typeAware

type: boolean

Enable rules that require type information.

Equivalent to passing --type-aware on the CLI.

Note that this requires the oxlint-tsgolint package to be installed.

options.typeCheck

type: boolean

Enable experimental type checking (includes TypeScript compiler diagnostics).

Equivalent to passing --type-check on the CLI.

Note that this requires the oxlint-tsgolint package to be installed.

overrides

type: array

overrides[n]

type: object

overrides[n].env

type: object

Environments enable and disable collections of global variables.

overrides[n].files

type: string[]

A set of glob patterns.

overrides[n].globals

type: object

Enabled or disabled specific global variables.

overrides[n].jsPlugins

type: array

JS plugins for this override, allows usage of ESLint plugins with Oxlint.

Read more about JS plugins in the docs.

Note: JS plugins are in alpha and not subject to semver.

overrides[n].jsPlugins[n]

type: object | string

overrides[n].jsPlugins[n].name

type: string

Custom name/alias for the plugin.

Note: The following plugin names are reserved because they are implemented natively in Rust within oxlint and cannot be used for JS plugins:

• react (includes react-hooks)
• unicorn
• typescript (includes @typescript-eslint)
• oxc
• import (includes import-x)
• jsdoc
• jest
• vitest
• jsx-a11y
• nextjs
• react-perf
• promise
• node
• vue
• eslint

If you need to use the JavaScript version of any of these plugins, provide a custom alias to avoid conflicts.

overrides[n].jsPlugins[n].specifier

type: string

Path or package name of the plugin

overrides[n].plugins

type: array

default: null

Optionally change what plugins are enabled for this override. When omitted, the base config's plugins are used.

overrides[n].plugins[n]

type: "eslint" | "react" | "unicorn" | "typescript" | "oxc" | "import" | "jsdoc" | "jest" | "vitest" | "jsx-a11y" | "nextjs" | "react-perf" | "promise" | "node" | "vue"

overrides[n].rules

type: object

See Oxlint Rules

plugins

type: array

default: null

Enabled built-in plugins for Oxlint. You can view the list of available plugins on the website.

NOTE: Setting the plugins field will overwrite the base set of plugins. The plugins array should reflect all of the plugins you want to use.

plugins[n]

type: "eslint" | "react" | "unicorn" | "typescript" | "oxc" | "import" | "jsdoc" | "jest" | "vitest" | "jsx-a11y" | "nextjs" | "react-perf" | "promise" | "node" | "vue"

rules

type: object

See Oxlint Rules

settings

type: object

Configure the behavior of linter plugins.

Here's an example if you're using Next.js in a monorepo:

{
  "settings": {
    "next": {
      "rootDir": "apps/dashboard/"
    },
    "react": {
      "linkComponents": [
        {
          "name": "Link",
          "linkAttribute": "to"
        }
      ]
    },
    "jsx-a11y": {
      "components": {
        "Link": "a",
        "Button": "button"
      }
    }
  }
}

settings.jest

type: object

Configure Jest plugin rules.

See eslint-plugin-jest's configuration for a full reference.

settings.jest.version

type: integer

default: null

Jest version — accepts a number (29) or a semver string ("29.1.0" or "v29.1.0"), storing only the major version.

WARNING

Using this config will override the no-deprecated-functions' config set.

settings.jsdoc

type: object

settings.jsdoc.augmentsExtendsReplacesDocs

type: boolean

default: false

Only for require-(yields|returns|description|example|param|throws) rule

settings.jsdoc.exemptDestructuredRootsFromChecks

type: boolean

default: false

Only for require-param-type and require-param-description rule

settings.jsdoc.ignoreInternal

type: boolean

default: false

For all rules but NOT apply to empty-tags rule

settings.jsdoc.ignorePrivate

type: boolean

default: false

For all rules but NOT apply to check-access and empty-tags rule

settings.jsdoc.ignoreReplacesDocs

type: boolean

default: true

Only for require-(yields|returns|description|example|param|throws) rule

settings.jsdoc.implementsReplacesDocs

type: boolean

default: false

Only for require-(yields|returns|description|example|param|throws) rule

settings.jsdoc.overrideReplacesDocs

type: boolean

default: true

Only for require-(yields|returns|description|example|param|throws) rule

settings.jsdoc.tagNamePreference

type: object

default: {}

settings.jsx-a11y

type: object

Configure JSX A11y plugin rules.

See eslint-plugin-jsx-a11y's configuration for a full reference.

settings.jsx-a11y.attributes

type: Record<string, array>

default: {}

Map of attribute names to their DOM equivalents. This is useful for non-React frameworks that use different attribute names.

Example:

{
  "settings": {
    "jsx-a11y": {
      "attributes": {
        "for": ["htmlFor", "for"]
      }
    }
  }
}

settings.jsx-a11y.components

type: Record<string, string>

default: {}

To have your custom components be checked as DOM elements, you can provide a mapping of your component names to the DOM element name.

Example:

{
  "settings": {
    "jsx-a11y": {
      "components": {
        "Link": "a",
        "IconButton": "button"
      }
    }
  }
}

settings.jsx-a11y.polymorphicPropName

type: string

An optional setting that define the prop your code uses to create polymorphic components. This setting will be used to determine the element type in rules that require semantic context.

For example, if you set the polymorphicPropName to as, then this element:

<Box as="h3">Hello</Box>

Will be treated as an h3. If not set, this component will be treated as a Box.

settings.next

type: object

Configure Next.js plugin rules.

settings.next.rootDir

type: array | string

settings.next.rootDir[n]

type: string

settings.react

type: object

Configure React plugin rules.

Derived from eslint-plugin-react

settings.react.componentWrapperFunctions

type: string[]

default: []

Functions that wrap React components and should be treated as HOCs.

Example:

{
  "settings": {
    "react": {
      "componentWrapperFunctions": ["observer", "withRouter"],
    },
  },
}

settings.react.formComponents

type: array

default: []

Components used as alternatives to <form> for forms, such as <Formik>.

Example:

{
  "settings": {
    "react": {
      "formComponents": [
        "CustomForm",
        // OtherForm is considered a form component and has an endpoint attribute
        { "name": "OtherForm", "formAttribute": "endpoint" },
        // allows specifying multiple properties if necessary
        { "name": "Form", "formAttribute": ["registerEndpoint", "loginEndpoint"] },
      ],
    },
  },
}

settings.react.formComponents[n]

type: object | string

settings.react.formComponents[n].attribute

type: string

settings.react.formComponents[n].name

type: string

settings.react.linkComponents

type: array

default: []

Components used as alternatives to <a> for linking, such as <Link>.

Example:

{
  "settings": {
    "react": {
      "linkComponents": [
        "HyperLink",
        // Use `linkAttribute` for components that use a different prop name
        // than `href`.
        { "name": "MyLink", "linkAttribute": "to" },
        // allows specifying multiple properties if necessary
        { "name": "Link", "linkAttribute": ["to", "href"] },
      ],
    },
  },
}

settings.react.linkComponents[n]

type: object | string

settings.react.linkComponents[n].attribute

type: string

settings.react.linkComponents[n].name

type: string

settings.react.version

type: string

default: null

React version to use for version-specific rules.

Accepts semver versions (e.g., "18.2.0", "17.0").

Example:

{
  "settings": {
    "react": {
      "version": "18.2.0",
    },
  },
}

settings.vitest

type: object

Configure Vitest plugin rules.

See eslint-plugin-vitest's configuration for a full reference.

settings.vitest.typecheck

type: boolean

default: false

Whether to enable typecheck mode for Vitest rules. When enabled, some rules will skip certain checks for describe blocks to accommodate TypeScript type checking scenarios.