English for ESLint Flat Config

Flat config replaced ESLint’s old .eslintrc cascading system with a single JavaScript array, and that structural shift comes with new vocabulary — “config objects” instead of “extends chains” — that’s worth using precisely when discussing a lint setup with a team still thinking in the old model.

Key Vocabulary

Config array — the eslint.config.js file’s top-level export, an ordered array of config objects that ESLint merges sequentially, replacing the old cascading .eslintrc file hierarchy. “The config array has four objects: base JS rules, the TypeScript override, the React plugin block, and a final ignores entry for generated files.”

Config object — a single object within the config array specifying files (which paths it applies to), rules, plugins, and languageOptions for that scope. “We added a separate config object scoped to **/*.test.ts so test files can use looser rules than production code without a nested override file.”

Flat plugin format — the requirement that plugins be imported as JavaScript modules and referenced by object reference in the config, rather than loaded by string name as in the legacy format. “The upgrade broke because the old plugin only shipped the legacy format — we had to switch to a fork that exports itself in the flat plugin format.”

languageOptions — the config object key defining parser, parser options, ECMAScript version, and global variables for the files it applies to, consolidating what used to be spread across parserOptions, env, and globals. “Browser globals like window were undefined-flagged because we hadn’t set languageOptions.globals for that config object — the old env: browser setting has no flat equivalent by default.”

ignores — a config object property (or a standalone object containing only ignores) that excludes matching paths from linting entirely, replacing .eslintignore. “We moved everything from .eslintignore into a single ignores-only config object at the top of the array — flat config no longer reads a separate ignore file by default.”

Common Phrases

• “Is this rule set in a config object scoped to specific files, or does it apply globally?”
• “Is the plugin imported in flat format, or is it still the legacy string-based one?”
• “Where are the language options defined for this file — is languageOptions actually covering it?”
• “Is this file excluded through an ignores entry, or is it just not being linted by accident?”
• “Does the config array order matter here — does a later object override an earlier rule?”

Example Sentences

Explaining a migration in a PR description: “Migrated from .eslintrc.json to flat config: four config objects instead of an extends chain, plugins imported directly instead of by name, and ignores consolidated into a single object.”

Debugging an unexpected lint failure: “This rule is coming from the base config object, and the TypeScript-specific object further down the array doesn’t override it — we need to add an explicit override there.”

Reviewing a config change: “Good call scoping that rule to a config object for just the test files — it was too strict for mocks and fixtures, but we still want it enforced in production code.”

Professional Tips

• Say config object rather than “the config” when there are multiple — flat config’s whole point is scoping rules per file pattern, and vague references undercut that.
• Confirm flat plugin format compatibility before proposing a plugin upgrade — a legacy-only plugin is a common blocker discovered mid-migration, not before.
• Reference languageOptions by name when debugging parser or globals issues — “the parser settings” is ambiguous about which config object actually applies.
• Consolidate exclusions into an explicit ignores object early in a migration and say so in the PR — a missing ignores entry silently re-lints generated files and confuses reviewers.

Practice Exercise

1. Write a sentence describing what a config object with files and rules does.
2. Explain, in your own words, the difference between the legacy and flat plugin formats.
3. Describe how you’d migrate a project’s ignore rules to flat config.

In Practice: Navigating Feedback and Collaboration

Let’s be honest – explaining why you’ve made a change to your ESLint configuration can feel surprisingly complex, even when you understand the technical details. It’s not just about saying “I added this plugin.” The goal is clear communication with other developers, particularly those whose first language isn’t English, and ensuring everyone is on the same page regarding code quality standards. Think of it as building a shared understanding – a crucial element in any successful development team.

Often, you’ll receive feedback during code reviews that goes beyond simply pointing out an error. A comment like, “This looks good but could be stricter with your variable naming rules” isn’t just criticism; it’s a request for clarification and a suggestion for improvement aligned with the project’s overall coding style. Similarly, in Slack discussions about configuration changes, you might hear phrases like, “Let’s ensure this plugin consistently enforces our preferred spacing conventions” or “Can we add a rule to prevent us from using var?” These require precise language to convey your intent and invite constructive dialogue. The key is to frame your explanations as suggestions for maintaining consistency rather than dictating specific rules, especially when dealing with developers who may have different interpretations of “best practices”. It’s about promoting a culture where technical decisions are transparent and collaboratively refined.

Consider this scenario: you’ve added a new ESLint plugin configured within a flat config file to enforce stricter type checking for TypeScript projects. During a code review, a senior developer asks, “Could you elaborate on how the no-explicit-any rule is intended to improve our codebase?” You need to respond with more than just “I added it.” You’d explain that the plugin’s configuration targets specific areas where overly permissive type annotations have been identified as potential sources of runtime errors and that consistent application of this rule will help prevent unexpected behavior. You might then add, “We can track these instances and review them periodically to ensure the plugin remains relevant.” This demonstrates a proactive approach and highlights the reasoning behind the change – vital for building trust and demonstrating your commitment to quality.

Here’s an example of a eslint.config.js file that incorporates a common configuration:

module.exports = {
  extends: [
    'plugin:react/recommended',
    'plugin:@typescript-eslint/recommended',
  ],
  plugins: ['@typescript-eslint', 'react'],
  rules: {
    '@typescript-eslint/no-explicit-any': 'error', // Example rule from ESLint
    'react/jsx-key': 'error',
  },
};

The extends array is particularly important. It shows that you’re building upon existing standards, rather than imposing entirely new ones. This demonstrates a collaborative mindset and an understanding of the project’s established guidelines. Remember, clear communication isn’t just about technical accuracy; it’s about fostering a productive and respectful environment where everyone feels valued and understood.