Feature Flags

ESLint ships experimental and future breaking changes behind feature flags to let users opt-in to behavior they want. Flags are used in these situations:

1. When a feature is experimental and not ready to be enabled for everyone.
2. When a feature is a breaking change that will be formally merged in the next major release, but users may opt-in to that behavior prior to the next major release.

Flag Prefixes

The prefix of a flag indicates its status:

• unstable_ indicates that the feature is experimental and the implementation may change before the feature is stabilized. This is a “use at your own risk” feature.
• v##_ indicates that the feature is stabilized and will be available in the next major release. For example, v10_some_feature indicates that this is a breaking change that will be formally released in ESLint v10.0.0. These flags are removed each major release.

A feature may move from unstable to stable without a major release if it is a non-breaking change.

Active Flags

The following flags are currently available for use in ESLint.

Flag	Description
test_only	Used only for testing.
unstable_config_lookup_from_file	Look up `eslint.config.js` from the file being linted.
unstable_ts_config	Enable TypeScript configuration files.

Inactive Flags

The following flags were once used but are no longer active.

Flag	Description
test_only_old	Used only for testing.

How to Use Feature Flags

Because feature flags are strictly opt-in, you need to manually enable the flags that you want.

Enable Feature Flags with the CLI

On the command line, you can specify feature flags using the --flag option. You can specify as many flags as you’d like:

npx eslint --flag flag_one --flag flag_two file.js
1

Enable Feature Flags with the API

When using the API, you can pass a flags array to both the ESLint and Linter classes:

const { ESLint, Linter } = require("eslint");

const eslint = new ESLint({
    flags: ["flag_one", "flag_two"]
});

const linter = new Linter({
    flags: ["flag_one", "flag_two"]
});
1
2
3
4
5
6
7
8
9

Enable Feature Flags in VS Code

To enable flags in the VS Code ESLint Extension for the editor, specify the flags you’d like in the eslint.options setting in your settings.json file:

{
  "eslint.options": { "flags": ["flag_one", "flag_two"] }
}
1
2
3

To enable flags in the VS Code ESLint Extension for a lint task, specify the eslint.lintTask.options settings:

{
  "eslint.lintTask.options": "--flag flag_one --flag flag_two ."
}
1
2
3