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