Change Request: `defineConfig` to freeze config

[privatenumber]

Which packages would you like to change?

• @eslint/compat
• @eslint/config-array
• @eslint/config-helpers
• @eslint/core
• @eslint/mcp
• @eslint/migrate-config
• @eslint/object-schema
• @eslint/plugin-kit

What problem do you want to solve?

With flat configs, users manage extension manually. This makes it easy to accidentally mutate shared config objects, especially in setups with multiple plugins or layered configs.

This can lead to unpredictable behavior, particularly when multiple plugins rely on the same config object. When there's no safeguard against mutation, these side effects can be hard to trace and debug.

ESLint's own config config uses Object.freeze() to prevent this, but many third-party config authors may not always remember to freeze their config objects manually.

What do you think is the correct solution?

Have defineConfig automatically deep freeze the returned config. This would align with ESLint's own internal practice, add a protective seal to the config, and make immutability the default.

Participation

• I am willing to submit a pull request for this change.

Additional comments

No response

[nzakas]

Thanks for the suggestion. Can you give a concrete example of the problem you're describing? (I'm assuming you probably just encountered this?).

As a note: we can't actually deep freeze a config because that would go into plugin objects, parser objects, etc., that the user doesn't own. So I think what you're asking for is more of a two-layer freeze, which is what the built-in config does.

[privatenumber]

I actually ran into this a while back and just came across this repo 😅
My original request was ported from eslint-types/eslint-define-config#264

IIRC the issue came from me directly mutating a plugin's "recommended" config to apply overrides—it just felt like the simplest way to do it at the time. So it made me think others may also encounter this mistake too and thought this is something devs should have guardrails against.

[nzakas]

Ah I see. In that case, the real solution is to have the plugin freeze the recommended config. We don't want to go around freezing objects that belong to other packages because that could cause problems. The only other alternative would be to deep clone the entire config, but that's an expensive operation.

[privatenumber]

I thought defineConfig was also for plugin or shared config authors, which is why I filed this issue (and I think your two-layer freeze approach could be useful here). Or is defineConfig mainly intended just for end users?

[nzakas]

defineConfig() is primarily for end users.