feat: Allow flags to be set in ESLINT_FLAGS env variable (#19717)

nzakas · mdjermanovic · web-flow · commit d71e37f450f4 · 2025-05-15T20:16:51.000+02:00
* feat: Allow flags to be set in ESLINT_FLAGS env variable fixes #19100 * Move environment variable reading into ESLint class * Update docs/src/pages/flags.md Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> * Update tests/lib/eslint/eslint.js Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> * Update tests/lib/eslint/eslint.js Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> * Clarify flags are merged * clean up formatting * Trim environment variable before split --------- Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>
diff --git a/docs/src/pages/flags.md b/docs/src/pages/flags.md
@@ -82,6 +82,16 @@ On the command line, you can specify feature flags using the `--flag` option. Yo
     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:
@@ -98,6 +108,10 @@ const linter = new Linter({
 });
 ```
 
+::: 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:
diff --git a/lib/eslint/eslint.js b/lib/eslint/eslint.js
@@ -390,6 +390,20 @@ function getFixerForFixTypes(fix, fixTypesSet, config) {
 		originalFix(message);
 }
 
+/**
+ * Retrieves flags from the environment variable ESLINT_FLAGS.
+ * @param {string[]} flags The flags defined via the API.
+ * @returns {string[]} The merged flags to use.
+ */
+function mergeEnvironmentFlags(flags) {
+	if (!process.env.ESLINT_FLAGS) {
+		return flags;
+	}
+
+	const envFlags = process.env.ESLINT_FLAGS.trim().split(/\s*,\s*/gu);
+	return Array.from(new Set([...envFlags, ...flags]));
+}
+
 //-----------------------------------------------------------------------------
 // Main API
 //-----------------------------------------------------------------------------
@@ -420,7 +434,7 @@ class ESLint {
 		const linter = new Linter({
 			cwd: processedOptions.cwd,
 			configType: "flat",
-			flags: processedOptions.flags,
+			flags: mergeEnvironmentFlags(processedOptions.flags),
 		});
 
 		const cacheFilePath = getCacheFile(
diff --git a/lib/shared/flags.js b/lib/shared/flags.js
@@ -27,6 +27,7 @@
  */
 const activeFlags = new Map([
 	["test_only", "Used only for testing."],
+	["test_only_2", "Used only for testing."],
 	[
 		"unstable_config_lookup_from_file",
 		"Look up `eslint.config.js` from the file being linted.",
diff --git a/tests/lib/cli.js b/tests/lib/cli.js
@@ -2741,6 +2741,11 @@ describe("cli", () => {
 						.returns();
 				});
 
+				afterEach(() => {
+					sinon.restore();
+					delete process.env.ESLINT_FLAGS;
+				});
+
 				it("should throw an error when an inactive flag whose feature has been abandoned is used", async () => {
 					const configPath = getFixturePath("eslint.config.js");
 					const filePath = getFixturePath("passing.js");
@@ -2751,6 +2756,18 @@ describe("cli", () => {
 					}, /The flag 'test_only_abandoned' is inactive: This feature has been abandoned\./u);
 				});
 
+				it("should throw an error when an inactive flag whose feature has been abandoned is used in an environment variable", async () => {
+					const configPath = getFixturePath("eslint.config.js");
+					const filePath = getFixturePath("passing.js");
+
+					process.env.ESLINT_FLAGS = "test_only_abandoned";
+					const input = `--config ${configPath} ${filePath}`;
+
+					await stdAssert.rejects(async () => {
+						await cli.execute(input, null, true);
+					}, /The flag 'test_only_abandoned' is inactive: This feature has been abandoned\./u);
+				});
+
 				it("should error out when an unknown flag is used", async () => {
 					const configPath = getFixturePath("eslint.config.js");
 					const filePath = getFixturePath("passing.js");
@@ -2761,6 +2778,18 @@ describe("cli", () => {
 					}, /Unknown flag 'test_only_oldx'\./u);
 				});
 
+				it("should error out when an unknown flag is used in an environment variable", async () => {
+					const configPath = getFixturePath("eslint.config.js");
+					const filePath = getFixturePath("passing.js");
+					const input = `--config ${configPath} ${filePath}`;
+
+					process.env.ESLINT_FLAGS = "test_only_oldx";
+
+					await stdAssert.rejects(async () => {
+						await cli.execute(input, null, true);
+					}, /Unknown flag 'test_only_oldx'\./u);
+				});
+
 				it("should emit a warning and not error out when an inactive flag that has been replaced by another flag is used", async () => {
 					const configPath = getFixturePath("eslint.config.js");
 					const filePath = getFixturePath("passing.js");
@@ -2780,6 +2809,28 @@ describe("cli", () => {
 					assert.strictEqual(exitCode, 0);
 				});
 
+				it("should emit a warning and not error out when an inactive flag that has been replaced by another flag is used in an environment variable", async () => {
+					const configPath = getFixturePath("eslint.config.js");
+					const filePath = getFixturePath("passing.js");
+					const input = `--config ${configPath} ${filePath}`;
+
+					process.env.ESLINT_FLAGS = "test_only_replaced";
+
+					const exitCode = await cli.execute(input, null, true);
+
+					assert.strictEqual(
+						processStub.callCount,
+						1,
+						"calls `process.emitWarning()` for flags once",
+					);
+					assert.deepStrictEqual(processStub.getCall(0).args, [
+						"The flag 'test_only_replaced' is inactive: This flag has been renamed 'test_only' to reflect its stabilization. Please use 'test_only' instead.",
+						"ESLintInactiveFlag_test_only_replaced",
+					]);
+					sinon.assert.notCalled(log.error);
+					assert.strictEqual(exitCode, 0);
+				});
+
 				it("should emit a warning and not error out when an inactive flag whose feature is enabled by default is used", async () => {
 					const configPath = getFixturePath("eslint.config.js");
 					const filePath = getFixturePath("passing.js");
@@ -2799,6 +2850,27 @@ describe("cli", () => {
 					assert.strictEqual(exitCode, 0);
 				});
 
+				it("should emit a warning and not error out when an inactive flag whose feature is enabled by default is used in an environment variable", async () => {
+					const configPath = getFixturePath("eslint.config.js");
+					const filePath = getFixturePath("passing.js");
+					const input = `--config ${configPath} ${filePath}`;
+
+					process.env.ESLINT_FLAGS = "test_only_enabled_by_default";
+
+					const exitCode = await cli.execute(input, null, true);
+					assert.strictEqual(
+						processStub.callCount,
+						1,
+						"calls `process.emitWarning()` for flags once",
+					);
+					assert.deepStrictEqual(processStub.getCall(0).args, [
+						"The flag 'test_only_enabled_by_default' is inactive: This feature is now enabled by default.",
+						"ESLintInactiveFlag_test_only_enabled_by_default",
+					]);
+					sinon.assert.notCalled(log.error);
+					assert.strictEqual(exitCode, 0);
+				});
+
 				it("should not error when a valid flag is used", async () => {
 					const configPath = getFixturePath("eslint.config.js");
 					const filePath = getFixturePath("passing.js");
@@ -2808,6 +2880,31 @@ describe("cli", () => {
 					sinon.assert.notCalled(log.error);
 					assert.strictEqual(exitCode, 0);
 				});
+
+				it("should not error when a valid flag is used in an environment variable", async () => {
+					const configPath = getFixturePath("eslint.config.js");
+					const filePath = getFixturePath("passing.js");
+					const input = `--config ${configPath} ${filePath}`;
+
+					process.env.ESLINT_FLAGS = "test_only";
+
+					const exitCode = await cli.execute(input, null, true);
+
+					sinon.assert.notCalled(log.error);
+					assert.strictEqual(exitCode, 0);
+				});
+
+				it("should error when a valid flag is used in an environment variable with an abandoned flag", async () => {
+					const configPath = getFixturePath("eslint.config.js");
+					const filePath = getFixturePath("passing.js");
+					const input = `--config ${configPath} ${filePath}`;
+
+					process.env.ESLINT_FLAGS = "test_only,test_only_abandoned";
+
+					await stdAssert.rejects(async () => {
+						await cli.execute(input, null, true);
+					}, /The flag 'test_only_abandoned' is inactive: This feature has been abandoned\./u);
+				});
 			});
 
 			describe("--report-unused-inline-configs option", () => {
diff --git a/tests/lib/eslint/eslint.js b/tests/lib/eslint/eslint.js
@@ -428,6 +428,10 @@ describe("ESLint", () => {
 					.returns();
 			});
 
+			afterEach(() => {
+				delete process.env.ESLINT_FLAGS;
+			});
+
 			it("should return true if the flag is present and active", () => {
 				eslint = new ESLint({
 					cwd: getFixturePath(),
@@ -437,6 +441,47 @@ describe("ESLint", () => {
 				assert.strictEqual(eslint.hasFlag("test_only"), true);
 			});
 
+			it("should return true if the flag is present and active with ESLINT_FLAGS", () => {
+				process.env.ESLINT_FLAGS = "test_only";
+				eslint = new ESLint({
+					cwd: getFixturePath(),
+				});
+				assert.strictEqual(eslint.hasFlag("test_only"), true);
+			});
+
+			it("should merge flags passed through API with flags passed through ESLINT_FLAGS", () => {
+				process.env.ESLINT_FLAGS = "test_only";
+				eslint = new ESLint({
+					cwd: getFixturePath(),
+					flags: ["test_only_2"],
+				});
+				assert.strictEqual(eslint.hasFlag("test_only"), true);
+				assert.strictEqual(eslint.hasFlag("test_only_2"), true);
+			});
+
+			it("should return true for multiple flags in ESLINT_FLAGS if the flag is present and active and one is duplicated in the API", () => {
+				process.env.ESLINT_FLAGS = "test_only,test_only_2";
+
+				eslint = new ESLint({
+					cwd: getFixturePath(),
+					flags: ["test_only"], // intentional duplication
+				});
+
+				assert.strictEqual(eslint.hasFlag("test_only"), true);
+				assert.strictEqual(eslint.hasFlag("test_only_2"), true);
+			});
+
+			it("should return true for multiple flags in ESLINT_FLAGS if the flag is present and active and there is leading and trailing white space", () => {
+				process.env.ESLINT_FLAGS = " test_only, test_only_2 ";
+
+				eslint = new ESLint({
+					cwd: getFixturePath(),
+				});
+
+				assert.strictEqual(eslint.hasFlag("test_only"), true);
+				assert.strictEqual(eslint.hasFlag("test_only_2"), true);
+			});
+
 			it("should return true for the replacement flag if an inactive flag that has been replaced is used", () => {
 				eslint = new ESLint({
 					cwd: getFixturePath(),
@@ -485,6 +530,15 @@ describe("ESLint", () => {
 				}, /The flag 'test_only_abandoned' is inactive: This feature has been abandoned/u);
 			});
 
+			it("should throw an error if an inactive flag whose feature has been abandoned is used in ESLINT_FLAGS", () => {
+				process.env.ESLINT_FLAGS = "test_only_abandoned";
+				assert.throws(() => {
+					eslint = new ESLint({
+						cwd: getFixturePath(),
+					});
+				}, /The flag 'test_only_abandoned' is inactive: This feature has been abandoned/u);
+			});
+
 			it("should throw an error if the flag is unknown", () => {
 				assert.throws(() => {
 					eslint = new ESLint({
@@ -494,6 +548,15 @@ describe("ESLint", () => {
 				}, /Unknown flag 'foo_bar'/u);
 			});
 
+			it("should throw an error if the flag is unknown in ESLINT_FLAGS", () => {
+				process.env.ESLINT_FLAGS = "foo_bar";
+				assert.throws(() => {
+					eslint = new ESLint({
+						cwd: getFixturePath(),
+					});
+				}, /Unknown flag 'foo_bar'/u);
+			});
+
 			it("should return false if the flag is not present", () => {
 				eslint = new ESLint({ cwd: getFixturePath() });
 

Original file line number	Diff line number	Diff line change
`@@ -27,6 +27,7 @@`
`27`	`27`	`*/`
`28`	`28`	`const activeFlags = new Map([`
`29`	`29`	`["test_only", "Used only for testing."],`
	`30`	`+ ["test_only_2", "Used only for testing."],`
`30`	`31`	`[`
`31`	`32`	`"unstable_config_lookup_from_file",`
`32`	`33`	"Look up `eslint.config.js` from the file being linted.",