docs: add document for FlatCompat use

[MikeMcC399]

• relates to issue Upgrade to new ESLint Flat configuration files #146

Issue

The README > Usage section describes how to add an .eslintrc.json configuration file to use the eslint-plugin-cypress plugin. With the announcement and release of ESLint v9 on Apr 5, 2024, configuration files in the format .eslintrc.* have become deprecated (see ESLint 8.x Configuration Files).

The plugin needs to document how to set up and use non-deprecated Configuration Files (New) for ESLint v8. These are JavaScript files using an eslint.config.*js naming convention. Users of the plugin may otherwise be blocked from preparing to update to ESLint v9 through lack of information.

Constraints

Plugins

• eslint-plugin-cypress has not yet implemented the instructions in Plugin Migration to Flat Config (see issue Upgrade to new ESLint Flat configuration files #146). It is compatible with ESLint v7 and v8.
• eslint-plugin-mocha documents how to import a flat config. It is compatible with ESLint v7 to v9.
• eslint-plugin-chai-friendly documents only how to use an .eslintrc.* legacy config file. The latest version [email protected] is not compatible with the ESLint v9 API due to usage of context.getAncestors. It is compatible with ESLint v3 to v8.

Node.js

• The package.json of eslint-plugin-cypress has no package type defined and so it defaults to CommonJS.
• import statements are supported only in ECMAScript (ES module / ESM).
• The default type of CommonJS constrains to using the .mjs extension for the ESLint configuration file in order to use import statements.

ESLint usage

• The ESLint Backwards compatibility utility, with the FlatCompat class from the npm module @eslint/eslintrc, is required to use legacy plugins in a flat config environment.
• [email protected] is the minimum version to detect and use an eslint.config.mjs configuration file (see ESLint CHANGELOG and ESLint 8.x > Configuration File Resolution).

Change

In order to provide clear, readable instructions for both legacy (.eslintrc.*) and new, flat config (eslint.config.*js) users, a separate document FLAT-CONFIG.md is created for the new flat config instructions.

Future steps

• Building on this documentation change, include support for usage of the eslint-plugin-cypress plugin in FlatCompat compatibility mode together with ESLint v9 in addition to ESLint 8.57.0.

References

• Configuration Migration Guide
• Backwards compatibility utility
• npm module @eslint/eslintrc

ESLint 8.x

• ESLint 8.x Configuration Files
• ESLint 8.x Configuration Files (New)
• ESLint 8.x Configuration Files (New) > Configuration File Resolution

[cypress-app-bot]

• Create a Draft Pull Request if your PR is not ready for review. Mark the PR as Ready for Review when you're ready for a Cypress team member to review the PR.

[jennifer-shehane]

@MikeMcC399 Thanks for adding this! It will help users be successful in the near term. Adding a lot of examples with the addition of other plugins is helpful.

[MikeMcC399]

@jennifer-shehane

Thanks for adding this! It will help users be successful in the near term. Adding a lot of examples with the addition of other plugins is helpful.

The examples are complete tested and ready to copy-and-paste. So I hope these will be helpful to users. I would have been grateful to have them as I was trying to ramp up!

[cypress-app-bot]

🎉 This PR is included in version 3.2.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀