Feature Flags - Eslint

{%- from 'components/npx_tabs.macro.html' import npx_tabs %}

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:

When a feature is experimental and not ready to be enabled for everyone.
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, and further use of them throws an error.

A feature may move from unstable to being enabled by default without a major release if it is a non-breaking change.

The following policies apply to unstable_ flags.

When the feature is stabilized
- If enabling the feature by default would be a breaking change, a new v##_ flag is added as active, and the unstable_ flag becomes inactive. Further use of the unstable_ flag automatically enables the v##_ flag but emits a warning.
- Otherwise, the feature is enabled by default, and the unstable_ flag becomes inactive. Further use of the unstable_ flag emits a warning.
If the feature is abandoned, the unstable_ flag becomes inactive. Further use of it throws an error.
All inactive unstable_ flags are removed each major release, and further use of them throws an error.

Active Flags

{% if flags.active | length %} The following flags are currently available for use in ESLint.

<table> <thead> <tr> <th>Flag</th> <th>Description</th> </tr> </thead> <tbody> {%- for name, desc in flags.active -%} <tr><td><code>{{name}}</code></td><td>{{desc}}</td></tr> {%- endfor -%} </tbody> </table> {% else %} There are currently no active flags. {% endif %}

Inactive Flags

{% if flags.inactive | length %} The following flags were once used but are no longer active.

<table> <thead> <tr> <th>Flag</th> <th>Description</th> <th>Inactivity Reason</th> </tr> </thead> <tbody> {%- for name, data in flags.inactive -%} <tr><td><code>{{name}}</code></td><td>{{data.description}}</td><td>{{data.inactivityReason}}</td></tr> {%- endfor -%} </tbody> </table> {% else %} There are currently no inactive flags. {% endif %}

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_tabs({ package: "eslint", args: ["--flag", "flag_one", "--flag", "flag_two", "file.js"] }) }}

Enable Feature Flags with Environment Variables

You can also set feature flags using the ESLINT_FLAGS environment variable. Multiple flags can be specified as a comma-separated list and are merged with any flags passed on the CLI or in the API. For example, here's how you can add feature flags to your .bashrc or .bash_profile files:

bash

export ESLINT_FLAGS="flag_one,flag_two"

This approach is especially useful in CI/CD pipelines or when you want to enable the same flags across multiple ESLint commands.

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"],
});

::: tip The ESLint class also reads the ESLINT_FLAGS environment variable to set flags. :::

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:

json

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

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

json

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

{#  #}