ESLint 8 から ESLint 9 の flat configに移行する

[KentaHizume]

2025/04/04 現在

air-bnb の ESLint 9 対応状況は以下にまとまっている。
main ブランチへの反映はまだ時間がかかりそう。

• eslint v9 support airbnb/javascript#2961

flat config への対応 Issue も Openの状態

• Support of new eslint flat config airbnb/javascript#2804

eslint-config-standardはflat config に対応していない状態が引き続きであり、特に進捗なし。

• Support for Eslint v9 Flat Config format standard/eslint-config-standard#411 (comment)

create-vue に関しては ESLint 9 flat config に対応済み、以下の ようにv3.16.0 でflat config に関する設定方法が説明されている。

• https://github.com/vuejs/create-vue/releases/tag/v3.16.0
• https://eslint.org/blog/2025/03/flat-config-extends-define-config-global-ignores/

なお、oxlint に関しても導入を進めており、現時点では ESLint と oxlint を並行利用する形で実施されている？

• chore: better oxlint + vscode integration vuejs/create-vue#720

2025/1/22 現在

一旦様子を見る方針で、
v 8 系 + @vue/eslint-config-airbnb-with-typescript を維持する。

create-vue@3.14.0 が ESlint + TypeScript に対応
https://github.com/vuejs/create-vue/releases/tag/v3.14.0

ただし、中身的にはeslint-config-standard-with-typescriptをextendsするのをやめているのでルールセットは異なる。
https://github.com/vuejs/eslint-config-standard/releases/tag/%40vue%2Feslint-config-standard-with-typescript%409.0.0

Vue固有の設定＋typescript-eslintに含まれる設定が利用できる。
https://github.com/vuejs/eslint-config-typescript/tree/v14.3.0?tab=readme-ov-file#usage

create-vueすると、eslint.config.tsが生成され、デフォルトのルールは下記。

  pluginVue.configs['flat/essential'],
  vueTsConfigs.recommended,

なので、Vue固有のルール以外は下記が適用される。
https://typescript-eslint.io/users/configs/#recommended

つまり、移行前に現在の理由とデフォルトのルールを比較して過不足を確認する必要がある。
不足している場合、下記で用意されているものであればすぐに使用できる。
https://typescript-eslint.io/users/configs/

recommended-type-checked が有力と思われる。

2024/12/25 現在

JavaScript版のairbnbのスタイルガイドが引き続きflat configに対応中の状態。

• eslint v9 support airbnb/javascript#2961

eslint-config-standardはflat config に対応していない状態で、
別のパッケージを見てくださいというコメントがある。

• Support for Eslint v9 Flat Config format standard/eslint-config-standard#411 (comment)
• https://github.com/neostandard/neostandard

googleのスタイルガイドは進んでいなさそう。

• Support for ESLint's New Flat Configs google/gts#830

2024/12/19 現在

確認対象のVue用のスタイルガイドについて、前回の時点からの更新はない状態。

2024/10/22 現在

調査の結果、現時点では9系への移行を見送り、ESLint8系のまま止めておく。
見送る大きな理由として、現時点でうまく適用できるVue用のスタイルガイドがないので、
いまflat configに移行するとlintの機能が縮小してしまうことへの懸念が挙げられる。

8系はEOLを迎えてはいるが、各プラグインのflat configへの対応状況を見る限り、
まだ過渡期と思われ、8系を使っていても直ちに問題は発生しないと判断した。

次のターゲットは、2024年末～2025年初めの ESLint 10 系のリリースと思われる。

When ESLint v10.0.0 is released (end of 2024 or early 2025 in all likelihood), the eslintrc configuration system will be completely removed.
https://eslint.org/blog/2023/10/flat-config-rollout-plans/#eslintrc-removed-in-eslint-v10.0.0

定期的な確認対象

下記のレポジトリのリリース状況をwatchする。
どちらかがflat configに対応したら、適用可能か調査を再開する。
eslint-config-standard
eslint-config-airbnb

【詳細】うまく適用できるVue用のスタイルガイドがない

現在適用しているeslint-config-airbnb-typescriptが2024/8にアーカイブされてしまったので、
代わりになるスタイルガイドを適用する必要がある。

1. eslint-config-standard

Vue用のスタイルガイドとしてflat config版がサポートされる予定。
standardのほうはflat config対応済みのため先に対応される見込み。

• feat!: support ESLint 9 flat config vuejs/eslint-config-typescript#81

Work on @vue/eslint-config-standard and @vue/eslint-config-airbnb. I can't guarantee a timeframe for these 2 projects, though. I will likely work on the standard config first because the upstream library has already shipped flag config support

2. typescript-eslintのrecommended-type-checked

現在はrecommendedを使用しているが、
型情報を利用するルールを追加で使用することで、チェックを強化することが可能。
https://github.com/vuejs/eslint-config-typescript?tab=readme-ov-file#linting-with-type-information

https://typescript-eslint.io/users/configs#recommended-type-checked
https://zenn.dev/cybozu_frontend/articles/ts-eslint-v6-guide

• TypeScriptの非同期処理のawait忘れを防止する maris#1811

3. eslint-config-airbnb

typescript版はアーカイブされてしまったが、JS版はメンテナンスされている。

• Support "Flat Config" (ESLint 9) iamturns/eslint-config-airbnb-typescript#331

起票時

ES Lint 8 系が 2024/10/5 に EOL を迎えるため、ES Lint 9 に移行する。
ES Lint 9 では、config の形式に破壊的変更があり、
flat config という新しい形式の config に移行する必要がある。

create-vue のES Lint 9対応が完了したら、この内容に追随する形でサンプルアプリとドキュメントの更新を行う。

• feat: support ESLint 9 Flat Config vuejs/create-vue#573

完了条件

• ES Lint 9 系にアップデートし、 flat config へ移行した状態で問題なく静的コード解析が動作すること
• create-vueで作成されるテンプレートと同期が取れていること
• ドキュメントの関連個所が修正されていること

[KentaHizume]

下記から内容をまとめ直しの上転記

• ESLint 9のflat configに移行する maris#349

[KentaHizume]

2024/10/11 時点

create-vueがリリースされたので、内容を確認する
https://github.com/vuejs/create-vue/releases/tag/v3.11.0

flat config対応以外にvitest周りの変更もあるように見える。

2024/10/17時点

flat config対応以外のトピックは下記。

1. @vitest/eslint-plugin を依存パッケージに追加
2. 推奨拡張機能に vitest.explorer を追加
3. cypress用のtsconfig.jsonを移動
4. リンク先のURL修正

1点目のパッケージ追加は、別々にやったほうが安全そう（後述）
2点目の推奨拡張機能追加はflat configと独立してやっていい。
残りの2つは軽微ですぐに対応できる。

1. @vitest/eslint-plugin を依存パッケージに追加
   これは直近のトピックとしてVItest公式から推奨になったらしい。
   テストコード用のルールを与えられる。
   現在のテストコードが引っかかる可能性があるのでflat configと一緒にやるとまずい。

https://zenn.dev/bs_kansai/articles/8ff70404804f60

よって、下記の順序、方針で対応する。

(1)
@vitest/eslint-plugin でどれくらい警告が出るか確認して、
すぐ対応できるものであれば対応してからflat config化、
時間かかりそうであればflat config化してからこの対応をする
(2)推奨機能追加
(3)その他軽微な変更

2024/10/18時点

@vitest/eslint-pluginがESLint9前提なので、先にflat config対応をやる必要がある。

Make sure you're running eslint v9.0.0 or higher for the latest version of this plugin to work.

2024/10/21 時点

flat configのサポート状況を一覧できる。

• 📈 Tracking: Flat Config support eslint/eslint#18093

airbnb-typescriptは下記。

• Support "Flat Config" (ESLint 9) iamturns/eslint-config-airbnb-typescript#331

[KentaHizume]

新旧の差分ファイル

旧：3.10.4 新：3.11.1

$ diff -r -q create-vue-work/app create-vue-work-new/app
Only in create-vue-work-new/app: .editorconfig
Only in create-vue-work/app: .eslintrc.cjs
Files create-vue-work/app/.prettierrc.json and create-vue-work-new/app/.prettierrc.json differ
Files create-vue-work/app/.vscode/extensions.json and create-vue-work-new/app/.vscode/extensions.json differ
Files create-vue-work/app/.vscode/settings.json and create-vue-work-new/app/.vscode/settings.json differ
Files create-vue-work/app/README.md and create-vue-work-new/app/README.md differ
Only in create-vue-work/app/cypress/e2e: tsconfig.json
Only in create-vue-work-new/app/cypress: tsconfig.json
Only in create-vue-work-new/app: eslint.config.js
Files create-vue-work/app/package.json and create-vue-work-new/app/package.json differ
Files create-vue-work/app/src/components/HelloWorld.vue and create-vue-work-new/app/src/components/HelloWorld.vue differ
Files create-vue-work/app/src/components/TheWelcome.vue and create-vue-work-new/app/src/components/TheWelcome.vue differ
Files create-vue-work/app/vite.config.ts and create-vue-work-new/app/vite.config.ts differ

差分全量

$ diff -r create-vue-work/app create-vue-work-new/app
Only in create-vue-work-new/app: .editorconfig
Only in create-vue-work/app: .eslintrc.cjs
diff -r create-vue-work/app/.prettierrc.json create-vue-work-new/app/.prettierrc.json
0a1
>
4d4
<   "tabWidth": 2,
6,8c6,7
<   "printWidth": 100,
<   "trailingComma": "none"
< }
\ No newline at end of file
---
>   "arrowParens": "avoid"
> }
diff -r create-vue-work/app/.vscode/extensions.json create-vue-work-new/app/.vscode/extensions.json
3a4
>     "vitest.explorer",
diff -r create-vue-work/app/.vscode/settings.json create-vue-work-new/app/.vscode/settings.json
1a2,7
>   "explorer.fileNesting.enabled": true,
>   "explorer.fileNesting.patterns": {
>     "tsconfig.json": "tsconfig.*.json, env.d.ts",
>     "vite.config.*": "jsconfig*, vitest.config.*, cypress.config.*, playwright.config.*",
>     "package.json": "package-lock.json, pnpm*, .yarnrc*, yarn*, .eslint*, eslint*, .prettier*, prettier*, .editorconfig"
>   },
diff -r create-vue-work/app/README.md create-vue-work-new/app/README.md
15c15
< See [Vite Configuration Reference](https://vitejs.dev/config/).
---
> See [Vite Configuration Reference](https://vite.dev/config/).
Only in create-vue-work/app/cypress/e2e: tsconfig.json
Only in create-vue-work-new/app/cypress: tsconfig.json
Only in create-vue-work-new/app: eslint.config.js
diff -r create-vue-work/app/package.json create-vue-work-new/app/package.json
15c15
<     "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore",
---
>     "lint": "eslint . --fix",
19,21c19,21
<     "pinia": "^2.1.7",
<     "vue": "^3.4.29",
<     "vue-router": "^4.3.3"
---
>     "pinia": "^2.2.4",
>     "vue": "^3.5.12",
>     "vue-router": "^4.4.5"
24d23
<     "@rushstack/eslint-patch": "^1.8.0",
27,31c26,31
<     "@types/node": "^20.14.5",
<     "@vitejs/plugin-vue": "^5.0.5",
<     "@vitejs/plugin-vue-jsx": "^4.0.0",
<     "@vue/eslint-config-prettier": "^9.0.0",
<     "@vue/eslint-config-typescript": "^13.0.0",
---
>     "@types/node": "^20.16.11",
>     "@vitejs/plugin-vue": "^5.1.4",
>     "@vitejs/plugin-vue-jsx": "^4.0.1",
>     "@vitest/eslint-plugin": "1.1.7",
>     "@vue/eslint-config-prettier": "^10.0.0",
>     "@vue/eslint-config-typescript": "^14.0.1",
34,45c34,45
<     "cypress": "^13.12.0",
<     "eslint": "^8.57.0",
<     "eslint-plugin-cypress": "^3.3.0",
<     "eslint-plugin-vue": "^9.23.0",
<     "jsdom": "^24.1.0",
<     "npm-run-all2": "^6.2.0",
<     "prettier": "^3.2.5",
<     "start-server-and-test": "^2.0.4",
<     "typescript": "~5.4.0",
<     "vite": "^5.3.1",
<     "vitest": "^1.6.0",
<     "vue-tsc": "^2.0.21"
---
>     "cypress": "^13.15.0",
>     "eslint": "^9.12.0",
>     "eslint-plugin-cypress": "^4.0.0",
>     "eslint-plugin-vue": "^9.29.0",
>     "jsdom": "^25.0.1",
>     "npm-run-all2": "^6.2.3",
>     "prettier": "^3.3.3",
>     "start-server-and-test": "^2.0.8",
>     "typescript": "~5.5.4",
>     "vite": "^5.4.8",
>     "vitest": "^2.1.2",
>     "vue-tsc": "^2.1.6"
diff -r create-vue-work/app/src/components/HelloWorld.vue create-vue-work-new/app/src/components/HelloWorld.vue
12c12
<       <a href="https://vitejs.dev/" target="_blank" rel="noopener">Vite</a> +
---
>       <a href="https://vite.dev/" target="_blank" rel="noopener">Vite</a> +
diff -r create-vue-work/app/src/components/TheWelcome.vue create-vue-work-new/app/src/components/TheWelcome.vue
29c29
<     <a href="https://vitejs.dev/guide/features.html" target="_blank" rel="noopener">Vite</a>. The
---
>     <a href="https://vite.dev/guide/features.html" target="_blank" rel="noopener">Vite</a>. The
diff -r create-vue-work/app/vite.config.ts create-vue-work-new/app/vite.config.ts
7c7
< // https://vitejs.dev/config/
---
> // https://vite.dev/config/

[KentaHizume]

flat config関連

feat(ESLint): support ESLint 9 Flat Config by @haoqunjiang in vuejs/create-vue#573

定義ファイル

• eslintrc.cjsがeslintconfig.jsに変更

package.json

• lintコマンドの定義に変更あり

• 依存パッケージに変更あり
  削除：@rushstack/eslint-patch

.prettierrc.json

• "tabWidth": 2,、 "printWidth": 100、 "trailingComma": "none"　が削除
  • .editorconfigに移動しているように見える
• "arrowParens": "avoid" が追加

.editorconfig

• 追加された

flat config以外

package.jsonに依存パッケージ追加

feat(ESLint + Vitest): add @vitest/eslint-plugin by @cexbrayat in vuejs/create-vue#559

追加：@vitest/eslint-plugin
これはflat configとは関係なし。

VSCode周り

feat(Vitest): add Vitest VSCode extension recommendation by @btea in vuejs/create-vue#553

• 推奨拡張機能に vitest.explorer が追加
• settings.jsonにvitest.explorer周りの設定が追加されている

Cypress周り

fix(Cypress + TypeScript): move tsconfig.json for cypress e2e a level up for better tooling compatibility [5027f2b]

• cypress用のtsconfig.jsonが、e2eフォルダ配下からcypressフォルダ直下へ移動

URL修正

• vitejs.devがvite.devに変更
  （現状は古いほうにアクセスしてもリダイレクトされる）

[KentaHizume]

移行

（作業記録、随時更新）

マイグレーションガイド

https://eslint.org/docs/latest/use/configure/migration-guide

メモ

• @vue/eslint-config-airbnb-with-typescript が dependenciesのほうにあるが、
  開発でしか使わないのでdevDepenenciesでは？

• lint系は設定を共通化しているので、ワークスペースのpackage,jsonよりルートプロジェクトのほうがいいかも
  ⇒バージョン変えたいケースもあるかもしれないのでいまのほうがいいか（と思ってそう置いた気がする）
  ⇒そういえばルートに全部置くとワークスペースのパッケージにないパッケージを使わないでくださいの警告が出たような記憶

手順

マイグレーションツール適用

マイグレーションツールが用意されていたが、
eslintrc.jsにはうまく使えないらしい。
実際に試してみたが生成されたファイルが色々おかしいためダメそう。

The configuration migrator doesn’t yet work well for .eslintrc.js files.
仕方ないので1つ1つ処理する。

パッケージ

.eslintrcから参照のあるパッケージについて、create-vueより古いものは一式アップデートする

パッケージ名	アップデート前	アップデート後	備考
eslint	8.57.0	9.12.0	メジャー
eslint-plugin-cypress	3.4.0	4.0.0	マイナー
eslint-plugin-vue	9.28.0	9.29.0	マイナー
@vue/eslint-config-prettier	9.0.0	10.0.0	メジャー
@vue/eslint-config-typescript	13.0.0	14.0.1	メジャー
@vitest/eslint-plugin	-	1.1.7	新規
@rushstack/eslint-patch	1.10.4	-	削除

prettierは3.3.3で変更なし。

-extオプションの廃止

npmスクリプトで使用していた、対象のファイル拡張子を指定するための -ext オプションが廃止された。
かわりに設定ファイルのfilesフィールドで指定する必要がある。

https://eslint.org/docs/latest/use/configure/migration-guide#--ext

--ignore-path オプションの廃止

.gitignoreファイルから対象外ファイルを読み込む機能が廃止になった。
代わりに設定ファイルのignoresフィールドで指定する必要がある。

https://eslint.org/docs/latest/use/configure/migration-guide#ignoring-files
To ignore files with flat config, you can use the ignores property in a config object. The ignores property accepts an array of glob patterns. Flat config does not support loading ignore patterns from .eslintignore files, so you’ll need to migrate those patterns directly into flat config.

flat configの場合にモノレポ構成でルートから継承がうまくできない

モジュールが見つからないエラーで実行できなくなってしまった。
原因として、ルートに置いてワークスペースで継承するということができないらしい。

下記のissueに詳しく書かれているが、下記のような設定ファイルは動作しない。
原因はflat configの場合に、eslintのCLIが実行した場所から最も近い1つの設定ファイルしか読まないかららしい。
相対パスがおかしくなってモジュールがインポートできていなかった様子。

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@vue/eslint-config-typescript' 

import rootConfig from "../../../eslint.config.js";

export default [
    ...rootConfig,
    // Some more stuff
]

問題提起がされており、

eslint/eslint#18385

対応するPRがマージされている。

eslint/eslint#18742

しかし、まだexperimentalな機能で、v10でexperimentalではなくなるよう。
unstable_config_lookup_from_fileフラグを立てることで使用できる。

https://eslint.org/docs/latest/use/configure/configuration-files#experimental-configuration-file-resolution

experimentalをあたまり使いたくないので、
対処としては一旦ワークスペースにも同じ設定のファイルを置いて、
experimentalでなくなったら別issueで導入する。

airbnbのプラグインがまだflat configに対応していない

• Support Eslint 9 vuejs/eslint-config-airbnb#65

issueは提起されていて、
コメント欄に例が挙げられている通り、
FlatCompatユーティリティを使用して変換する必要がある。

https://eslint.org/docs/latest/use/configure/migration-guide#using-eslintrc-configs-in-flat-config

ライバルだったgoogleのスタイルガイドも未対応の状態なので、よい代替先も見当たらない。

• feat!: flat config for eslint migrated from old config google/gts#886

一旦FlatCompatで変換する。

fixupConfigRules

• flatCompatを使用しただけの場合、下記のエラーで落ちる。

TypeError: context.getScope is not a function

ESLintのAPIの破壊的変更により使えなくなったAPIをコールしているのが原因らしい。
旧スタイルのプラグインの内部でさらにそのような状態になっている場合は、
fixupConfigRules()でラップする必要がある。

https://eslint.org/blog/2024/05/eslint-compatibility-utilities/#using-with-flatcompat

プラグインのキーが重複する

ConfigError: Config (unnamed): Key "plugins": Cannot redefine plugin "vue". 

@vue/eslint-config-airbnbが、
内部でplugins: ['vue']とplugins: ['@typescript-eslint'],を宣言しているが、
これをFlatCompatでラップしてしまうと、
pluginVue.configs['flat/recommended']とvueTsEslintConfig()とプラグインの宣言が衝突するのが原因と思われる。

lintすると/* eslint-disable */コメントが削除される

• reportUnusedDisableDirectivesの影響と思われる。
• reportUnusedDisableDirectives: falseにすると、削除されなかったため。

https://eslint.org/blog/2023/12/eslint-v8.56.0-released/#new-features-for-reporting-unused-disable-directives
https://eslint.org/docs/latest/use/configure/configuration-files#reporting-unused-disable-directives
https://zenn.dev/teppeis/articles/2023-12-eslint-report-unused-disable-directives

移行前

/* eslint-env node */
require('@rushstack/eslint-patch/modern-module-resolution');

module.exports = {
  root: true,
  extends: [
    'plugin:vue/vue3-recommended',
    'eslint:recommended',
    '@vue/eslint-config-airbnb-with-typescript',
    '@vue/eslint-config-prettier',
  ],
  rules: {
    'import/prefer-default-export': 'off',
    'import/no-default-export': 'error',
  },
  overrides: [
    {
      files: [
        'cypress/e2e/**/*.{cy,spec}.{js,ts,jsx,tsx}',
        'cypress/support/**/*.{js,ts,jsx,tsx}',
      ],
      extends: ['plugin:cypress/recommended'],
    },
  ],
  ignorePatterns: ['postcss.config.cjs', 'tailwind.config.js'],
};

[KentaHizume]

ESLint Config Inspector

https://eslint.org/blog/2024/04/eslint-config-inspector/

[KentaHizume]

移行前後の検証

• 下記を参考に実施する。

https://zenn.dev/cybozu_frontend/articles/introduce-eslint-config-compat