feat: support flat config system

[filiptammergard]

Resolves #591.

Wanted to open this for review to get some early feedback. This seems to work fine, if I create an eslint.config.js in the root with this content:

const prettier = require("./flat");

module.exports = [
  prettier.configs.recommended,
];

I get ESLint errors accordingly.

The idea here is that the flat config file could be imported this way in other projects:

const prettier = require("eslint-plugin-prettier/flat");

module.exports = [
  prettier.configs.recommended,
];

The reason not to change the main export is that the eslintrc format needs to have continued support. Eslintrc will be deprecated in v9 of ESLint and removed in v10, so to introduce a minimal amount of breaking changes, the flat config support can be purely additive and when ESLint v10 is released, the flat config could be made the main export in a new major version of this plugin.

Thoughts? If you think it's a good approach, I can continue adding documentation add changeset etc.

[changeset-bot]

🦋 Changeset detected

Latest commit: 9c45c5d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
eslint-plugin-prettier	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[filiptammergard]

Any early input in this one @JounQin?

[JounQin]

Sorry for forgetting this, I'll review recently ASAP.

[pumano]

Would love to use it as it will be available! @filiptammergard thank you!

[filiptammergard]

Some new docs on how to migrate to flat config format just came out: https://eslint.org/docs/latest/extend/plugin-migration-flat-config. Did some updates to align with those recommendations.

[pumano]

@filiptammergard don't stop in your idea to support it)

[BPScott]

Per https://eslint.org/blog/2023/10/flat-config-rollout-plans/

You should also make sure that your rules aren’t using context.parserOptions and context.parserPath. Instead, you should be using context.languageOptions and context.languageOptions.parser, which also work when ESLint is run in eslintrc mode. See our previous post for more information.

Looking at https://eslint.org/blog/2023/09/preparing-custom-rules-eslint-v9/, it seems we need to update our usage of the now-deprecated:

• context.getSourceCode
• context.getFilename
• context.getPhysicalFilename

We will need to identify when the replacements for these functions were added, and update our minimum supported version of eslint accordingly.

Any change to the minimum supported version will be a breaking change (Which is fine, but we'll need to update the changeset).

[filiptammergard]

Per https://eslint.org/blog/2023/10/flat-config-rollout-plans/

You should also make sure that your rules aren’t using context.parserOptions and context.parserPath. Instead, you should be using context.languageOptions and context.languageOptions.parser, which also work when ESLint is run in eslintrc mode. See our previous post for more information.

Looking at https://eslint.org/blog/2023/09/preparing-custom-rules-eslint-v9/, it seems we need to update our usage of the now-deprecated:

• context.getSourceCode
• context.getFilename
• context.getPhysicalFilename

We will need to identify when the replacements for these functions were added, and update our minimum supported version of eslint accordingly.

Any change to the minimum supported version will be a breaking change (Which is fine, but we'll need to update the changeset).

Good input @BPScott!

Looks like the methods you're mentioning are becoming properties (added in v8.40.0): https://eslint.org/blog/2023/09/preparing-custom-rules-eslint-v9/#context-methods-becoming-properties

The methods will be removed in ESLint v10 (not v9), so there's no rush here. The blog post also suggests supporting both versions like this:

const sourceCode = context.sourceCode ?? context.getSourceCode();

If the property is undefined (as per before ESLint v8.40.0), the method is used instead, and no breaking change needs to be considered.

However, I think those changes can be considered separately from supporting flat config format, so I made a separate PR for it: #594

[filiptammergard]

@JounQin @BPScott Updated now to avoid mutations and to align with the recommendation to always provide meta information: https://eslint.org/docs/latest/extend/plugin-migration-flat-config#adding-plugin-meta-information I needed to bump @types/eslint to get support for flat config types.

Also renamed from recommended to flat since that makes it more clear that this in a flat config export.

[BPScott]

Thanks for fighting through this!

https://eslint.org/docs/latest/extend/plugin-migration-flat-config#backwards-compatibility makes it seem like it would be totally fine to have both a regular and flat config defined within the configs key of eslint-plugin-prettier.js instead of needing a whole new file for this.

It seems like it should be possible to add a new "recommended-flat" key to the configs object and define the config there and use it like so, instead of needing to add a new file to the repo:

// in some consuming apps eslint.config.mjs file that is authored in the flat config style

import eslintPluginPrettier from 'eslint-plugin-prettier';

export default [
  eslintPluginPrettier.configs['recommended-flat'],
  {/* the app's own config goes here */}
]

The linked blogpost suggested having a flat config called "BLAH" and the legacy equivalent is named named "BLAH-legacy". That seems like a nice idea eventually, but I like the idea of of avoiding a backwards compatibility break now by adding a new config that is flat-compatible and leaving the current one as-is. We can swap the names around in some future major version.

Could you please add the new flat compatible config to the configs key in eslint-plugin-prettier.js with the name"recommended-flat", instead of adding a new entrypoint to the package.

---

We'll also need to update the README to talk about how to use the flat config, but hold off on that till we are happy with the the implementation and how people would consume it.

[filiptammergard]

@BPScott I think both ways work, and for example eslint-plugin-react went the other way: https://github.com/jsx-eslint/eslint-plugin-react#configuring-shared-settings

But since ESLint recommends doing as you said, I think it might be a good idea to lean on that. The downside with having them in the same file is that I can't reference the plugin from the config like this:

const eslintPluginPrettier = {
  configs: {
    recommended: {
      extends: ['prettier'],
      plugins: ['prettier'],
      rules: {
        'prettier/prettier': 'error',
        'arrow-body-style': 'off',
        'prefer-arrow-callback': 'off',
      },
    },
    'recommended-flat': {
      plugins: {
        prettier: eslintPluginPrettier, // Error "Block-scoped variable 'eslintPluginPrettier' used before its declaration.ts(2448)"
      },
      rules: {
        'prettier/prettier': 'error',
        'arrow-body-style': 'off',
        'prefer-arrow-callback': 'off',
      },
    },
  },
  rules: {
    prettier: {/* ... */},
  },
};

That makes eslintPluginPrettier reference itself and that gives a circular dependency. So we have to either mutate it with Object.assign, or we create a new variable as I did now.

Thoughts on this?

[filiptammergard]

@BPScott I saw you pushed a commit for using Object.assign instead of creating a new variable. Any other changes requested, or should I get going updating the docs accordingly?

[pumano]

@JounQin could you please review it? Very important feature

[JounQin]

Should we use camelCase here?

[pumano]

looks like config names should be as rules with dashes also eslint have config naming convention for eslint plugins with dashes too

[JounQin]

The previous rules are for legacy configs, for flat configs, we're using js object reference instead, so camelCase is preferred IMO. And I think flatRecommended makes more sense than recommendedFlat.

[filiptammergard]

recommended-flat is all based on direction from the ESLint team:

Export both eslintrc and flat configs. The configs key is only validated when a config is used, so you can provide both formats of configs in the configs key. We recommend that you append older format configs with -legacy to make it clear that these configs will not be supported in the future. For example, if your primary config is called recommended and is in flat config format, then you can also have a config named recommended-legacy that is the eslintrc config format.

https://eslint.org/docs/latest/extend/plugin-migration-flat-config#backwards-compatibility

They're recommending appending -legacy for legacy configs (to make it recommended-legacy for example), which means -flat is the equivalent. Should we not go for that?

[JounQin]

That strategy is an unnecessary breaking change IMO, and it can be made in next major version.

[filiptammergard]

Yes, that's why the suggestion is to add recommended-flat now (non-breaking) and swap them around in next major.

[JounQin]

My suggestion is to add flatRecommended config key instead of recommended-flat.

[BPScott]

Ah sorry, I thought I added a comment after pushing up that change at the weekend.

I've been thinking about this for the last few days, and now I've had a chance to play with what the eslint suggested approach looks like, I actually kinda hate it. Having to do object reassignment in eslint-plugin-prettier feels clunky, and the naming clashes of recommended vs recommended-flat/flat-recommended is awkward.

This PR's original approach of mimicking eslint-plugin-react and creating a new recommended.js file, and getting people to import from eslint-plugin-prettier/recommended feels a bunch cleaner. We should feed this back to the eslint team at some point.

@JounQin I think my previous request of "lets follow eslint recommendations" was a bad idea (well, good for learning what it looks like, bad for actually using), and instead am preferring having the "recommended.js" file that was proposed at the start of this PR. Now you've saw both approaches, do you have on preference on which one feels better?

[JounQin]

In my view I'd like to have a flat.js exporting a flat plugin, usage:

const prettier = require("eslint-plugin-prettier/flat");

module.exports = [
  {
    // usage 1, use plugin manually
    plugins: {
      prettier,
    },
  },
  // usage 2, enable rules automatically
  prettier.configs.recommended,
];

[BPScott]

I think "flat plugin" is a bit of a misnomer. Reading https://eslint.org/docs/latest/extend/plugin-migration-flat-config, I get the impression that if we add the meta block to the existing plugin then it will work with flat or legacy configs, with the exception of the configs object. At that point it's only the "configs" that we need to deal with. I'm pretty sure that for usage one, people can already do the following (once we add the meta block), there's no need for a dedicated file:

const prettier = require("eslint-plugin-prettier");

module.exports = [
  {
    // usage 1, use plugin manually
    plugins: {
      prettier,
    },
  },
];

And then usage 2 can be

const prettierRecommended = require("eslint-plugin-prettier/recommended");

module.exports = [
  {
    ...prettierRecommended
  },
];

[JounQin]

@BPScott Fair enough, I'm fine with that approach.

[filiptammergard]

A suggestion is to bump @types/eslint separately, so that this PR can handle only what's explicitly related to introducing flat config format support. #602

Sounds good?

[filiptammergard]

And same for this one: #603

[filiptammergard]

I dropped the commit where @types/eslint was bumped from this PR now as it is already taken care of in #602.

[JounQin]

Suggested change

	module.exports = [prettier.configs['recommended-flat']];
	module.exports = [prettier.config.flatRecommended];

I still recommend this config name.

[filiptammergard]

But even better with a separate flat.js file, right?

[JounQin]

I don't have such preference, a clear document is enough IMO.

[filiptammergard]

Waiting for input by @BPScott on what direction to take before I proceed. I'll vote for using a separate file flat.js.

[filiptammergard]

Do you have any input @BPScott?

[JounQin]

I think the deadline could be this weekend, otherwise I'll help to refactor and release in my view.

[BPScott]

Waiting for input by @BPScott on what direction to take before I proceed. I'll vote for using a separate file flat.js.

Aah sorry I totally missed this and the updates from the eslint discord. I was planning to come back to this PR last week but needing a break got to me.

---

@filiptammergard thank you for pushing on with this, and asking for opinions from the eslint discord. It's great to know that they're not pushing hard on the approach suggested in https://eslint.org/docs/latest/extend/plugin-migration-flat-config.

Doing a little audit of other popular plugins:

• eslint-plugin-react, eslint-plugin-import, eslint-plugin-unicorn have a configs/recommended.js file for the flat recommended config (ok eslint-plugin-import has config/recommended.js but near enough).
• -eslint-plugin-jest and eslint-plugin-jsx-a11y don't yet support flat config but have PRs that have the same configs/recommended.js approach.
• eslint-plugin-jsdoc and eslint-plugin-n Adds a flat/recommended config to the main export
• typescript-eslint has a draft PR that goes down a third approach of creating a new wrapper package

With three popular packages diverging from the recommendations I don't feel bad about diverging. We have a single rule so we won't ever need multiple configs (ignoring the legacy vs flat distinction) so I think placing that in a configs folder is overkill. The root of the repo is fine and good.

I think I still prefer creating a new separate file and usage being const prettierRecommended = require('eslint-plugin-prettier/recommended');. I think that's a little cleaner than const prettierRecommended = require('eslint-plugin-prettier').configs['flat/recommended'].

I would prefer that new file be named recommended.js instead of flat.js. Consider fast forwarding to two years time when ESLint v10 is released and the legacy config format is dead - having a file called flat.js feels strange in that world - I'd expect that the filename should be the name of the config - recommended feels like it makes more sense to me.

---

My request is annoyingly "back to what we had originally before I opened my mouth":

• A recommended.js in the root of the repo
• Add a recommended.d.ts with types
• Add those two files to the package.json's files array
• We'll need to update the README to describe usage when using flat config

[BPScott]

I've made a the above changes in #616. Notably in contains a rewrite of the readme file's configuration section.