Support name field in flat config and recommend as an convention

[antfu]

ESLint version

v9.0.0-rc.0

What problem do you want to solve?

(This is more like an RFC, but since it's rather simple, I started here first, but up to moving it to a proper RFC if you think it's necessary)

The new flat config format is truly great in many ways - I guess I don't need to list them - but thank you for making this move!

While it's great and much more composable, I often find it hard to tell the meaning/scope of each flat config item just by looking at the config among a large number of configs.

That's why I made https://github.com/antfu/eslint-flat-config-viewer, an interactive web UI to display the resolved flat configure structure with a search to understand how rules are applied. But still - given that the flat config items are anonymous, it not obvious what config are for what purpose.

Thus in the config viewer, and my own eslint-config, I spontaneously invented the convention of having that name field convention in my config and displaying name in the viewer. for example like this:

import eslint from '@eslint/js'

export default [
  {
    name: 'eslint:js', // assign custom name to other config
    ...eslint 
  }, 
  {
    name: 'antfu:ts',
    // ts plugins & rules...
  },
  {
    name: 'antfu:vue',
    // vue plugins & rules...
  }
  {
    name: 'antfu:vue:disables':
    // ...
  }
]

Which I believe helps a lot on communications as well as some userland overrides like:

flatConfigs
    .find(c => c.name === 'stylistic')
    .rules['indent'] = 'off'

export default flatConfigs

What do you think is the correct solution?

Even if it "kinda works" right now, as ESLint is not compliant about the extra name properties (#17842 (comment)). But I think it would be great for the ecosystem to make it an official supported way and develop a convention across the ecosystem. The shared configs from plugins could have their plugin name as the prefix for their configs for example.

To achieve that, I think we could:

• Add name to the flat config schema, and add it in @types/eslint
• Add a doc section to recommend plugins/configs authors to provide that field with a convention (could be namespace:scope:sub-scope or namespace/scope etc, but more like a convention, not a constraint)
• Integrations like https://github.com/antfu/eslint-flat-config-viewer could follow up that convention to provide a better DX for users,

Participation

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

Additional comments

No response

[bmish]

This sounds like a useful idea.

I just want to call out a related ticket about potentially standardizing meta properties like name / description under meta or meta.docs so that rules and configs have consistent properties:

• Change Request: Standardize documentation properties (e.g. allow configs to export description) #17842

[antfu]

According to #17842 (comment), where name is actually already undocumented supported - while I do like the meta approach better as it would allow more possible properties to be exposed. I wonder if we should deprecate the top-level name in favor of meta.name, or keep them co-exists?

[nzakas]

@bmish thanks for pointing out the related issue. 👍 As a reminder, as a team member, we need you to help push new issues through the triage process. While your comment is informative, it's not moving the issue through the process, so please keep an eye on that going forward.

@antfu The only reason we haven't documented and recommended using name in config objects is because we don't expose that value anywhere. My plan was to include it in thrown errors, so this is a good reminder to go back and do that.

I do think we can have both name and meta.name, as we already support both for plugins.

Also, the flag config viewer is amazing. Is there any chance you'd be willing to donate that to the ESLint project? You could stay on as the maintainer and we could pay you. 😄 If that's of interest, shoot me an email at contact (at) eslint (dot) org and we can talk details.

[antfu]

My plan was to include it in thrown errors, so this is a good reminder to go back and do that.

That was something really useful indeed - I was about the bring that up as well. I suppose it won't be a conflict to have the ecosystem using the convention as ESLint implements better error messages. Let me know what I can help to move this forward; I am happy to do either the code and/or the documentation if you aren't already working on them.

Glad to hear you like the config viewer - sure, I am more than happy to donate it if that could help more ppl to get their hands on it! Just send you the email :)

[nzakas]

Related external PR:
humanwhocodes/config-array#128