Storybook 项目中安装并启用 ESLint 与 eslint-plugin-storybook 的完整指南【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本指南讲解如何在 Storybook 项目中从零安装 ESLint并接入 Storybook 官方维护的eslint-plugin-storybook让 stories 与.storybook配置始终符合 Storybook 与前端工程最佳实践。你将掌握 npm、pnpm、yarn 三种包管理器下的安装命令、.eslintrclegacy与eslint.config.jsflat config两种配置形态以及规则作用范围、覆盖与禁用方法。ESLint 在 Storybook 工作流中的角色Storybook 提供了独立的 code/lib/eslint-plugin 包即eslint-plugin-storybook用于在编写 stories 与组件时对齐最新的 Storybook 与前端开发最佳实践。包内声明为eslintplugin、peerDependencies: { eslint: 8 }并由 Storybook 主仓库统一维护。ESLint 本身则负责提供通用的 JavaScript/TypeScript 静态检查能力是运行该插件的前提。第一步安装 ESLint安装 ESLint 是整个流程的基础步骤务必作为开发依赖devDependencies安装因为它只服务于本地代码检查不应进入生产运行时。npm 用户执行npm install --save-dev eslintpnpm 用户执行pnpm add --save-dev eslintyarn 用户执行yarn add --dev eslint安装完成后可通过npx eslint --version验证版本。安装的 ESLint 大版本会影响后续插件版本的选择请留意下文“ESLint 兼容性”小节。第二步安装 eslint-plugin-storybookESLint 就绪后继续安装 Storybook 官方插件同样作为开发依赖npm install --save-dev eslint-plugin-storybookpnpm add --save-dev eslint-plugin-storybookyarn add --dev eslint-plugin-storybook一个值得注意的工程细节该插件在package.json的files中打包了自身所需依赖插件自身也“捆绑了所需的 CSF 辅助工具”因此在共享 monorepo 的 ESLint preset 等场景中无需为了加载该插件而单独安装 storybook 主包见 插件 README。第三步最小化接入配置基于.eslintrcESLint v9 之前在.eslintrc配置文件的extends中加入plugin:storybook/recommended。由于 ESLint 的命名约定此处可以省略eslint-plugin-前缀{ // extend plugin:storybook/configuration, 例如: extends: [plugin:storybook/recommended] }最后在.eslintignore文件中追加一行!.storybook这一行用于取消对.storybook目录的忽略使插件也能 lint 目录内的配置文件如main.js|ts。其实际收益是一旦在main.js|ts中拼错 addon 名称检查即可立刻报错保证配置始终正确。提示ESLint 默认会忽略node_modules与“以点开头的目录”。.eslintignore中的!.storybook正是利用忽略规则的取反语义单独将 Storybook 配置目录重新纳入检查范围。基于 flat configESLint v9 及 v8.57.0若项目使用 flat config 风格则在eslint.config.js中加入全局忽略取反import { defineConfig, globalIgnores } from eslint/config; export default defineConfig([ globalIgnores([!.storybook], Include Storybook Directory), // ... ]);启用并扩展 recommended 规则集与.eslintrc的extends不同flat config 需要显式展开预设配置对象再将通用的其他规则集拼接进来import 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 等通用规则集 ]);如果项目借助typescript-eslint等工具的辅助函数组织配置则插件配置需要作为整体传入而不是解构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], // 注意此处不解构 );ESLint 与插件版本兼容矩阵插件对 ESLint 版本有对应要求选择插件版本时按下表匹配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插件源码中的peerDependencies声明eslint: 8而表格进一步给出了按大版本细分的历史兼容线。安装时建议让包管理器解析出与当前 ESLint 匹配的插件版本。规则自动作用范围启用后无需任何手动配置插件只会作用于符合*.stories.*推荐或*.story.*命名约定的文件。这一点可从源码得到印证在 code/lib/eslint-plugin/src/configs/recommended.ts 及 flat 系列配置如 flat/recommended.ts中均将检查范围限定为**/*.stories.(ts|tsx|js|jsx|mjs|cjs) **/*.story.(ts|tsx|js|jsx|mjs|cjs)因此业务代码文件不会被这些 Storybook 专属规则打扰。需要提醒的是该插件不支持 MDX 文件.stories.mdx不在检查范围内。局部覆盖与禁用规则stories 专属规则不应施加到所有文件因此建议通过overrideslegacy或独立 flat 配置片段将规则调整限定在 story 文件内。.eslintrc形态{ overrides: [ { // 该 patterns 应与 .storybook/main.js|ts 中的 stories 属性保持一致 files: [**/*.stories.(ts|tsx|js|jsx|mjs|cjs)], rules: { // 开启某条规则 storybook/csf-component: error, // 关闭某条规则 storybook/default-exports: off, } } ] }flat config 形态import storybook from eslint-plugin-storybook; import { defineConfig } from eslint/config; export default defineConfig([ ...storybook.configs[flat/recommended], { // 同样匹配 .storybook/main.js|ts 中的 stories 属性 files: [**/*.stories.(ts|tsx|js|jsx|mjs|cjs)], rules: { storybook/csf-component: error, storybook/default-exports: off, }, }, ]);内置规则速览插件当前提供四套可继承的预设csf、csf-strict、addon-interactions、recommendedflat 前缀的flat/xxx变体亦存在。rules 源码位于 code/lib/eslint-plugin/src/rules其中核心规则包括规则作用自动修复storybook/await-interactionsplay 中的交互应当被await✅storybook/context-in-play-function调用其他 story 的 play 函数时应传入 contextstorybook/csf-componentmeta 中应设置component属性storybook/default-exportsstory 文件应有 default export✅storybook/hierarchy-separator禁止在 title 中使用已废弃的分层分隔符✅storybook/no-redundant-story-name故事不应有冗余的 name 属性✅storybook/no-renderer-packages禁止在 stories 中直接导入 renderer 包storybook/no-stories-ofstoriesOf已废弃不应使用storybook/no-uninstalled-addons识别未安装或名称拼错的 addonstorybook/prefer-pascal-case故事命名应使用 PascalCase✅storybook/story-exportsstory 文件至少包含一个 story 导出storybook/use-storybook-expect应使用storybook/test/storybook/test/storybook/jest的expect✅storybook/use-storybook-testing-library不要在 stories 中直接使用 testing-library✅其中no-uninstalled-addons规则会被施加到.storybook/main.*文件这正是上文.eslintignore取反配置让插件 lint 配置目录的直接价值。插件目录还内置了对应规则的单测见 src/test-utils.ts例如默认以MyComponent.stories.js作为测试用文件名验证规则在真实命名下的行为。验证与后续动作完成上述安装与配置后在项目根目录运行 ESLint 即可看到对 stories 文件的检查结果npx eslint **/*.stories.{ts,tsx,js,jsx}若需在 CI 中强制执行可配合 lint 脚本如lint: eslint . --ext .js,.jsx,.ts,.tsx纳入流水线。欲进一步了解规则细节与贡献方式可继续阅读 code/lib/eslint-plugin/README.md 与 code/lib/eslint-plugin/CONTRIBUTING.md。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考