@bitfactory/eslint-config 5.0.5 → 5.1.1

package/README.md

@@ -10,15 +10,17 @@
 This is a shareable config for [ESLint](https://eslint.org). All the rules and configurations are already set. Rules can be overridden if needed.
 
 > [!IMPORTANT]  
-> From ESLint v9 the Flat Config file is the default. Because of this change update the `package.json` npm run scripts!
+> **ESLint v9+ uses Flat Config (ESM) by default.** This package now provides Flat Config entry points (`index.flat.js`, `typescript.flat.js`, `vue.flat.js`) for modern usage. See [:rocket: ESLint v9+ Flat Config Usage](#rocket-eslint-v9-flat-config-usage) for details and examples.
 >
-> See also the Release Roadmap <https://github.com/bitfactory-nl/shared-npm-eslint-config-bitfactory/issues/83>
+> **Legacy CJS configs are still supported** for backward compatibility. If you use the legacy `.eslintrc.js` approach, you must set the environment variable `ESLINT_USE_FLAT_CONFIG=false` in your npm scripts. See [:rocket: CLI usage](#rocket-cli-usage) for examples.
 >
-> For now the `eslint` scripts can only be run with the `ESLINT_USE_FLAT_CONFIG=false` environment variable set like this. For examples how to add this to the `package.json`, please check out the [CLI usage documentation](#rocket-cli-usage).
+> Choose the method that matches your ESLint version and project setup. Legacy will be deprecated in a next major version.
+> See also the Release Roadmap <https://github.com/bitfactory-nl/shared-npm-eslint-config-bitfactory/issues/83>
 
 - [@bitfactory/eslint-config](#bitfactoryeslint-config)
   - [:technologist: Development](#technologist-development)
     - [Publishing](#publishing)
+    - [Local Development Configs](#local-development-configs)
   - [:package: Installing](#package-installing)
     - [Vue.js projects](#vuejs-projects)
     - [TypeScript projects](#typescript-projects)
@@ -28,6 +30,12 @@ This is a shareable config for [ESLint](https://eslint.org). All the rules and c
     - [Visual Studio Code](#visual-studio-code)
       - [Additional Extensions](#additional-extensions)
     - [PhpStorm](#phpstorm)
+  - [:rocket: ESLint v9+ Flat Config Usage](#rocket-eslint-v9-flat-config-usage)
+    - [Flat Config Entry Points](#flat-config-entry-points)
+    - [Example: Using Only the Base Config](#example-using-only-the-base-config)
+    - [Example: TypeScript Project](#example-typescript-project)
+    - [Example: Vue Project](#example-vue-project)
+    - [Example: Combined Vue + TypeScript + JS](#example-combined-vue--typescript--js)
 
 ## :technologist: Development
 
@@ -42,6 +50,27 @@ Before publishing a new version:
 
 > **For detailed automation and release rules, see the [Bitfactory NPM Package Automation Rules](.cursor/rules/npm-package-shared.mdc).**
 
+### Local Development Configs
+
+> The files `.eslintrc.cjs` and `eslint.config.js` are provided for local development and testing only. They are not included in the published npm package and are not intended for consumer use. Consumers of this package should use the shareable config files (`index.(m)js`, `typescript.(m)js`, `vue.(m)js`, etc.) as described in the usage instructions.
+
+### Debugging ESLint Configuration
+
+For debugging ESLint configuration issues, rule conflicts, or understanding config behavior, use the official ESLint Config Inspector:
+
+```bash
+npx @eslint/config-inspector
+```
+
+**Use cases:**
+
+- Debug rule conflicts and understand which rules are active
+- Visualize how configs apply to different file patterns
+- Help consumers troubleshoot configuration issues
+- Generate visual documentation of rule sets
+
+The inspector provides a web interface showing all active rules, plugins, and file matching patterns for your ESLint configuration.
+
 ## :package: Installing
 
 Include the config into your project:
@@ -154,6 +183,10 @@ module.exports = {
 
 ## :rocket: CLI usage
 
+> [!WARNING]
+> **You only need to set `ESLINT_USE_FLAT_CONFIG=false` in your scripts if you are using the legacy config (`.eslintrc.js`).**
+> For Flat Config (`eslint.config.js` and `*.flat.js`), do not set this variable—ESLint v9+ uses Flat Config by default.
+
 To use ESLint in the command-line, add the following scripts to your projects `package.json`:
 
 ```json
@@ -289,3 +322,66 @@ Or import the following xml file:
     </TaskOptions>
 </TaskOptions>
 ```
+
+## :rocket: ESLint v9+ Flat Config Usage
+
+> [!IMPORTANT]
+> ESLint v9+ uses Flat Config by default. This package now provides ESM-based Flat Config entry points for modern usage, while legacy CJS configs remain for backward compatibility.
+
+### Flat Config Entry Points
+
+- **Base JS config:** `index.flat.js`
+- **TypeScript config:** `typescript.flat.js`
+- **Vue config:** `vue.flat.js`
+
+### Example: Using Only the Base Config
+
+Create an `eslint.config.js` in your project root:
+
+```js
+import base from '@bitfactory/eslint-config/index.flat.js';
+
+export default [
+  ...base,
+];
+```
+
+### Example: TypeScript Project
+
+```js
+import base from '@bitfactory/eslint-config/index.flat.js';
+import ts from '@bitfactory/eslint-config/typescript.flat.js';
+
+export default [
+  ...base,
+  ...ts,
+];
+```
+
+### Example: Vue Project
+
+```js
+import base from '@bitfactory/eslint-config/index.flat.js';
+import vue from '@bitfactory/eslint-config/vue.flat.js';
+
+export default [
+  ...base,
+  ...vue,
+];
+```
+
+### Example: Combined Vue + TypeScript + JS
+
+```js
+import base from '@bitfactory/eslint-config/index.flat.js';
+import ts from '@bitfactory/eslint-config/typescript.flat.js';
+import vue from '@bitfactory/eslint-config/vue.flat.js';
+
+export default [
+  ...base,
+  ...ts,
+  ...vue,
+];
+```
+
+> You can combine these configs as needed, just like with the legacy CJS configs. Only import the ones you need for your project.

package/index.flat.js

@@ -0,0 +1,95 @@
+// ESLint Flat Config for @bitfactory/eslint-config
+// This file is for ESLint v9+ flat config support. The legacy config files remain for backward compatibility.
+
+import js from '@eslint/js';
+import stylistic from '@stylistic/eslint-plugin';
+import jsdoc from 'eslint-plugin-jsdoc';
+import unicorn from 'eslint-plugin-unicorn';
+import importPlugin from 'eslint-plugin-import';
+import babelParser from '@babel/eslint-parser';
+import globals from 'globals';
+
+import { errorsRules } from './rules/errors.flat.js';
+import { es6Rules } from './rules/es6.flat.js';
+import { jsdocRules } from './rules/jsdoc.flat.js';
+import { practicesRules } from './rules/practices.flat.js';
+import { styleRules } from './rules/style.flat.js';
+import { stylisticRules } from './rules/stylistic.flat.js';
+import { variablesRules } from './rules/variables.flat.js';
+
+export default [
+    {
+        ignores: [
+            '!.stylelintrc.js',
+            '/.nuxt/**',
+            '/dist/**',
+            '/static/sw.*',
+        ],
+    },
+    stylistic.configs['recommended-flat'],
+    {
+        files: ['**/*.{js,mjs}'],
+        languageOptions: {
+            ecmaVersion: 2021,
+            sourceType: 'module',
+            parser: babelParser,
+            parserOptions: {
+                requireConfigFile: false,
+            },
+            globals: {
+                ...globals.node,
+                ...globals.browser,
+            },
+        },
+        plugins: {
+            '@stylistic': stylistic,
+            jsdoc,
+            unicorn,
+            'import': importPlugin,
+        },
+        rules: {
+            ...js.configs.recommended.rules,
+            ...jsdocRules,
+            ...unicorn.configs.recommended.rules,
+            ...errorsRules,
+            ...es6Rules,
+            ...practicesRules,
+            ...styleRules,
+            ...stylisticRules,
+            ...variablesRules,
+        },
+    },
+    // .cjs files must always be parsed as scripts
+    {
+        files: ['**/*.cjs'],
+        languageOptions: {
+            ecmaVersion: 2021,
+            sourceType: 'script',
+            parser: babelParser,
+            parserOptions: {
+                requireConfigFile: false,
+            },
+            globals: {
+                ...globals.node,
+                ...globals.browser,
+            },
+        },
+        plugins: {
+            '@stylistic': stylistic,
+            jsdoc,
+            unicorn,
+            'import': importPlugin,
+        },
+        rules: {
+            ...js.configs.recommended.rules,
+            ...jsdocRules,
+            ...unicorn.configs.recommended.rules,
+            ...errorsRules,
+            ...es6Rules,
+            ...practicesRules,
+            ...styleRules,
+            ...stylisticRules,
+            ...variablesRules,
+        },
+    },
+];

package/index.js

@@ -26,6 +26,15 @@ module.exports = {
         '/static/sw.*',
     ],
     overrides: [
+        {
+            files: ['**/*.cjs'],
+            env: {
+                node: true,
+            },
+            parserOptions: {
+                sourceType: 'script',
+            },
+        },
         {
             files: ['**/*.js'],
             parser: '@babel/eslint-parser',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitfactory/eslint-config",
-  "version": "5.0.5",
+  "version": "5.1.1",
   "description": "ESLint sharable config for Bitfactory projects",
   "keywords": [
     "eslint",
@@ -13,9 +13,12 @@
   "files": [
     "rules",
     "index.js",
-    "README.md",
+    "index.flat.js",
     "typescript.js",
-    "vue.js"
+    "typescript.flat.js",
+    "vue.js",
+    "vue.flat.js",
+    "README.md"
   ],
   "devDependencies": {
     "eslint": "9.29.0",
@@ -30,16 +33,19 @@
     "eslint": "^8.56.0 || ^9.0.0",
     "eslint-plugin-import": ">=2.31.0",
     "eslint-plugin-jsdoc": ">=47.0.0",
-    "eslint-plugin-unicorn": ">=56.0.1 <57.0.0"
+    "eslint-plugin-unicorn": ">=56.0.1 <57.0.0",
+    "globals": ">=16.2.0"
   },
   "engines": {
     "node": "^20.9.0 || ^22.11.0"
   },
   "scripts": {
-    "eslint": "ESLINT_USE_FLAT_CONFIG=false eslint '**/*.{cjs,js,mjs}'",
+    "eslint": "eslint '**/*.{cjs,js,mjs}'",
     "eslint:fix": "pnpm run eslint --fix",
-    "lint": "pnpm run eslint",
-    "lint:fix": "pnpm run eslint:fix",
+    "eslint:legacy": "ESLINT_USE_FLAT_CONFIG=false eslint -c .eslintrc.cjs '**/*.{cjs,js,mjs}' --ignore-pattern '**/*.flat.js' --ignore-pattern 'eslint.config.js'",
+    "eslint:legacy:fix": "pnpm run eslint:legacy --fix",
+    "lint": "pnpm run eslint && pnpm run eslint:legacy",
+    "lint:fix": "pnpm run eslint:fix && pnpm run eslint:legacy:fix",
     "update:interactive": "pnpm exec npm-check-updates -i",
     "update:minor": "pnpm exec npm-check-updates -i -t minor",
     "update:patch": "pnpm exec npm-check-updates -t patch"

package/rules/errors.flat.js

@@ -0,0 +1,5 @@
+export const errorsRules = {
+    'no-await-in-loop': 'error',
+    'no-console': 'error',
+    'no-template-curly-in-string': 'error',
+};

package/rules/es6.flat.js

@@ -0,0 +1,38 @@
+export const es6Plugins = [
+    'import',
+];
+export const es6Rules = {
+    'arrow-body-style': ['error', 'as-needed'],
+    'import/no-duplicates': ['error'],
+    'no-duplicate-imports': [
+        'error',
+        {
+            includeExports: true,
+        },
+    ],
+    'no-useless-computed-key': 'error',
+    'no-useless-rename': 'error',
+    'no-var': 'error',
+    'object-shorthand': [
+        'error',
+        'always',
+        {
+            avoidQuotes: true,
+            ignoreConstructors: true,
+        },
+    ],
+    'prefer-arrow-callback': 'error',
+    'prefer-const': 'error',
+    'prefer-destructuring': [
+        'error',
+        {
+            array: false,
+            object: true,
+        },
+    ],
+    'prefer-numeric-literals': 'error',
+    'prefer-rest-params': 'error',
+    'prefer-spread': 'error',
+    'prefer-template': 'error',
+    'symbol-description': 'error',
+};

package/rules/jsdoc.flat.js

@@ -0,0 +1,5 @@
+export const jsdocRules = {
+    'jsdoc/check-indentation': 'warn',
+    'jsdoc/check-syntax': 'warn',
+    'jsdoc/match-description': 'warn',
+};

package/rules/practices.flat.js

@@ -0,0 +1,62 @@
+export const practicesRules = {
+    'array-callback-return': 'error',
+    'block-scoped-var': 'error',
+    'complexity': ['error', 10],
+    'consistent-return': 'error',
+    'curly': ['error', 'all'],
+    'dot-notation': 'error',
+    'eqeqeq': 'error',
+    'guard-for-in': 'error',
+    'max-classes-per-file': 'error',
+    'no-alert': 'error',
+    'no-caller': 'error',
+    'no-div-regex': 'error',
+    'no-else-return': 'error',
+    'no-empty-function': 'error',
+    'no-eval': 'error',
+    'no-extend-native': 'error',
+    'no-extra-bind': 'error',
+    'no-extra-label': 'error',
+    'no-implicit-coercion': 'error',
+    'no-implicit-globals': 'error',
+    'no-implied-eval': 'error',
+    'no-iterator': 'error',
+    'no-labels': 'error',
+    'no-lone-blocks': 'error',
+    'no-loop-func': 'error',
+    'no-multi-str': 'error',
+    'no-new-func': 'error',
+    'no-new-wrappers': 'error',
+    'no-octal-escape': 'error',
+    'no-param-reassign': 'error',
+    'no-proto': 'error',
+    'no-return-assign': 'warn',
+    'no-return-await': 'error',
+    'no-script-url': 'error',
+    'no-self-compare': 'error',
+    'no-sequences': 'error',
+    'no-throw-literal': 'error',
+    'no-unmodified-loop-condition': 'error',
+    'no-unused-expressions': 'error',
+    'no-useless-call': 'error',
+    'no-useless-concat': 'error',
+    'no-useless-return': 'error',
+    'no-void': 'error',
+    'no-warning-comments': 'error',
+    'prefer-promise-reject-errors': 'error',
+    'radix': 'error',
+    'require-await': 'error',
+    'unicorn/filename-case': [
+        'error',
+        {
+            cases: {
+                kebabCase: true,
+                pascalCase: true,
+            },
+        },
+    ],
+    'unicorn/no-null': 0,
+    'unicorn/no-reduce': 0,
+    'vars-on-top': 'error',
+    'yoda': 'error',
+};

package/rules/style.flat.js

@@ -0,0 +1,49 @@
+export const styleRules = {
+    'camelcase': 'error',
+    'consistent-this': 'error',
+    'func-name-matching': 'error',
+    'func-names': ['error', 'never'],
+    'func-style': 'error',
+    'max-depth': 'error',
+    'max-lines': 'warn',
+    'max-lines-per-function': [
+        'warn',
+        {
+            skipBlankLines: true,
+            skipComments: true,
+        },
+    ],
+    'max-params': 'error',
+    'max-statements': 'warn',
+    'new-cap': 'error',
+    'no-array-constructor': 'error',
+    'no-lonely-if': 'error',
+    'no-multi-assign': 'error',
+    'no-negated-condition': 'error',
+    'no-new-object': 'error',
+    'no-plusplus': [
+        'error',
+        {
+            allowForLoopAfterthoughts: true,
+        },
+    ],
+    'no-underscore-dangle': [
+        'error',
+        {
+            enforceInMethodNames: true,
+        },
+    ],
+    'no-unneeded-ternary': [
+        'error',
+        {
+            defaultAssignment: false,
+        },
+    ],
+    'one-var': ['error', 'never'],
+    'operator-assignment': 'error',
+    'prefer-object-spread': 'error',
+    'sort-imports': ['error', {
+        ignoreDeclarationSort: true,
+    }],
+    'sort-vars': 'error',
+};

package/rules/stylistic.flat.js

@@ -0,0 +1,114 @@
+export const stylisticRules = {
+    '@stylistic/array-bracket-newline': ['error', 'consistent'],
+    '@stylistic/array-bracket-spacing': 'error',
+    '@stylistic/array-element-newline': ['error', 'consistent'],
+    '@stylistic/arrow-parens': ['error', 'as-needed'],
+    '@stylistic/arrow-spacing': 'error',
+    '@stylistic/block-spacing': 'error',
+    '@stylistic/brace-style': ['error', '1tbs'],
+    '@stylistic/comma-dangle': ['error', 'always-multiline'],
+    '@stylistic/comma-spacing': 'error',
+    '@stylistic/comma-style': 'error',
+    '@stylistic/computed-property-spacing': 'error',
+    '@stylistic/eol-last': 'error',
+    '@stylistic/generator-star-spacing': ['error', 'after'],
+    '@stylistic/implicit-arrow-linebreak': 'error',
+    '@stylistic/indent': ['error', 4, {
+        SwitchCase: 1,
+    }],
+    '@stylistic/indent-binary-ops': ['error', 4],
+    '@stylistic/key-spacing': 'error',
+    '@stylistic/keyword-spacing': 'error',
+    '@stylistic/line-comment-position': 'error',
+    '@stylistic/linebreak-style': 'error',
+    '@stylistic/lines-between-class-members': 'error',
+    '@stylistic/max-len': ['warn', {
+        code: 120,
+    }],
+    '@stylistic/max-statements-per-line': 'error',
+    '@stylistic/member-delimiter-style': ['error', {
+        multiline: {
+            delimiter: 'semi',
+            requireLast: true,
+        },
+        singleline: {
+            delimiter: 'semi',
+            requireLast: false,
+        },
+        multilineDetection: 'brackets',
+    }],
+    '@stylistic/multiline-comment-style': ['error', 'separate-lines'],
+    '@stylistic/multiline-ternary': ['error', 'never'],
+    '@stylistic/new-parens': 'error',
+    '@stylistic/newline-per-chained-call': 'error',
+    '@stylistic/no-confusing-arrow': 'error',
+    '@stylistic/no-extra-parens': ['error', 'functions'],
+    '@stylistic/no-floating-decimal': 'error',
+    '@stylistic/no-mixed-operators': 'error',
+    '@stylistic/no-multi-spaces': 'error',
+    '@stylistic/no-multiple-empty-lines': ['error', {
+        max: 1,
+    }],
+    '@stylistic/no-tabs': 'error',
+    '@stylistic/no-trailing-spaces': 'error',
+    '@stylistic/no-whitespace-before-property': 'error',
+    '@stylistic/object-curly-newline': ['error', {
+        ExportDeclaration: {
+            minProperties: 2,
+            multiline: true,
+        },
+        ImportDeclaration: {
+            minProperties: 4,
+            multiline: true,
+        },
+        ObjectExpression: {
+            minProperties: 1,
+            multiline: true,
+        },
+        ObjectPattern: {
+            minProperties: 4,
+            multiline: true,
+        },
+    }],
+    '@stylistic/object-curly-spacing': ['error', 'always'],
+    '@stylistic/object-property-newline': 'error',
+    '@stylistic/one-var-declaration-per-line': ['error', 'always'],
+    '@stylistic/operator-linebreak': ['error', 'after'],
+    '@stylistic/padding-line-between-statements': ['error', {
+        blankLine: 'always',
+        next: 'return',
+        prev: '*',
+    }],
+    '@stylistic/rest-spread-spacing': 'error',
+    '@stylistic/quote-props': ['error', 'consistent-as-needed'],
+    '@stylistic/quotes': ['error', 'single', {
+        allowTemplateLiterals: false,
+        avoidEscape: true,
+    }],
+    '@stylistic/semi': ['error', 'always'],
+    '@stylistic/semi-style': 'error',
+    '@stylistic/space-before-blocks': 'error',
+    '@stylistic/space-before-function-paren': ['error', 'never'],
+    '@stylistic/space-in-parens': 'error',
+    '@stylistic/space-infix-ops': 'error',
+    '@stylistic/space-unary-ops': ['error', {
+        nonwords: false,
+        words: true,
+    }],
+    '@stylistic/spaced-comment': 'error',
+    '@stylistic/switch-colon-spacing': 'error',
+    '@stylistic/template-curly-spacing': 'error',
+    '@stylistic/template-tag-spacing': 'error',
+    '@stylistic/type-annotation-spacing': ['error', {
+        before: false,
+        after: true,
+        overrides: {
+            arrow: {
+                before: true,
+                after: true,
+            },
+        },
+    }],
+    '@stylistic/wrap-regex': 'error',
+    '@stylistic/yield-star-spacing': ['error', 'after'],
+};

package/rules/variables.flat.js

@@ -0,0 +1,7 @@
+export const variablesRules = {
+    'init-declarations': 'error',
+    'no-label-var': 'error',
+    'no-undef-init': 'error',
+    'no-undefined': 'error',
+    'no-use-before-define': 'error',
+};

package/rules/vue.flat.js

@@ -0,0 +1,26 @@
+export const vueRules = {
+    'vuejs-accessibility/media-has-caption': 'off',
+    'vue/block-tag-newline': [
+        'error',
+        {
+            multiline: 'always',
+            singleline: 'always',
+        },
+    ],
+    'vue/component-name-in-template-casing': [
+        'error',
+        'PascalCase',
+        {
+            registeredComponentsOnly: false,
+        },
+    ],
+    'vue/attributes-order': ['error', {
+        alphabetical: true,
+    }],
+    'vue/html-indent': ['error', 4],
+    'vue/no-empty-component-block': 'error',
+    'vue/no-template-target-blank': 'error',
+    'vue/padding-line-between-blocks': ['error', 'always'],
+    'vue/singleline-html-element-content-newline': 'off',
+    'vue/v-on-function-call': 'error',
+};

package/typescript.flat.js

@@ -0,0 +1,27 @@
+import baseConfig from './index.flat.js';
+import ts from '@typescript-eslint/eslint-plugin';
+import tsParser from '@typescript-eslint/parser';
+
+export default [
+    ...baseConfig,
+    ...ts.configs.recommended,
+    {
+        files: ['**/*.ts', '**/*.tsx'],
+        languageOptions: {
+            parser: tsParser,
+        },
+        plugins: {
+            '@typescript-eslint': ts,
+        },
+        rules: {
+            '@typescript-eslint/consistent-type-imports': [
+                'warn',
+                {
+                    fixStyle: 'inline-type-imports',
+                    prefer: 'type-imports',
+                },
+            ],
+            'no-duplicate-imports': 'off',
+        },
+    },
+];

package/vue.flat.js

@@ -0,0 +1,28 @@
+import baseConfig from './index.flat.js';
+import vue from 'eslint-plugin-vue';
+import vueA11y from 'eslint-plugin-vuejs-accessibility';
+import vueParser from 'vue-eslint-parser';
+import babelParser from '@babel/eslint-parser';
+import { vueRules } from './rules/vue.flat.js';
+
+export default [
+    ...baseConfig,
+    ...vue.configs['flat/recommended'],
+    ...vueA11y.configs['flat/recommended'],
+    {
+        files: ['**/*.vue'],
+        languageOptions: {
+            parser: vueParser,
+            parserOptions: {
+                parser: babelParser,
+            },
+        },
+        plugins: {
+            vue,
+            'vuejs-accessibility': vueA11y,
+        },
+        rules: {
+            ...vueRules,
+        },
+    },
+];