Storybook 深入指南：在 .storybook/main.ts 中扩展 TypeScript 默认配置

Storybook 深入指南在 .storybook/main.ts 中扩展 TypeScript 默认配置【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybookStorybook 对 TypeScript 采用“零配置优先”的策略安装完成即可编写.ts/.tsx故事并获得 API、参数与组件元数据的自动类型推断。然而当项目对类型检查、docgen 解析或编译链路有更细粒度诉求时就需要在.storybook/main.ts的typescript配置段显式扩展默认行为。本文以官方代码片段 storybook-main-extend-ts-config.md 为骨架结合 TypeScript 集成指南 与 typescript 配置 API 参考系统讲解check、checkOptions、skipCompiler及 React 专属的reactDocgen系列的语义、可用范围、配置写法与底层实现读完后你将能够在任意框架项目中精准调校 Storybook 的 TS 处理管线。一、typescript配置段在 Storybook 中的定位Storybook 的主配置文件.storybook/main.ts本身就是一个用 TypeScript 编写的 ESM 模块。通过为配置对象标注StorybookConfig类型编辑器可以对该文件的每个字段提供自动补全与严格类型检查。typescript正是该配置对象的一个顶层字段专门用来控制Storybook 如何读取、校验并解析 TypeScript 文件。// .storybook/main.ts —— CSF 3 写法renderer 通用模板 // 将 your-framework 替换为你实际使用的框架例如 react-vite、nextjs、vue3-vite、angular 等 import type { StorybookConfig } from storybook/your-framework; const config: StorybookConfig { framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], typescript: { check: false, checkOptions: {}, skipCompiler: false, }, }; export default config;在底层类型系统中该字段由 TypescriptOptions 定义核心层面原生只声明check: boolean与skipCompiler: boolean两个成员且默认值均为false源码注释标明了default false在 StorybookConfigRaw 中则作为typescript?: PartialTypescriptOptions存在因此所有字段均可按需省略。React 渲染器另有一套框架层专属选项reactDocgen、reactDocgenTypescriptOptions从文档结构看可以推断它们由 React 框架包在预设层二次声明与消费下面会单独说明。二、不同框架可见的选项总览可配置字段依框架与构建器而不同。非 React 渲染器Angular、Vue、Web Components、Ember、HTML、Svelte、Preact、Qwik、Solid主要使用下表三项选项说明典型示例check仅在 Webpack 构建器项目可用开启 Storybook 内部类型检查typescript: { check: true }checkOptions依赖check开启用于透传配置fork-ts-checker-webpack-plugintypescript: { checkOptions: {} }skipCompiler关闭通过编译器解析 TypeScript 文件针对 Webpack5typescript: { skipCompiler: false }React 渲染器在此基础上增加两项“docgen 解析器”选项选项说明默认值reactDocgen选择解析 React 组件元数据所用库react-docgen/react-docgen-typescript/false未安装storybook/react时为false已安装时为react-docgenreactDocgenTypescriptOptions要求reactDocgen为react-docgen-typescript透传react-docgen-typescript-pluginWebpack或vite-plugin-react-docgen-typescriptVite—三、从官方模板看默认扩展写法官方片段在“Extending the default configuration”一节中提供了一套开箱即用的示例显式写出三项配置并把它们设为框架默认行为便于你在真实项目里以此为起点按需修改。不同故事格式CSF 3 与试验性的 CSF Next写法上略有差异。CSF 3直接导出StorybookConfig上面“定位”小节中的代码即为 CSF 3 的标准形态从storybook/your-framework导入StorybookConfig类型然后写出包含stories、framework、typescript三个字段的配置对象。其中stories数组负责声明 Story 与文档的扫描范围MDX 与stories.(js|jsx|mjs|ts|tsx)形式的后缀均被覆盖typescript块中的check: false、checkOptions: {}、skipCompiler: false明确写出默认值表明这是“接近开箱即用、无需额外类型处理”的基线状态。CSF Next试验性使用defineMainStorybook 新一代配置 APICSF Next通过defineMain工厂函数获得更强的类型推导此时配置类型来源于框架包中的node子路径导出// .storybook/main.ts —— CSF NextReact 示例 import { defineMain } from storybook/your-framework/node; export default defineMain({ framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], typescript: { check: false, checkOptions: {}, skipCompiler: false, }, });框架差异Vue 与 Web Components 的 CSF Next 变体值得注意的是官方为 Vue3 Vite 与 Web Components Vite 提供的 CSF Next 模板只保留了skipCompiler一项// .storybook/main.ts —— CSF NextVue 示例 import { defineMain } from storybook/vue3-vite/node; export default defineMain({ framework: storybook/vue3-vite, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], typescript: { skipCompiler: false, }, });// .storybook/main.ts —— CSF NextWeb Components 示例 import { defineMain } from storybook/web-components-vite/node; export default defineMain({ framework: storybook/web-components-vite, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], typescript: { skipCompiler: false, }, });// .storybook/main.ts —— CSF NextAngular 示例 import { defineMain } from storybook/angular/node; export default defineMain({ framework: storybook/angular, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], typescript: { check: false, checkOptions: {}, skipCompiler: false, }, });这从侧面印证了官方文档中的限定条件check/checkOptions依赖 Webpack 构建器下的fork-ts-checker-webpack-plugin因此在 Vite 系渲染器的 CSF Next 模板中被省略。也就是说实际可用的typescript选项集合取决于“框架 构建器 渲染器”的组合接入时不要照搬其他技术栈的完整配置。四、逐项解析check、checkOptions 与 skipCompiler4.1check在 Storybook 内部执行类型检查check是布尔开关用于让 Storybook 在运行过程中启用 TypeScript 类型检查。由于底层借助的是 Webpack 生态的fork-ts-checker-webpack-plugin它只在使用 Webpack 构建器时可用若采用 Vite 构建器该字段不生效请按构建器自身的 TS 配置如vite的esbuild/vite-plugin体系处理类型问题。开启方式对应片段 main-config-typescript-check.mdtypescript: { check: true, }开启后类型错误会在 dev 或 build 过程中被上报从而把“写故事/写组件时的类型安全”前移到 Storybook 自身的编译期而不是等到下游应用构建时才暴露。4.2checkOptions透传 fork-ts-checker-webpack-plugin 选项checkOptions只有在check: true时才有意义用于把配置原样交给fork-ts-checker-webpack-plugin。官方示例片段 main-config-typescript-check-options.md展示了如何顺带开启 ESLint 集成typescript: { check: true, checkOptions: { eslint: true, }, }除eslint外该插件还暴露了诸如async、typescript、issue、formatter等大量选项详见插件自身文档。需要强调的是插件只会收到checkOptions里显式写出的键因此当check: false时该字段整体被忽略。4.3skipCompiler跳过“通过编译器解析 TS 文件”skipCompiler与 Webpack5 下的 TS 处理链路相关关闭后Storybook 不再把 TypeScript 文件交给编译器做解析仅按普通模块对待。其默认值是false即默认会走编译器解析这与源码中 TypescriptOptions 标注的default false一致。使用场景通常与“组件元数据/docgen 是否依赖编译产物”相关当你并不需要 Storybook 从编译解析中获取类型信息或遇到编译器解析导致的性能/兼容问题时可以尝试设置typescript: { skipCompiler: true, }官方对它的描述是“Disables parsing Typescript files through the compiler”即仅影响 TS 文件的编译器解析环节并不会关闭 Vite/Webpack 对 TS 的正常转译。五、React 专属docgen 解析器与参数表生成5.1reactDocgen两套解析方案的取舍Storybook 为 React 组件默认启用自动类型推断以生成 Props 表格与 Controls。解析层可选两套库参考片段react-docgen默认解析器速度快但推断覆盖不完整react-docgen-typescript真正调用 TypeScript 编译器做全量推断更准确但更慢false完全关闭组件解析。typescript: { reactDocgen: react-docgen-typescript, }5.2reactDocgenTypescriptOptions细调 TS 解析行为当reactDocgen指定为react-docgen-typescript时可再用reactDocgenTypescriptOptions向底层插件传递选项参考片段例如propFilter、shouldExtractLiteralValuesFromEnum、tsconfigPath等。典型的两个调整动机来自官方疑难解答外部包类型未生成改用react-docgen-typescript以解析第三方库的 TS 声明Monorepo 中 workspace 组件缺失继承参数inherited args这是因为底层 Vite 插件以**/**.tsx为默认include从项目目录建立 TypeScript Programworkspace 包源码位于目录之外导致继承类型无法解析。此时应把 workspace 源码加入include而不是试图通过tsconfigPath解决——后者只影响编译器选项不会改变 Program 纳入哪些文件。react-docgen-typescript需要真正的 TS 编译因此与“快速但可能不完整”的默认解析器相比是典型的速度/准确度权衡这也是官方文档把这类选项单独归为 React 能力的原因。六、落地建议与验证清单按技术栈取模板React/Webpack 系可完整使用checkcheckOptionsskipCompilerVite 系关注skipCompilerReact 追加关注reactDocgen两个选项。更多typescript字段请查阅 main-config-typescript API 参考。先零配置按需开启默认情况下三项核心开关全部为false源码依据Storybook 已经能正常构建与展示 TS 故事。仅当需要编译期类型检查、docgen 精细化解析或规避特定兼容问题时才显式开启相应项。写完配置后自检重新启动storybook dev确认没有因为check引入的伪报错、Props 表格是否如期出现继承参数以及 Vite/Webpack 下的构建时长相较修改前是否在可接受范围。完整的 TypeScript 能力不止于main.ts故事文件本身使用Meta/StoryObj泛型与satisfies操作符可进一步提升类型安全相关写法请继续阅读 docs/configure/integration/typescript.mdx 中的“Write stories with TypeScript”与“Troubleshooting”章节它们与本篇的typescript配置段同属一套 TS 体验。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考