--- url: /docs/guide/usage/linter/config-file-reference.md --- # Oxlint Configuration File This configuration is aligned with ESLint v8's configuration schema (`eslintrc.json`). Usage: `oxlint -c oxlintrc.json` Example `.oxlintrc.json` ```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` ```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 ```json { "$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` Environments enable and disable collections of global variables. 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[]` Configurations that this configuration file extends (inherits from). In `.oxlintrc.json`, `extends` has type `string[]`. Each string is a path to a configuration file, resolved relative to the location of the configuration file that contains the `extends` property. In `oxlint.config.ts`, `extends` has type `OxlintConfig[]`. Import each configuration and pass the configuration object directly: ```ts import { defineConfig } from "oxlint"; import baseConfig from "./base-config.ts"; export default defineConfig({ extends: [baseConfig] }); ``` Configurations are merged from the first to the last, with the last configuration overriding the previous ones. ## globals type: `Record` Enabled or disabled specific global variables. 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: ```json { "$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. Patterns use gitignore-style matching, rooted at the directory containing the configuration file. Files outside that directory cannot be matched; patterns containing `..` are rejected as a configuration error. ## jsPlugins type: `array` JS plugins, allows usage of ESLint plugins with Oxlint. Read more about JS plugins in [the docs](https://oxc.rs/docs/guide/usage/linter/js-plugins.html). Note: JS plugins are in alpha and not subject to semver. Examples: Basic usage with a local plugin path. ```json { "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. ```json { "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. ```json { "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 (includes jsx-a11y-x) * 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` Oxlint config options. 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.respectEslintDisableDirectives type: `boolean` Whether oxlint should respect `eslint-disable*` and `eslint-enable*` directives in addition to its native `oxlint-*` directives. Defaults to `true`. 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` Add, remove, or otherwise reconfigure rules for specific files or groups of files. ### overrides\[n] type: `object` #### overrides\[n].env type: `object` Environments enable and disable collections of global variables. #### overrides\[n].excludeFiles type: `string[]` A list of glob patterns to exclude from this override. Files matching these patterns are not globally ignored; this override simply does not apply to them. ## Example `[ "*.generated.ts", "fixtures/**" ]` A set of glob patterns. Patterns are matched against paths relative to the configuration file's directory. #### overrides\[n].files type: `string[]` A list of glob patterns to override. ## Example `[ "*.test.ts", "*.spec.ts" ]` A set of glob patterns. Patterns are matched against paths relative to the configuration file's directory. #### 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](https://oxc.rs/docs/guide/usage/linter/js-plugins.html). 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 (includes jsx-a11y-x) * 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](https://oxc.rs/docs/guide/usage/linter/rules.html) ## plugins type: `array` default: `null` Enabled built-in plugins for Oxlint. You can view the list of available plugins on [the website](https://oxc.rs/docs/guide/usage/linter/plugins.html#supported-plugins). 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` Example `.oxlintrc.json` ```json { "$schema": "./node_modules/oxlint/configuration_schema.json", "rules": { "eqeqeq": "warn", "import/no-cycle": "error", "prefer-const": [ "error", { "ignoreReadBeforeAssign": true } ] } } ``` See [Oxlint Rules](https://oxc.rs/docs/guide/usage/linter/rules.html) for the list of rules. See [Oxlint Rules](https://oxc.rs/docs/guide/usage/linter/rules.html) ## settings type: `object` Plugin-specific configuration for both built-in and custom plugins. This includes settings for built-in plugins such as `react` and `jsdoc` as well as configuring settings for JS custom plugins loaded via `jsPlugins`. Configure the behavior of linter plugins. Here's an example if you're using Next.js in a monorepo: ```json { "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](https://github.com/jest-community/eslint-plugin-jest)'s configuration for a full reference. #### settings.jest.version type: `integer | string` 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](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y#configurations)'s configuration for a full reference. #### settings.jsx-a11y.attributes type: `Record` default: `{}` Map of attribute names to their DOM equivalents. This is useful for non-React frameworks that use different attribute names. Example: ```json { "settings": { "jsx-a11y": { "attributes": { "for": ["htmlFor", "for"] } } } } ``` #### settings.jsx-a11y.components type: `Record` 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: ```json { "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: ```jsx Hello ``` 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` The root directory of the Next.js project. This is particularly useful when you have a monorepo and your Next.js project is in a subfolder. Example: ```json { "settings": { "next": { "rootDir": "apps/dashboard/" } } } ``` ##### settings.next.rootDir\[n] type: `string` ### settings.react type: `object` Configure React plugin rules. Derived from [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react#configuration-legacy-eslintrc-) #### settings.react.componentWrapperFunctions type: `string[]` default: `[]` Functions that wrap React components and should be treated as HOCs. Example: ```jsonc { "settings": { "react": { "componentWrapperFunctions": ["observer", "withRouter"], }, }, } ``` #### settings.react.formComponents type: `array` default: `[]` Components used as alternatives to `
` for forms, such as ``. Example: ```jsonc { "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 `` for linking, such as ``. Example: ```jsonc { "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: ```jsonc { "settings": { "react": { "version": "18.2.0", }, }, } ``` ### settings.vitest type: `object` Configure Vitest plugin rules. See [eslint-plugin-vitest](https://github.com/vitest-dev/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.