Storybook 官方 ESLint 插件安裝指南eslint-plugin-storybook 的安裝、版本匹配與配置實(shí)戰(zhàn)【免費(fèi)下載鏈接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation項(xiàng)目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇指南講解如何在 Storybook 項(xiàng)目中安裝并啟用官方 ESLint 插件eslint-plugin-storybook從 npm/pnpm/yarn 三種包管理器的安裝命令出發(fā)覆蓋 ESLint 前置條件、ESLint 版本與插件版本匹配、.eslintrc與 flat config 兩種配置體系以及內(nèi)置推薦規(guī)則集的行為邊界。讀完你將能獨(dú)立完成一個(gè)既有 Storybook 環(huán)境含 React/Vue/Svelte 等任意框架的 lint 接入并理解該插件在源碼層面如何自動(dòng)識(shí)別*.stories.*文件、檢查.storybook/main.*配置從而持續(xù)保障 story 代碼與 CSFComponent Story Format規(guī)范一致。一、eslint-plugin-storybook 是什么eslint-plugin-storybook是 Storybook 官方維護(hù)的 ESLint 插件定位是編寫 story 的最佳實(shí)踐規(guī)則集。在 Storybook 倉(cāng)庫(kù)中它位于 code/lib/eslint-pluginpackage.json 中描述為Storybook ESLint Plugin: Best practice rules for writing stories當(dāng)前倉(cāng)庫(kù)內(nèi)版本為10.6.0-beta.1其peerDependencies聲明eslint 8見(jiàn) code/lib/eslint-plugin/package.json。它可以幫你捕捉兩類典型問(wèn)題story 代碼自身的規(guī)范問(wèn)題例如缺失默認(rèn)導(dǎo)出、重復(fù)的 story name、未使用 PascalCase 命名、誤用了已廢棄的storiesOfAPI 等Storybook 配置文件錯(cuò)誤例如在 [.storybook/main.js|ts] 中把 addon 名稱拼寫錯(cuò)誤或引用了未安裝的 addon。該插件內(nèi)部已打包其所需的 CSF 輔助工具因此不需要為了加載 ESLint 插件而單獨(dú)安裝storybook包在 monorepo 共享 ESLint preset 中尤其方便這一細(xì)節(jié)在 code/lib/eslint-plugin/README.md 中有明確說(shuō)明。二、第一步先安裝 ESLint插件是 ESLint 的擴(kuò)展因此需要先保證項(xiàng)目里存在 ESLint。官方安裝文檔docs/configure/integration/eslint-plugin.mdx指出Youll first need to install ESLint。eslint 本體與插件一樣應(yīng)作為開(kāi)發(fā)依賴安裝對(duì)應(yīng)安裝片段見(jiàn) docs/_snippets/eslint-install.mdnpm install --save-dev eslint使用 pnpm 時(shí)pnpm add --save-dev eslint使用 yarn 時(shí)yarn add --dev eslint提示官方文檔站點(diǎn)中的安裝片段用renderercommon packageManagernpm|pnpm|yarn標(biāo)注表示同一命令在不同包管理器下的等價(jià)寫法實(shí)際項(xiàng)目中只執(zhí)行與你鎖定的包管理器對(duì)應(yīng)的那一條即可。三、第二步安裝 eslint-plugin-storybook這就是本篇關(guān)聯(lián)文檔docs/_snippets/eslint-plugin-storybook-install.md的核心內(nèi)容——三種包管理器下將該插件安裝為開(kāi)發(fā)依賴的命令。插件應(yīng)始終使用--save-dev或-D寫入devDependencies。npmnpm install --save-dev eslint-plugin-storybookpnpmpnpm add --save-dev eslint-plugin-storybookyarnyarn add --dev eslint-plugin-storybook3.1 ESLint 與插件版本的匹配關(guān)系ESLint 的 major 版本決定了插件需要安裝哪個(gè)大版本。官方文檔提供了明確的對(duì)照表見(jiàn) docs/configure/integration/eslint-plugin.mdx 的ESLint compatibility一節(jié)ESLint 版本Storybook 插件版本^9.0.0^9.0.0或^0.10.0^8.57.0^9.0.0或^0.10.0^7.0.0~0.9.0需要說(shuō)明兩點(diǎn)以幫助你結(jié)合當(dāng)前倉(cāng)庫(kù)判斷上面的表格是官方集成文檔中的版本指引而當(dāng)前倉(cāng)庫(kù)code/lib/eslint-plugin的package.json已推進(jìn)到10.6.0-beta.110.x 時(shí)代其peerDependencies直接聲明eslint 8。在跟隨文檔選擇安裝版本時(shí)優(yōu)先以你要安裝的插件 dist-tag 發(fā)布說(shuō)明與peerDependencies為準(zhǔn)。之所以存在嚴(yán)格的版本映射是因?yàn)?ESLint 9 起 flat config 成為默認(rèn)配置體系規(guī)則 API 與配置結(jié)構(gòu)都有變化舊版插件無(wú)法直接在新版 ESLint 上加載。四、第三步配置插件使其生效安裝完成后還需在 ESLint 配置中啟用插件。根據(jù)你使用的 ESLint 配置風(fēng)格分兩種情況。4.1 傳統(tǒng).eslintrc配置ESLint v9在.eslintrc的extends中加入plugin:storybook/recommended。官方指出可以省略eslint-plugin-前綴{ // extend plugin:storybook/configuration例如 extends: [plugin:storybook/recommended] }自動(dòng)文件范圍啟用該配置后無(wú)需手動(dòng)指定文件范圍插件只作用于匹配*.stories.*官方推薦或*.story.*模式的文件。這一自動(dòng)作用域在源碼中可以看到其實(shí)現(xiàn)推薦配置通過(guò)overrides的files字段聲明的模式為**/*.stories.(ts|tsx|js|jsx|mjs|cjs)與**/*.story.(ts|tsx|js|jsx|mjs|cjs)同時(shí)另設(shè)一組專門作用于.storybook/main.(js|cjs|mjs|ts)的規(guī)則見(jiàn) code/lib/eslint-plugin/src/configs/recommended.ts。讓.storybook目錄也被檢查在.eslintignore中加入下面一行作用是撤銷對(duì)該目錄的默認(rèn)忽略讓插件也能檢查 Storybook 自己的配置文件!.storybook官方文檔給出的理由是這樣能保證.storybook目錄內(nèi)配置始終正確——例如它可以捕捉 [.storybook/main.js|ts] 中拼寫錯(cuò)誤的 addon 名稱對(duì)應(yīng)規(guī)則是storybook/no-uninstalled-addons。4.2 按規(guī)則定制僅對(duì) story 文件生效如果你需要覆蓋、新增或關(guān)閉某條規(guī)則應(yīng)把這些改動(dòng)放進(jìn)overrides段且files應(yīng)與 [.storybook/main.js|ts] 中的stories屬性保持一致避免規(guī)則被應(yīng)用到所有文件{ overrides: [ { // 應(yīng)與 .storybook/main.js|ts 中的 stories 屬性匹配 files: [**/*.stories.(ts|tsx|js|jsx|mjs|cjs)], rules: { // 開(kāi)啟該規(guī)則 storybook/csf-component: error, // 關(guān)閉該規(guī)則 storybook/default-exports: off, } } ] }4.3 flat configESLint v9 默認(rèn) / 自 v8.57.0 起可用若使用eslint.config.jsflat config 風(fēng)格官方文檔提供了兩種推薦寫法。最簡(jiǎn)單的是直接展開(kāi)flat/recommendedimport storybook from eslint-plugin-storybook; // 若使用更老的 ESLint 版本可將 eslint/config 替換為 eslint/config-helpers import { defineConfig } from eslint/config; export default defineConfig([ ...storybook.configs[flat/recommended], // 在此追加其他通用配置如 js.configs.recommended ]);由于eslint-plugin-storybook的主模塊默認(rèn)導(dǎo)出中同時(shí)帶有configs、meta與rules三個(gè)命名導(dǎo)出見(jiàn) code/lib/eslint-plugin/src/index.ts配置對(duì)象會(huì)自然被 flat config 注冊(cè)器識(shí)別。當(dāng)你使用tseslint、tslint等工具的配置輔助函數(shù)時(shí)注冊(cè)方式略有不同——需要把整個(gè)插件對(duì)象作為參數(shù)傳入而非解構(gòu)它import storybook from eslint-plugin-storybook; import somePlugin from some-plugin; import tseslint from typescript-eslint; export default tseslint.config( somePlugin, storybook.configs[flat/recommended], // 注意不要解構(gòu) );同時(shí)flat config 下讓.storybook參與檢查需使用globalIgnores反轉(zhuǎn)忽略規(guī)則import { defineConfig, globalIgnores } from eslint/config; export default defineConfig([ globalIgnores([!.storybook], Include Storybook Directory), // ... ]);在 flat config 中針對(duì) story 文件覆蓋單條規(guī)則的方式如下import storybook from eslint-plugin-storybook; import { defineConfig } from eslint/config; export default defineConfig([ ...storybook.configs[flat/recommended], { // 應(yīng)與 .storybook/main.js|ts 中的 stories 屬性匹配 files: [**/*.stories.(ts|tsx|js|jsx|mjs|cjs)], rules: { // 開(kāi)啟該規(guī)則 storybook/csf-component: error, // 關(guān)閉該規(guī)則 storybook/default-exports: off, }, }, ]);MDX 兼容性說(shuō)明官方文檔明確該插件不支持 MDX 文件。若你的 story 寫在.mdx中插件規(guī)則不會(huì)對(duì)其生效。五、內(nèi)置配置與規(guī)則速覽從源碼 code/lib/eslint-plugin/src/index.ts 可以確認(rèn)插件導(dǎo)出的配置configs共 8 種分為兩組傳統(tǒng) eslintrc 配置csf、csf-strict、addon-interactions、recommendedflat config 配置flat/csf、flat/csf-strict、flat/addon-interactions、flat/recommended。這 4 類規(guī)則集的定義文件一一對(duì)應(yīng)位于 code/lib/eslint-plugin/src/configs 與同目錄下的flat/子目錄。插件當(dāng)前共導(dǎo)出 16 條規(guī)則對(duì)應(yīng) code/lib/eslint-plugin/src/rules 下的 16 個(gè)*.ts實(shí)現(xiàn)文件。以官方文檔docs/configure/integration/eslint-plugin.mdx 中的規(guī)則總表為據(jù)典型規(guī)則與所屬配置如下規(guī)則作用可自動(dòng)修復(fù)所屬配置storybook/await-interactionsinteractions 必須被 await?addon-interactions、recommendedstorybook/context-in-play-function調(diào)用其他 story 的 play function 時(shí)應(yīng)傳入上下文-recommended、addon-interactionsstorybook/csf-componentmeta 中應(yīng)設(shè)置 component 屬性-csf、csf-strictstorybook/default-exportsstory 文件應(yīng)有默認(rèn)導(dǎo)出?csf、csf-strict、recommendedstorybook/hierarchy-separatortitle 中不應(yīng)使用已廢棄的分層分隔符?csf、csf-strict、recommendedstorybook/no-redundant-story-namestory 不應(yīng)有冗余的 name 屬性?csf、csf-strict、recommendedstorybook/no-renderer-packagesstory 中不應(yīng)直接導(dǎo)入 renderer 包-recommendedstorybook/no-stories-ofstoriesOf已廢棄不應(yīng)使用-csf-strictstorybook/no-title-property-in-meta不應(yīng)在 meta 中定義 title?csf-strictstorybook/no-uninstalled-addons識(shí)別拼寫錯(cuò)誤或未安裝的 addon-recommended作用于.storybook/main.*storybook/prefer-pascal-casestory 命名應(yīng)使用 PascalCase?recommendedstorybook/story-exportsstory 文件至少導(dǎo)出一個(gè) story-csf、csf-strict、recommendedstorybook/use-storybook-expect應(yīng)使用storybook/test、storybook/test或storybook/jest的 expect?addon-interactions、recommendedstorybook/use-storybook-testing-library不要在 story 中直接使用 testing-library?addon-interactions、recommended此外還有storybook/meta-inline-properties、storybook/meta-satisfies-type兩條獨(dú)立規(guī)則不屬于上述任何配置。作為對(duì)照從源碼 code/lib/eslint-plugin/src/configs/recommended.ts 可以看到recommended配置在兩個(gè)overrides段中分別啟用的完整規(guī)則集合對(duì) story 文件啟用await-interactions、context-in-play-function、default-exports、hierarchy-separator、no-redundant-story-name、no-renderer-packages、prefer-pascal-case、story-exports、use-storybook-expect、use-storybook-testing-library等規(guī)則并將react-hooks/rules-of-hooks、import-x/no-anonymous-default-export關(guān)閉以避免與 story 寫法沖突對(duì).storybook/main.*文件則僅啟用no-uninstalled-addons。每條規(guī)則的實(shí)現(xiàn)與配套測(cè)試位于 code/lib/eslint-plugin/src/rules如default-exports.ts與default-exports.test.ts如果你需要了解某條規(guī)則的判定細(xì)節(jié)可以直接查閱對(duì)應(yīng)文件與測(cè)試用例。六、安裝與啟用后的驗(yàn)證方式完成上述三步安裝 ESLint → 安裝eslint-plugin-storybook→ 在配置中啟用plugin:storybook/recommended并放行.storybook目錄后你可以在終端直接運(yùn)行npx eslint **/*.stories.(ts|tsx|js|jsx|mjs|cjs)預(yù)期出現(xiàn)兩類輸出無(wú)輸出退出碼 0所有 story 文件通過(guò)檢查報(bào)告storybook/*開(kāi)頭的錯(cuò)誤或警告例如Default export should be placed at the end of the filedefault-exports、Stories should use PascalCaseprefer-pascal-case等可按提示逐一修正或按上文「overrides」方式按項(xiàng)目規(guī)范調(diào)整。若你新寫一個(gè)Button.stories.tsx卻忘記默認(rèn)導(dǎo)出或?qū)戝e(cuò)了 addon 名插件會(huì)立刻給出定位到具體文件的診斷信息——這正是把 lint 接入 CI 或 IDE 后帶來(lái)的持續(xù)保障。七、小結(jié)接入eslint-plugin-storybook的核心路徑可以濃縮為四步安裝 ESLint → 按包管理器安裝eslint-plugin-storybook本文檔的三種命令即eslint-plugin-storybook-install.md片段的全部?jī)?nèi)容→ 在.eslintrc或eslint.config.js中啟用plugin:storybook/recommended/flat/recommended→ 通過(guò).eslintignore或globalIgnores放行.storybook目錄。插件會(huì)自動(dòng)限定到*.stories.*/*.story.*文件并對(duì).storybook/main.*單獨(dú)啟用 addon 檢查無(wú)需手工圈定文件范圍。安裝前后注意核對(duì) ESLint 大版本與插件版本映射即可讓 story 代碼在團(tuán)隊(duì)中保持一致的、符合 Storybook 最佳實(shí)踐的質(zhì)量基線?！久赓M(fèi)下載鏈接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation項(xiàng)目地址: https://gitcode.com/GitHub_Trending/st/storybook創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考