Oxlint Configuration File

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

Usage: oxlint -c oxlintrc.json --import-plugin

NOTE

Only the .json format is supported. You can use comments in configuration files.

Example

.oxlintrc.json

{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "plugins": ["import", "typescript", "unicorn"],
  "env": {
    "browser": true
  },
  "globals": {
    "foo": "readonly"
  },
  "settings": {},
  "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 | null

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. See ESLint's list of environments for what environments are available and what each one provides.

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 | null

JS plugins.

Note: JS plugins are experimental and not subject to semver. They are not supported in language server at present.

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
• oxc
• import (includes import-x)
• jsdoc
• jest
• vitest
• jsx-a11y
• nextjs
• react-perf
• promise
• node
• regex
• 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

overrides

type: array

overrides[n]

type: object

overrides[n].env

type: object | null

Environments enable and disable collections of global variables.

overrides[n].files

type: string[]

A set of glob patterns.

overrides[n].globals

type: object | null

Enabled or disabled specific global variables.

overrides[n].jsPlugins

type: array | null

JS plugins for this override.

Note: JS plugins are experimental and not subject to semver. They are not supported in language server at present.

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
• oxc
• import (includes import-x)
• jsdoc
• jest
• vitest
• jsx-a11y
• nextjs
• react-perf
• promise
• node
• regex
• 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 | null

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: string

overrides[n].rules

type: object

See Oxlint Rules

plugins

type: array | null

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: string

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.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 | null

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.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 | null

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.