@commercetools-frontend/eslint-config-mc-app 26.1.0 → 27.1.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @commercetools-frontend/eslint-config-mc-app
 
+## 27.1.0
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @commercetools-frontend/babel-preset-mc-app@27.1.0
+
+## 27.0.0
+
+### Major Changes
+
+- [#3936](https://github.com/commercetools/merchant-center-application-kit/pull/3936) [`d890dce`](https://github.com/commercetools/merchant-center-application-kit/commit/d890dce89affdce28220fd3627a1b31244c26640) Thanks [@valoriecarli](https://github.com/valoriecarli)! - Migrate to ESLint 9 flat config format.
+
+  **Peer dependency:** `eslint@^9.0.0` is now required.
+
+  ## How to update
+
+  Both packages ship a `migrations/v27.md` with full step-by-step instructions, structured for both human and AI-assisted migration:
+
+  ```
+  node_modules/@commercetools-frontend/eslint-config-mc-app/migrations/v27.md
+  node_modules/@commercetools-backend/eslint-config-node/migrations/v27.md
+  ```
+
+  > "Migrate my eslint config following `node_modules/@commercetools-frontend/eslint-config-mc-app/migrations/v27.md`"
+
+  Quick summary:
+
+  1. Upgrade ESLint to v9: `eslint@^9.0.0`
+  2. Replace `.eslintrc.js` with `eslint.config.js`:
+
+  ```js
+  const mcAppConfig = require('@commercetools-frontend/eslint-config-mc-app');
+
+  module.exports = [
+    ...mcAppConfig,
+    // your overrides here
+  ];
+  ```
+
+  3. Delete `.eslintignore` and inline ignore patterns as `{ ignores: ['dist/', 'build/'] }` in `eslint.config.js`
+  4. Remove `@rushstack/eslint-patch` if present
+
+  ## What changed
+
+  Both packages now export a flat config array instead of a legacy `.eslintrc` object:
+
+  - Config is now an array of objects, each targeting its own file patterns (replaces `overrides`)
+  - Plugins must be imported as objects, not referenced as strings
+  - Parsers moved into `languageOptions.parser`
+  - `env` replaced with explicit globals via the `globals` package
+  - `extends` removed — plugin rules are configured directly
+  - `@rushstack/eslint-patch` removed — no longer needed in ESLint 9
+  - `react-hooks` rules now explicitly applied to `**/*.ts` files (custom hooks without JSX)
+
+  Dependency upgrades: `@typescript-eslint/*` v5→v8, `eslint-plugin-jest` v27→v28, `eslint-plugin-react-hooks` v4→v5, `eslint-plugin-testing-library` v5→v7.
+
+  ## Why
+
+  ESLint 9 drops support for the legacy `.eslintrc` format. The flat config system provides explicit, predictable scoping — plugins and parsers apply only to the file patterns they are registered for, eliminating the silent global leaking behavior of ESLint 8 overrides.
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @commercetools-frontend/babel-preset-mc-app@27.0.0
+
 ## 26.1.0
 
 ### Patch Changes

package/README.md

@@ -4,22 +4,35 @@
   <a href="https://www.npmjs.com/package/@commercetools-frontend/eslint-config-mc-app"><img src="https://badgen.net/npm/v/@commercetools-frontend/eslint-config-mc-app" alt="Latest release (latest dist-tag)" /></a> <a href="https://www.npmjs.com/package/@commercetools-frontend/eslint-config-mc-app"><img src="https://badgen.net/npm/v/@commercetools-frontend/eslint-config-mc-app/next" alt="Latest release (next dist-tag)" /></a> <a href="https://bundlephobia.com/result?p=@commercetools-frontend/eslint-config-mc-app"><img src="https://badgen.net/bundlephobia/minzip/@commercetools-frontend/eslint-config-mc-app" alt="Minified + GZipped size" /></a> <a href="https://github.com/commercetools/merchant-center-application-kit/blob/main/LICENSE"><img src="https://badgen.net/github/license/commercetools/merchant-center-application-kit" alt="GitHub license" /></a>
 </p>
 
-ESLint config used by Merchant Center customizations.
+ESLint flat config (v9+) for Merchant Center customizations.
+
+## Requirements
+
+- ESLint 9.x or higher
+- Node.js 18.x, 20.x, or >=22.0.0
+
+## Migrations
+
+See the [migrations/](./migrations/) directory for version-specific upgrade guides. Each file is structured for both human and AI-assisted migration.
 
 ## Install
 
 ```bash
-$ npm install --save @commercetools-frontend/eslint-config-mc-app
-
-$ npx install-peerdeps --dev @commercetools-frontend/eslint-config-mc-app
+pnpm add -D eslint @commercetools-frontend/eslint-config-mc-app
 ```
 
 ## Usage
 
+Create an `eslint.config.js` file in your project root:
+
 ```js
-// .eslintrc.js
+// eslint.config.js
+const mcAppConfig = require('@commercetools-frontend/eslint-config-mc-app');
 
-module.exports = {
-  extends: ['@commercetools-frontend/eslint-config-mc-app'],
-};
+module.exports = [
+  ...mcAppConfig,
+  // Add your custom config overrides here
+];
 ```
+
+> **Note**: This package uses ESLint's flat config format introduced in ESLint 9. If you're migrating from ESLint 8, you'll need to replace your `.eslintrc.js` file with `eslint.config.js`.

package/helpers/rules-presets.js

@@ -267,23 +267,21 @@ const craRules = {
     'jest/valid-title': statusCode.warn,
 
     // https://github.com/testing-library/eslint-plugin-testing-library
-    'testing-library/await-async-query': statusCode.error,
+    // Note: v6 renamed rules to plural forms and removed some rules
+    'testing-library/await-async-queries': statusCode.error,
     'testing-library/await-async-utils': statusCode.error,
-    'testing-library/no-await-sync-query': statusCode.error,
+    'testing-library/no-await-sync-queries': statusCode.error,
     'testing-library/no-container': statusCode.error,
     'testing-library/no-debugging-utils': statusCode.error,
     'testing-library/no-dom-import': [statusCode.error, 'react'],
     'testing-library/no-node-access': statusCode.error,
     'testing-library/no-promise-in-fire-event': statusCode.error,
-    'testing-library/no-render-in-setup': statusCode.error,
     'testing-library/no-unnecessary-act': statusCode.error,
-    'testing-library/no-wait-for-empty-callback': statusCode.error,
     'testing-library/no-wait-for-multiple-assertions': statusCode.error,
     'testing-library/no-wait-for-side-effects': statusCode.error,
     'testing-library/no-wait-for-snapshot': statusCode.error,
     'testing-library/prefer-find-by': statusCode.error,
     'testing-library/prefer-presence-queries': statusCode.error,
-    'testing-library/prefer-query-by-disappearance': statusCode.error,
     'testing-library/prefer-screen-queries': statusCode.error,
     'testing-library/render-result-naming-convention': statusCode.error,
   },

package/index.js

@@ -1,264 +1,417 @@
-process.env.BABEL_ENV = 'production';
-
-// This is a workaround for https://github.com/eslint/eslint/issues/3458
-require('@rushstack/eslint-patch/modern-module-resolution');
-
-const { statusCode, allSupportedExtensions } = require('./helpers/eslint');
-const hasJsxRuntime = require('./helpers/has-jsx-runtime');
-const { craRules } = require('./helpers/rules-presets');
-
 /**
- * @type {import("eslint").Linter.Config}
+ * ESLint flat config (v9+) for @commercetools-frontend/eslint-config-mc-app
+ *
+ * This package provides ESLint configuration using the new flat config format
+ * introduced in ESLint v9. It includes support for:
+ * - TypeScript
+ * - React and JSX
+ * - Jest and Testing Library
+ * - Cypress
+ * - Import ordering and validation
+ * - Prettier integration
+ * - Accessibility rules (jsx-a11y)
  */
-module.exports = {
-  root: true,
 
-  parser: '@babel/eslint-parser',
+/**
+ * ESLint flat config (v9+) for @commercetools-frontend/eslint-config-mc-app
+ *
+ * This package provides ESLint configuration using the new flat config format
+ * introduced in ESLint v9. It includes support for:
+ * - TypeScript
+ * - React and JSX
+ * - Jest and Testing Library
+ * - Cypress
+ * - Import ordering and validation
+ * - Prettier integration
+ * - Accessibility rules (jsx-a11y)
+ */
 
-  parserOptions: {
-    sourceType: 'module',
-    requireConfigFile: false,
-    babelOptions: {
-      presets: [
-        require.resolve(
-          '@commercetools-frontend/babel-preset-mc-app/production'
-        ),
-      ],
-    },
-  },
+process.env.BABEL_ENV = 'production';
 
-  env: {
-    browser: true,
-    commonjs: true,
-    es6: true,
-    jest: true,
-    node: true,
-  },
+const fs = require('fs');
+const path = require('path');
 
-  extends: [
-    // https://github.com/cypress-io/eslint-plugin-cypress
-    'plugin:cypress/recommended',
-    // https://github.com/import-js/eslint-plugin-import
-    'plugin:import/errors',
-    'plugin:import/warnings',
-    'plugin:import/typescript',
-    // https://github.com/prettier/prettier-eslint
-    // NOTE: this should go last.
-    'prettier',
-  ],
+const migrationGuide =
+  'node_modules/@commercetools-frontend/eslint-config-mc-app/migrations/v27.md';
 
-  plugins: [
-    // https://github.com/import-js/eslint-plugin-import
-    'import',
-    // https://github.com/jsx-eslint/eslint-plugin-jsx-a11y
-    'jsx-a11y',
-    // https://github.com/prettier/prettier-eslint
-    'prettier',
-  ],
+// Detect if loaded from a legacy .eslintrc file (the array export won't work there)
+const caller = module.parent?.filename || '';
+if (/\.eslintrc/.test(caller)) {
+  console.error(
+    '\n\u274c @commercetools-frontend/eslint-config-mc-app v27 exports a flat config array.\n' +
+      '   It cannot be used in .eslintrc files. Migrate to eslint.config.js.\n' +
+      '   Guide: ' +
+      migrationGuide +
+      '\n'
+  );
+}
 
-  settings: {
-    'import/resolver': {
-      node: {
-        extensions: allSupportedExtensions,
-      },
-    },
-  },
+// Detect leftover legacy config files and warn
+const projectRoot = process.cwd();
+const legacyPatterns = [
+  '.eslintrc',
+  '.eslintrc.js',
+  '.eslintrc.cjs',
+  '.eslintrc.json',
+  '.eslintrc.yml',
+  '.eslintrc.yaml',
+];
+const foundLegacy = legacyPatterns.filter((name) =>
+  fs.existsSync(path.join(projectRoot, name))
+);
+if (foundLegacy.length > 0) {
+  console.warn(
+    '\n\u26a0\ufe0f  @commercetools-frontend/eslint-config-mc-app v27 uses ESLint 9 flat config.\n' +
+      `   Found legacy config file(s): ${foundLegacy.join(', ')}\n` +
+      '   These files are ignored by ESLint 9 and your subdirectory rules will not be applied.\n' +
+      '   Guide: ' +
+      migrationGuide +
+      '\n'
+  );
+}
 
-  rules: {
-    ...craRules.base,
+const babelParser = require('@babel/eslint-parser');
+const typescriptPlugin = require('@typescript-eslint/eslint-plugin');
+const typescriptParser = require('@typescript-eslint/parser');
+const prettierConfig = require('eslint-config-prettier');
+const cypressPlugin = require('eslint-plugin-cypress');
+const importPlugin = require('eslint-plugin-import');
+const jestPlugin = require('eslint-plugin-jest');
+const jestDomPlugin = require('eslint-plugin-jest-dom');
+const jsxA11yPlugin = require('eslint-plugin-jsx-a11y');
+const prettierPlugin = require('eslint-plugin-prettier');
+const reactPlugin = require('eslint-plugin-react');
+const reactHooksPlugin = require('eslint-plugin-react-hooks');
+const testingLibraryPlugin = require('eslint-plugin-testing-library');
+const globals = require('globals');
 
-    // NOTE: The regular rule does not support do-expressions. The equivalent rule of babel does.
-    'no-unused-expressions': statusCode.off,
+// Reuse existing helpers
+const { statusCode, allSupportedExtensions } = require('./helpers/eslint');
+const hasJsxRuntime = require('./helpers/has-jsx-runtime');
+const { craRules } = require('./helpers/rules-presets');
 
-    // Enforce direct lodash imports for tree-shaking (e.g., 'lodash/omit' not 'lodash')
-    'no-restricted-imports': [
-      statusCode.warn,
-      {
-        paths: [
-          {
-            name: 'lodash',
-            message:
-              "Import from 'lodash/<function>' directly for tree-shaking (e.g., import omit from 'lodash/omit').",
-          },
-        ],
+/**
+ * ESLint flat config format for @commercetools-frontend/eslint-config-mc-app
+ * @type {import("eslint").Linter.FlatConfig[]}
+ */
+module.exports = [
+  // Base config for all JavaScript/TypeScript files
+  {
+    files: ['**/*.{js,jsx,ts,tsx,cjs,mjs}'],
+    languageOptions: {
+      parser: babelParser,
+      parserOptions: {
+        sourceType: 'module',
+        requireConfigFile: false,
+        babelOptions: {
+          presets: [
+            require.resolve(
+              '@commercetools-frontend/babel-preset-mc-app/production'
+            ),
+          ],
+        },
       },
-    ],
-
-    // Imports
-    'import/extensions': [
-      statusCode.error,
-      {
-        js: 'never',
-        jsx: 'never',
-        ts: 'never',
-        tsx: 'never',
-        mjs: 'never',
-        json: 'always',
-        svg: 'always',
-        graphql: 'always',
+      ecmaVersion: 2020,
+      globals: {
+        ...globals.browser,
+        ...globals.commonjs,
+        ...globals.es2015,
+        ...globals.node,
       },
-    ],
-    'import/default': statusCode.off,
-    'import/first': statusCode.error,
-    // TODO: enable this once there is support for `import type`
-    // 'import/order': statusCode.error,
-    'import/namespace': statusCode.off,
-    'import/no-extraneous-dependencies': statusCode.off,
-    'import/no-named-as-default': statusCode.off,
-    'import/no-named-as-default-member': statusCode.off,
-    'import/no-unresolved': statusCode.error,
-  },
-
-  overrides: [
-    {
-      files: ['*.{spec,test}.*'],
-      env: {
-        'jest/globals': true,
+    },
+    plugins: {
+      import: importPlugin,
+      'jsx-a11y': jsxA11yPlugin,
+      prettier: prettierPlugin,
+      cypress: cypressPlugin,
+    },
+    settings: {
+      'import/resolver': {
+        node: {
+          extensions: allSupportedExtensions,
+        },
       },
-      extends: [
-        // https://github.com/jest-community/eslint-plugin-jest
-        'plugin:jest/recommended',
-        // https://github.com/testing-library/eslint-plugin-testing-library
-        'plugin:testing-library/react',
-        // https://github.com/prettier/prettier-eslint
-        // NOTE: this should go last.
-        'prettier',
+    },
+    rules: {
+      ...craRules.base,
+      // Disable React rules in base config - they'll be enabled in React file configs
+      'react/forbid-foreign-prop-types': statusCode.off,
+      'react/jsx-no-comment-textnodes': statusCode.off,
+      'react/jsx-no-duplicate-props': statusCode.off,
+      'react/jsx-no-target-blank': statusCode.off,
+      'react/jsx-no-undef': statusCode.off,
+      'react/jsx-pascal-case': statusCode.off,
+      'react/no-danger-with-children': statusCode.off,
+      'react/no-direct-mutation-state': statusCode.off,
+      'react/no-is-mounted': statusCode.off,
+      'react/no-typos': statusCode.off,
+      'react/require-render-return': statusCode.off,
+      'react/style-prop-object': statusCode.off,
+      'react-hooks/exhaustive-deps': statusCode.off,
+      'react-hooks/rules-of-hooks': statusCode.off,
+      'no-unused-expressions': statusCode.off,
+      // Enforce direct lodash imports for tree-shaking (e.g., 'lodash/<function>' not 'lodash')
+      'no-restricted-imports': [
+        statusCode.warn,
+        {
+          paths: [
+            {
+              name: 'lodash',
+              message:
+                "Import from 'lodash/<function>' directly for tree-shaking (e.g., import omit from 'lodash/omit').",
+            },
+          ],
+        },
       ],
-      plugins: [
-        'testing-library',
-        // https://github.com/jest-community/eslint-plugin-jest
-        'jest',
-        // https://github.com/testing-library/eslint-plugin-jest-dom
-        'jest-dom',
-        // https://github.com/prettier/prettier-eslint
-        'prettier',
+      'import/extensions': [
+        statusCode.error,
+        {
+          js: 'never',
+          jsx: 'never',
+          ts: 'never',
+          tsx: 'never',
+          mjs: 'never',
+          json: 'always',
+          svg: 'always',
+          graphql: 'always',
+        },
       ],
-      rules: {
-        ...craRules.jest,
-
-        // React
-        'react/display-name': statusCode.off,
-
-        // Jest
-        'jest/expect-expect': statusCode.off,
-        'jest/no-identical-title': statusCode.warn,
-        'jest/no-focused-tests': statusCode.error,
-
-        // RTL
-        'testing-library/prefer-presence-queries': statusCode.error,
-        'testing-library/await-async-query': statusCode.error,
-        // Enabling these would be a breaking change to the config
-        'testing-library/render-result-naming-convention': statusCode.off,
-        'testing-library/prefer-screen-queries': statusCode.off,
-        'testing-library/no-container': statusCode.warn,
-      },
+      'import/default': statusCode.off,
+      'import/first': statusCode.error,
+      'import/namespace': statusCode.off,
+      'import/no-extraneous-dependencies': statusCode.off,
+      'import/no-named-as-default': statusCode.off,
+      'import/no-named-as-default-member': statusCode.off,
+      'import/no-unresolved': statusCode.error,
+      'prettier/prettier': 'error',
     },
-    {
-      files: ['**/*.{ts,tsx}'],
-      parser: '@typescript-eslint/parser',
+  },
+
+  // TypeScript files (non-React)
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parser: typescriptParser,
       parserOptions: {
         ecmaVersion: 2018,
         sourceType: 'module',
-        // typescript-eslint specific options
         warnOnUnsupportedTypeScriptVersion: true,
       },
-      plugins: ['@typescript-eslint'],
-      extends: ['prettier'],
-      rules: {
-        ...craRules.typescript,
-
-        // TypeScript
-        '@typescript-eslint/ban-types': statusCode.off,
-        '@typescript-eslint/naming-convention': statusCode.off,
-        '@typescript-eslint/consistent-type-definitions': statusCode.off,
-        '@typescript-eslint/no-explicit-any': statusCode.error,
-        '@typescript-eslint/no-use-before-define': [
-          statusCode.error,
-          { functions: false },
-        ],
-        '@typescript-eslint/no-var-requires': statusCode.off,
-        '@typescript-eslint/unbound-method': statusCode.off,
-        '@typescript-eslint/ban-ts-comment': statusCode.off,
-        '@typescript-eslint/explicit-function-return-type': statusCode.off,
-        '@typescript-eslint/explicit-member-accessibility': [
-          statusCode.error,
-          { accessibility: 'no-public' },
-        ],
-        '@typescript-eslint/no-require-imports': statusCode.off,
-        '@typescript-eslint/promise-function-async': statusCode.off,
+    },
+    plugins: {
+      '@typescript-eslint': typescriptPlugin,
+      'react-hooks': reactHooksPlugin,
+    },
+    settings: {
+      'import/parsers': {
+        '@typescript-eslint/parser': ['.ts', '.tsx'],
       },
-      settings: {
-        'import/parsers': {
-          '@typescript-eslint/parser': ['.js', '.jsx', '.ts', '.tsx'],
+      'import/resolver': {
+        typescript: {
+          alwaysTryTypes: true,
         },
-        'import/resolver': {
-          'eslint-import-resolver-typescript': true,
-          typescript: {},
-          node: {
-            extensions: allSupportedExtensions,
-          },
+        node: {
+          extensions: allSupportedExtensions,
         },
       },
     },
-    {
-      files: ['**/*.{js,jsx,tsx}'],
-      extends: [
-        // https://github.com/yannickcr/eslint-plugin-react
-        'plugin:react/recommended',
+    rules: {
+      ...craRules.typescript,
+      '@typescript-eslint/ban-types': statusCode.off,
+      '@typescript-eslint/naming-convention': statusCode.off,
+      '@typescript-eslint/consistent-type-definitions': statusCode.off,
+      '@typescript-eslint/no-explicit-any': statusCode.error,
+      '@typescript-eslint/no-use-before-define': [
+        statusCode.error,
+        { functions: false },
       ],
-      plugins: [
-        // https://github.com/yannickcr/eslint-plugin-react
-        'react',
-        // https://github.com/facebook/react/tree/main/packages/eslint-plugin-react-hooks
-        'react-hooks',
+      '@typescript-eslint/no-var-requires': statusCode.off,
+      '@typescript-eslint/unbound-method': statusCode.off,
+      '@typescript-eslint/ban-ts-comment': statusCode.off,
+      '@typescript-eslint/explicit-function-return-type': statusCode.off,
+      '@typescript-eslint/explicit-member-accessibility': [
+        statusCode.error,
+        { accessibility: 'no-public' },
       ],
-      rules: {
-        // React
-        'react/jsx-uses-vars': statusCode.error,
-        'react/no-deprecated': statusCode.error,
-        'react/no-unused-prop-types': statusCode.error,
-        ...(hasJsxRuntime() && {
-          'react/jsx-uses-react': statusCode.off,
-          'react/react-in-jsx-scope': statusCode.off,
-        }),
-        'react/no-unknown-property': [
-          statusCode.error,
-          {
-            ignore: [
-              // To allow using Emotion's `css` prop: https://emotion.sh/docs/css-prop
-              'css',
-            ],
-          },
-        ],
+      '@typescript-eslint/no-require-imports': statusCode.off,
+      '@typescript-eslint/promise-function-async': statusCode.off,
+      'react-hooks/rules-of-hooks': 'error',
+      'react-hooks/exhaustive-deps': 'warn',
+    },
+  },
+
+  // React/JSX files (JavaScript)
+  {
+    files: ['**/*.{js,jsx}'],
+    plugins: {
+      react: reactPlugin,
+      'react-hooks': reactHooksPlugin,
+    },
+    settings: {
+      react: {
+        version: 'detect',
       },
-      settings: {
-        react: {
-          version: 'detect',
+    },
+    rules: {
+      'react/jsx-uses-vars': statusCode.error,
+      'react/no-deprecated': statusCode.error,
+      'react/no-unused-prop-types': statusCode.error,
+      ...(hasJsxRuntime() && {
+        'react/jsx-uses-react': statusCode.off,
+        'react/react-in-jsx-scope': statusCode.off,
+      }),
+      'react/no-unknown-property': [
+        statusCode.error,
+        {
+          ignore: ['css'], // Emotion's css prop
         },
-      },
+      ],
+      'react-hooks/rules-of-hooks': 'error',
+      'react-hooks/exhaustive-deps': 'warn',
     },
-    {
-      files: ['**/*.tsx'],
-      parser: '@typescript-eslint/parser',
+  },
+
+  // TypeScript + React files (TSX)
+  {
+    files: ['**/*.tsx'],
+    languageOptions: {
+      parser: typescriptParser,
       parserOptions: {
+        ecmaVersion: 2018,
+        sourceType: 'module',
+        warnOnUnsupportedTypeScriptVersion: true,
         ecmaFeatures: {
           jsx: true,
         },
       },
-      rules: {
-        // React
-        'react/no-unused-prop-types': statusCode.off,
-        'react/prop-types': statusCode.off,
+    },
+    plugins: {
+      '@typescript-eslint': typescriptPlugin,
+      react: reactPlugin,
+      'react-hooks': reactHooksPlugin,
+    },
+    settings: {
+      react: {
+        version: 'detect',
+      },
+      'import/parsers': {
+        '@typescript-eslint/parser': ['.ts', '.tsx'],
+      },
+      'import/resolver': {
+        typescript: {
+          alwaysTryTypes: true,
+        },
+        node: {
+          extensions: allSupportedExtensions,
+        },
       },
     },
-    {
-      files: [
-        '.custom-application-config.{js,cjs,mjs,ts}',
-        'custom-application-config.{js,cjs,mjs,ts}',
+    rules: {
+      ...craRules.typescript,
+      '@typescript-eslint/ban-types': statusCode.off,
+      '@typescript-eslint/naming-convention': statusCode.off,
+      '@typescript-eslint/consistent-type-definitions': statusCode.off,
+      '@typescript-eslint/no-explicit-any': statusCode.error,
+      '@typescript-eslint/no-use-before-define': [
+        statusCode.error,
+        { functions: false },
       ],
-      rules: {
-        'no-template-curly-in-string': statusCode.off,
+      '@typescript-eslint/no-var-requires': statusCode.off,
+      '@typescript-eslint/unbound-method': statusCode.off,
+      '@typescript-eslint/ban-ts-comment': statusCode.off,
+      '@typescript-eslint/explicit-function-return-type': statusCode.off,
+      '@typescript-eslint/explicit-member-accessibility': [
+        statusCode.error,
+        { accessibility: 'no-public' },
+      ],
+      '@typescript-eslint/no-require-imports': statusCode.off,
+      '@typescript-eslint/promise-function-async': statusCode.off,
+      'react/jsx-uses-vars': statusCode.error,
+      'react/no-deprecated': statusCode.error,
+      'react/no-unused-prop-types': statusCode.off,
+      'react/prop-types': statusCode.off,
+      ...(hasJsxRuntime() && {
+        'react/jsx-uses-react': statusCode.off,
+        'react/react-in-jsx-scope': statusCode.off,
+      }),
+      'react/no-unknown-property': [
+        statusCode.error,
+        {
+          ignore: ['css'],
+        },
+      ],
+      'react-hooks/rules-of-hooks': 'error',
+      'react-hooks/exhaustive-deps': 'warn',
+    },
+  },
+
+  // Test files (all)
+  {
+    files: ['**/*.{spec,test}.{js,jsx,ts,tsx}'],
+    languageOptions: {
+      globals: {
+        ...globals.jest,
       },
     },
-  ],
-};
+    plugins: {
+      jest: jestPlugin,
+      'jest-dom': jestDomPlugin,
+      'testing-library': testingLibraryPlugin,
+    },
+    rules: {
+      ...craRules.jest,
+      'react/display-name': statusCode.off,
+      'jest/expect-expect': statusCode.off,
+      'jest/no-identical-title': statusCode.warn,
+      'jest/no-focused-tests': statusCode.error,
+      'testing-library/prefer-presence-queries': statusCode.error,
+      'testing-library/await-async-queries': statusCode.error,
+      'testing-library/render-result-naming-convention': statusCode.off,
+      'testing-library/prefer-screen-queries': statusCode.off,
+      'testing-library/no-container': statusCode.warn,
+    },
+  },
+
+  // Test utility files (e.g., test-utils.tsx, test-helpers.tsx)
+  // These files aren't named *.spec.* or *.test.* but contain testing code
+  // and use inline eslint-disable comments for testing-library rules
+  {
+    files: [
+      '**/test-utils/**/*.{jsx,tsx}',
+      '**/*test-utils.{jsx,tsx}',
+      '**/*test-helpers.{jsx,tsx}',
+    ],
+    languageOptions: {
+      globals: {
+        ...globals.jest,
+      },
+    },
+    plugins: {
+      jest: jestPlugin,
+      'jest-dom': jestDomPlugin,
+      'testing-library': testingLibraryPlugin,
+      react: reactPlugin,
+      'react-hooks': reactHooksPlugin,
+    },
+    rules: {
+      'react/display-name': statusCode.off,
+      'testing-library/render-result-naming-convention': statusCode.off,
+      'testing-library/no-node-access': statusCode.warn,
+      'react-hooks/exhaustive-deps': 'warn',
+    },
+  },
+
+  // Custom application config files
+  {
+    files: [
+      '.custom-application-config.{js,cjs,mjs,ts}',
+      'custom-application-config.{js,cjs,mjs,ts}',
+    ],
+    rules: {
+      'no-template-curly-in-string': statusCode.off,
+    },
+  },
+
+  // Prettier must be last to override formatting rules
+  prettierConfig,
+];

package/migrations/v27.md

@@ -0,0 +1,328 @@
+# Migrating to ESLint 9 Flat Config
+
+This guide covers migrating from ESLint 8 (legacy `.eslintrc` format) to ESLint 9 (flat config) for projects using `@commercetools-frontend/eslint-config-mc-app`.
+
+> **AI agents**: This document is structured as step-by-step instructions that can be followed automatically. Read the existing config files before generating new ones.
+
+## Key concept: no more config cascading
+
+In legacy ESLint, `.eslintrc.*` files in subdirectories automatically merged with parent configs. **Flat config does not cascade.** ESLint 9 reads only the root `eslint.config.js`. Any `.eslintrc.*` files in subdirectories are silently ignored.
+
+This means every subdirectory `.eslintrc.*` must be explicitly migrated into the root config (or into files imported by the root config). Missing this is the most common migration mistake — your subdirectory rules will silently stop being enforced.
+
+## Step 1: Discover and analyze existing config
+
+Find **all** ESLint-related files in the project:
+
+```bash
+find . -name '.eslintrc*' -not -path '*/node_modules/*'
+find . -name '.eslintignore' -not -path '*/node_modules/*'
+```
+
+For **each** `.eslintrc.*` file found (root and subdirectories), extract: `extends`, `plugins`, `rules`, `overrides` (with their `files`, `excludedFiles`, `parser`, `parserOptions`, `plugins`, `rules`), `env`, `globals`, `settings`, and any `process.env` assignments before `module.exports`. Also collect `.eslintignore` patterns and note `"type": "module"` fields in `package.json`.
+
+**Legacy cascade behavior**: A child config completely replaces the parent's value for the same rule key (e.g., if root sets `no-restricted-imports` with `paths` and a subdirectory sets it with `patterns`, the subdirectory version wins entirely). Replicate this override behavior in flat config.
+
+## Step 2: Plan subdirectory config strategy
+
+If subdirectory `.eslintrc.*` files were found, **ask the user which approach they prefer**:
+
+### Option A: Subdirectory files imported by root (recommended for monorepos)
+
+Each subdirectory exports a flat config array with **root-relative** `files` patterns. The root imports and spreads them.
+
+```js
+// packages/my-app/src/eslint.config.cjs
+module.exports = [
+  {
+    files: ['packages/my-app/src/**/*.{js,jsx,ts,tsx}'],
+    rules: { 'my-rule': 'error' },
+  },
+];
+```
+
+```js
+// eslint.config.js (root)
+const myAppConfig = require('./packages/my-app/src/eslint.config.cjs');
+module.exports = [...mcAppConfig, ...myAppConfig];
+```
+
+> **Use `.cjs` extension** for subdirectory config files. If any package has `"type": "module"` in its `package.json`, a `.js` file will be treated as ESM and `module.exports` will fail.
+
+### Option B: Inline in root config
+
+All rules defined directly in root `eslint.config.js` with directory-scoped `files` patterns. Simpler for small projects.
+
+## Step 3: Create `eslint.config.js`
+
+### Base structure
+
+```js
+// Preserve any process.env assignments from the old config
+process.env.ENABLE_NEW_JSX_TRANSFORM = 'true';
+
+// Plugins are now imported as objects, not strings
+const somePlugin = require('some-eslint-plugin');
+const mcAppConfig = require('@commercetools-frontend/eslint-config-mc-app');
+
+module.exports = [
+  // Ignores replace .eslintignore (directory patterns end with /)
+  { ignores: ['dist/', 'build/'] },
+
+  // Spread the base config (replaces "extends")
+  ...mcAppConfig,
+
+  // Top-level rule overrides become a config object after the spread
+  {
+    files: ['**/*.{js,jsx,ts,tsx}'],
+    rules: { 'no-console': 'warn' },
+  },
+];
+```
+
+### Converting `plugins`
+
+Plugins registered as strings become imported objects:
+
+```js
+// Before: plugins: ['@graphql-eslint']
+// After:
+const graphqlPlugin = require('@graphql-eslint/eslint-plugin');
+// plugins: { '@graphql-eslint': graphqlPlugin }
+```
+
+### Converting `overrides`
+
+Each `overrides` entry becomes a separate object in the config array:
+
+```js
+// Before (legacy):
+overrides: [{ files: ['**/*.graphql'], parser: '@graphql-eslint/eslint-plugin',
+  parserOptions: { graphQLConfig: { schema: './schema.json' } },
+  rules: { '@graphql-eslint/known-type-names': 'error' } }]
+
+// After (flat config):
+{
+  files: ['**/*.graphql'],
+  plugins: { '@graphql-eslint': graphqlPlugin },
+  languageOptions: {
+    parser: graphqlPlugin,
+    parserOptions: { graphQLConfig: { schema: './schema.json' } },
+  },
+  rules: { '@graphql-eslint/known-type-names': 'error' },
+}
+```
+
+> **Glob patterns must include `**/`for subdirectory matching.** In legacy config,`files: ['*.foo.js']`matched anywhere. In flat config, it only matches the root directory. Always prefix with`\*\*/`.
+
+### Key property mappings
+
+| Legacy (`.eslintrc`)               | Flat config (`eslint.config.js`)                          |
+| ---------------------------------- | --------------------------------------------------------- |
+| `parser` (string)                  | `languageOptions.parser` (imported module)                |
+| `parserOptions`                    | `languageOptions.parserOptions`                           |
+| `env: { browser: true }`           | `languageOptions.globals` (use the `globals` npm package) |
+| `globals: { myVar: 'readonly' }`   | `languageOptions.globals: { myVar: 'readonly' }`          |
+| `plugins: ['name']` (string array) | `plugins: { name: importedPlugin }` (object)              |
+| `excludedFiles`                    | `ignores` (within the same config object)                 |
+
+### Plugin scoping: matching rules to file types
+
+**Critical difference from legacy ESLint.** In flat config, plugins are only registered for files matching the config object's `files` pattern. Setting a rule from an unregistered plugin causes an error. Split rule overrides by plugin scope.
+
+The base `mcAppConfig` registers plugins for:
+
+| Plugin               | Registered for                   |
+| -------------------- | -------------------------------- |
+| `react`              | `*.js`, `*.jsx`, `*.tsx`         |
+| `react-hooks`        | `*.js`, `*.jsx`, `*.ts`, `*.tsx` |
+| `@typescript-eslint` | `*.ts`, `*.tsx`                  |
+| `jest`               | `*.spec.*`, `*.test.*`           |
+| `testing-library`    | `*.spec.*`, `*.test.*`           |
+
+If your override mixes rules from different plugins, split into separate config objects matching each plugin's file types (e.g., `react/` rules in `**/*.{js,jsx,tsx}`, `@typescript-eslint/` rules in `**/*.{ts,tsx}`, core rules in `**/*.{js,jsx,ts,tsx}`).
+
+#### Common mistake: catch-all file patterns with mixed plugin rules
+
+The natural instinct when converting a subdirectory `.eslintrc.cjs` is to put all the rules into a single config object targeting `**/*.{js,jsx,ts,tsx}`. This will fail because not every plugin is registered for every file type.
+
+```js
+// WRONG — will error on .ts files because `react` plugin is not registered for them
+{
+  files: ['packages/my-app/src/**/*.{js,jsx,ts,tsx}'],
+  rules: {
+    'no-console': 'warn',                                 // core — works on all
+    'react/jsx-sort-props': 'error',                       // react — NOT on .ts
+    '@typescript-eslint/consistent-type-imports': 'error', // ts — NOT on .js/.jsx
+  },
+}
+```
+
+Split into separate config objects, each matching the plugin's registered file types:
+
+```js
+// Core ESLint rules — all source files
+{
+  files: ['packages/my-app/src/**/*.{js,jsx,ts,tsx}'],
+  rules: { 'no-console': 'warn' },
+},
+// React rules — only file types where the react plugin is registered
+{
+  files: ['packages/my-app/src/**/*.{js,jsx,tsx}'],
+  rules: { 'react/jsx-sort-props': 'error' },
+},
+// TypeScript rules — only .ts and .tsx
+{
+  files: ['packages/my-app/src/**/*.{ts,tsx}'],
+  rules: { '@typescript-eslint/consistent-type-imports': 'error' },
+},
+```
+
+> **Tip**: When converting an existing `.eslintrc.cjs`, group its rules by which plugin they belong to, then create one config object per plugin group with the correct `files` pattern. Core ESLint rules (no plugin prefix) can target all file types.
+
+#### Common mistake: `no-unused-vars` duplication on TypeScript files
+
+The base `mcAppConfig` disables core `no-unused-vars` on `.ts`/`.tsx` files and replaces it with `@typescript-eslint/no-unused-vars`. If your subdirectory config re-enables the core `no-unused-vars` for all file types, both rules will fire on TypeScript files, producing duplicate errors.
+
+```js
+// WRONG — re-enables core no-unused-vars on .ts/.tsx where @typescript-eslint
+// version is already active from the base config
+{
+  files: ['packages/my-app/src/**/*.{js,jsx,ts,tsx}'],
+  rules: { 'no-unused-vars': 'error' },
+}
+```
+
+Scope core `no-unused-vars` overrides to JavaScript files only:
+
+```js
+// CORRECT — only overrides the core rule on files where it applies
+{
+  files: ['packages/my-app/src/**/*.{js,jsx}'],
+  rules: { 'no-unused-vars': 'error' },
+}
+```
+
+### Self-linting the config file
+
+The root `eslint.config.js` is itself a `.js` file in your project, so ESLint will lint it. Rules like `import/extensions` may error on `.cjs` requires. Add a self-override to avoid this:
+
+```js
+{
+  files: ['eslint.config.js'],
+  rules: { 'import/extensions': 'off' },
+},
+```
+
+## Step 4: Update `package.json`
+
+```diff
+- "eslint": "8.57.1",
++ "eslint": "^9.0.0",
+
+- "@commercetools-frontend/eslint-config-mc-app": "^25.0.0",
++ "@commercetools-frontend/eslint-config-mc-app": "^27.0.0",
+```
+
+Remove `@rushstack/eslint-patch` — not needed in flat config.
+
+### Update custom ESLint plugins
+
+If you maintain custom ESLint rule plugins, update deprecated APIs:
+
+| Deprecated (ESLint 8)     | Replacement (ESLint 9)      |
+| ------------------------- | --------------------------- |
+| `context.getFilename()`   | `context.filename`          |
+| `context.getSourceCode()` | `context.sourceCode`        |
+| `context.getScope()`      | `sourceCode.getScope()`     |
+| `context.getAncestors()`  | `sourceCode.getAncestors()` |
+| `context.getCwd()`        | `context.cwd`               |
+
+Also update the plugin's `peerDependencies` to `"eslint": "9.x"`.
+
+### `jest-runner-eslint` compatibility
+
+If using `jest-runner-eslint`, note that the `rules` key in `cliOptions` is not supported in flat config mode — move those rule overrides into `eslint.config.js` instead. You may also need a `pnpm.overrides` (or npm `overrides`) entry if the package's peer dependency still specifies ESLint 8:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "jest-runner-eslint>eslint": "^9.0.0"
+    }
+  }
+}
+```
+
+If the formatter path uses a bare directory import (e.g., `node_modules/eslint-formatter-pretty`), ESM module resolution will reject it. Change to an explicit file path:
+
+```diff
+- format: 'node_modules/eslint-formatter-pretty',
++ format: 'node_modules/eslint-formatter-pretty/index.js',
+```
+
+## Step 5: Clean up
+
+- Delete **all** `.eslintrc.*` files (root and subdirectories)
+- Delete `.eslintignore`
+- Verify: `find . -name '.eslintrc*' -not -path '*/node_modules/*'`
+
+## Step 6: Verify
+
+Run eslint on at least one file from **each directory that had its own config**. Check for:
+
+- **Configuration errors** — fix the generated `eslint.config.js`
+- **New lint violations** from dependency upgrades:
+  - `@typescript-eslint` v5→v8 (stricter type checking)
+  - `eslint-plugin-jest` v27→v28 (new rules)
+  - `eslint-plugin-react-hooks` v4→v5 (improved detection; rules now also apply to `*.ts` — custom hooks in `.ts` files may surface new warnings)
+  - `eslint-plugin-testing-library` v5→v7 (new best practices)
+
+## Troubleshooting
+
+**"Definition for rule 'plugin/rule-name' was not found"**: This means a rule is referenced on a file type where its plugin isn't registered. Two common causes:
+
+1. **Config rules targeting wrong file types** — your subdirectory config has a catch-all `files` pattern like `**/*.{js,jsx,ts,tsx}` but includes rules from a plugin that isn't registered for all of those types. See "Plugin scoping" above for how to split by plugin.
+2. **Stale inline `eslint-disable` comments** — ESLint 8 silently ignored `eslint-disable` comments referencing rules from unregistered plugins. ESLint 9 treats them as errors. This surfaces pre-existing stale comments that were previously harmless (e.g., `// eslint-disable-next-line testing-library/no-render-in-setup` in a file that isn't matched by the `testing-library` plugin's file pattern, or `@typescript-eslint/...` in a `.js` file). **Fix**: remove the stale disable comment, or if the rule should apply, register the plugin for that file type.
+
+**"ReferenceError: module is not defined in ES module scope"**: Config file uses `module.exports` but nearest `package.json` has `"type": "module"`. **Fix**: rename to `.cjs` extension and update imports.
+
+**Jest globals (`describe`, `it`, `expect`) not defined**: The base config only injects Jest globals for `**/*.{spec,test}.*`. Other files that use Jest APIs need explicit globals. Common patterns that are easy to miss:
+
+- `__mocks__/` directories (at any depth)
+- `test-utils/` directories (helper modules used by tests)
+
+Add a config block for these:
+
+```js
+{
+  files: [
+    '**/__mocks__/**/*.{js,jsx,ts,tsx}',
+    '**/test-utils/**/*.{js,jsx,ts,tsx}',
+  ],
+  languageOptions: {
+    globals: {
+      jest: 'readonly',
+      expect: 'readonly',
+    },
+  },
+},
+```
+
+> **Note**: Use `**/__mocks__/**` (with leading `**/`), not `__mocks__/**`. The latter only matches a `__mocks__/` directory at the project root. Most projects have `__mocks__/` directories nested inside packages or `src/` directories.
+
+**Duplicate `no-unused-vars` errors on `.ts`/`.tsx` files**: The base config sets `@typescript-eslint/no-unused-vars` for TypeScript files and disables the core `no-unused-vars` there. If your subdirectory config re-enables `no-unused-vars` for `**/*.{js,jsx,ts,tsx}`, both rules fire on TypeScript files. **Fix**: scope `no-unused-vars` overrides to `**/*.{js,jsx}` only. See "Common mistake" above.
+
+**Lint errors in `eslint.config.js` itself**: The config file is a `.js` file in the project root, so ESLint lints it. Rules like `import/extensions` may error on `.cjs` requires. **Fix**: add a self-override: `{ files: ['eslint.config.js'], rules: { 'import/extensions': 'off' } }`.
+
+**"Cannot find module 'some-eslint-plugin'"**: Plugins must be installed as direct dependencies in flat config.
+
+**"context.getScope is not a function"**: Incompatible plugin version. Update to the latest major version supporting ESLint 9.
+
+**Lint violations in test files**: The testing-library plugin v7 is stricter. Common issues: `testing-library/no-node-access` (use `fireEvent.click()` instead of `.click()`) and `testing-library/no-wait-for-side-effects` (only assertions belong in `waitFor()`).
+
+## Additional resources
+
+- [ESLint Flat Config Documentation](https://eslint.org/docs/latest/use/configure/configuration-files)
+- [Migration Guide (Official ESLint)](https://eslint.org/docs/latest/use/configure/migration-guide)
+- [TypeScript ESLint v8 Release Notes](https://typescript-eslint.io/blog/announcing-typescript-eslint-v8)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercetools-frontend/eslint-config-mc-app",
-  "version": "26.1.0",
+  "version": "27.1.0",
   "description": "ESLint config used by Merchant Center customizations.",
   "bugs": "https://github.com/commercetools/merchant-center-application-kit/issues",
   "repository": {
@@ -23,30 +23,30 @@
   "dependencies": {
     "@babel/core": "^7.22.17",
     "@babel/eslint-parser": "^7.22.15",
-    "@commercetools-frontend/babel-preset-mc-app": "^26.1.0",
-    "@rushstack/eslint-patch": "^1.3.3",
-    "@typescript-eslint/eslint-plugin": "^5.62.0",
-    "@typescript-eslint/parser": "^5.62.0",
+    "@commercetools-frontend/babel-preset-mc-app": "^27.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.55.0",
+    "@typescript-eslint/parser": "^8.55.0",
     "confusing-browser-globals": "^1.0.11",
     "eslint-config-prettier": "^8.10.0",
     "eslint-import-resolver-typescript": "^3.6.0",
     "eslint-plugin-cypress": "^2.14.0",
     "eslint-plugin-import": "^2.28.1",
-    "eslint-plugin-jest": "^27.2.3",
+    "eslint-plugin-jest": "^28.0.0",
     "eslint-plugin-jest-dom": "^4.0.3",
     "eslint-plugin-jsx-a11y": "^6.7.1",
     "eslint-plugin-prettier": "^4.2.1",
     "eslint-plugin-react": "^7.33.2",
-    "eslint-plugin-react-hooks": "^4.6.0",
-    "eslint-plugin-testing-library": "^5.11.1",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "eslint-plugin-testing-library": "^7.15.4",
+    "globals": "^15.15.0",
     "prettier": "^2.8.4",
     "typescript": "^5.2.2"
   },
   "peerDependencies": {
-    "eslint": "8.x"
+    "eslint": "^9.0.0"
   },
   "devDependencies": {
-    "eslint": "8.57.1"
+    "eslint": "^9.0.0"
   },
   "engines": {
     "node": "18.x || 20.x || >=22.0.0"