在 Storybook 中为 Web Components 项目配置 Vite 框架.storybook/main完整接入指南【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇技术指南聚焦于 Storybook 官方框架storybook/web-components-vite的接入方式说明如何在现有 Vite Web Components 项目中通过修改.storybook/main.js|ts配置文件将框架挂载到 Storybook 核心从而以隔离方式开发、文档化和测试自定义元素。读完本文你将掌握从安装依赖、声明 framework 字段到使用StorybookConfig类型与 CSF NextdefineMain的完整配置方案并能理解该框架在 Storybook 内部如何通过 preset 关联 Vite 构建器与 Web Components 渲染器。一、为什么需要显式声明framework字段Storybook 本身是一个与框架无关的 UI 组件工作台它通过framework配置项决定当前项目使用哪一套渲染器 构建器 模板组合。对于使用 Web Components如基于 lit、lit-html 构建的自定义元素并且构建工具为 Vite 的项目官方提供的框架包是storybook/web-components-vite。从当前仓库源码看该框架包位于 code/frameworks/web-components-vite其核心 preset 定义在 src/preset.ts 中export const core: PresetPropertycore { builder: import.meta.resolve(storybook/builder-vite), renderer: import.meta.resolve(storybook/web-components/preset), };这段代码揭示了框架的内部组装关系它把Vite 构建器storybook/builder-vite与Web Components 渲染器storybook/web-components/preset绑定在一起。因此在.storybook/main.js|ts中把framework指向storybook/web-components-vite就等于一次性告知 Storybook用 Vite 编译并启动开发服务器用 Web Components 渲染器把你的自定义元素绘制到画布中。二、安装框架依赖在修改配置文件之前需要先安装框架包。根据仓库文档 web-components-vite-install.md 的说明三种主流包管理器对应的命令如下npm install --save-dev storybook/web-components-vitepnpm add --save-dev storybook/web-components-viteyarn add --dev storybook/web-components-vite从 package.json 可以看到该包的依赖约束它内部依赖storybook/builder-vite与storybook/web-components并以storybook和vite^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0作为 peer 依赖。也就是说使用本框架的项目需要满足Vite ≥ 5的版本要求这与官方文档 web-components-vite.mdx 中记录的版本范围一致。三、在.storybook/main中接入框架核心配置安装完成后编辑项目根目录下的.storybook/main.js或.storybook/main.ts在默认导出的配置对象中新增framework字段。以下是原文档 web-components-vite-add-framework.md 提供的完整配置示例。3.1 纯 JavaScript 配置.storybook/main.jsexport default { // ... framework: storybook/web-components-vite, // Add this };当framework使用字符串形式时Storybook 会直接加载该包并采用包内 preset 的默认设置即上文提到的 Vite 构建器 Web Components 渲染器组合。3.2 TypeScript 配置.storybook/main.ts如果你使用 TypeScript 编写 Storybook 配置可以引入storybook/web-components-vite导出的StorybookConfig类型让编辑器对配置字段进行完整的类型检查与自动补全import type { StorybookConfig } from storybook/web-components-vite; const config: StorybookConfig { // ... framework: storybook/web-components-vite, // Add this }; export default config;StorybookConfig类型定义在 src/types.ts 中它是 Storybook 基础配置、Vite 构建器配置StorybookConfigVite与框架配置StorybookConfigFramework的交集。其中framework字段既支持字符串形式也支持{ name, options }对象形式后者用于传递框架选项详见下文第五节。该类型还约束了core.builder只能是storybook/builder-vite或其带 options 的对象形式从类型层面保证了Web Components 框架只与 Vite 构建器搭配。3.3 CSF Next 配置defineMain写法CSF Next 是 Storybook 推荐的下一代配置方式它通过defineMain包装器提供类型推断无需显式标注泛型。此时需要从包的 Node 子路径导入import { defineMain } from storybook/web-components-vite/node; export default defineMain({ // ... framework: storybook/web-components-vite, // Add this });import { defineMain } from storybook/web-components-vite/node; export default defineMain({ // ... framework: storybook/web-components-vite, // Add this });defineMain的实现位于 src/node/index.ts其源码非常简洁import type { StorybookConfig } from ../types.ts; export function defineMain(config: StorybookConfig) { return config; } export type { StorybookConfig };它接收一个StorybookConfig并原样返回属于典型的类型化包装器在运行时零开销但能让配置对象获得完整的类型约束与推导。由于该函数位于./node子路径导出只应在 Node 环境如.storybook/main配置文件、脚本中使用不应出现在浏览器侧代码中。提示.storybook/main.js与.storybook/main.ts二选一即可二者功能等价。若项目使用 TypeScript推荐main.tsStorybookConfig或defineMain写法以获得类型安全。四、配置完成后如何运行与构建框架接入完成后即可在项目根目录执行 Storybook 标准命令# 以开发模式启动 Storybook storybook dev# 以生产模式构建静态站点 storybook build构建产物默认输出到outputDir指定的目录默认值为storybook-static可在main配置中通过相应字段覆盖。启动成功后Storybook 会使用 Vite 作为构建与开发服务器将stories字段匹配到的故事文件中的 Web Components 渲染到画布中。五、传递框架选项builder配置如果需要对构建器做额外定制可将framework从字符串形式改为对象形式并通过options.builder传递 Vite 构建器选项。原文档 web-components-vite-framework-options.md 给出了三种写法export default { framework: { name: storybook/web-components-vite, options: { // ... }, }, };import type { StorybookConfig } from storybook/web-components-vite; const config: StorybookConfig { framework: { name: storybook/web-components-vite, options: { // ... }, }, }; export default config;import { defineMain } from storybook/web-components-vite/node; export default defineMain({ framework: { name: storybook/web-components-vite, options: { // ... }, }, });import { defineMain } from storybook/web-components-vite/node; export default defineMain({ framework: { name: storybook/web-components-vite, options: { // ... }, }, });对照 src/types.ts 可以看到该框架当前提供的FrameworkOptions仅包含一个可选字段export type FrameworkOptions { builder?: BuilderOptions; };BuilderOptions来自storybook/builder-vite涵盖 Vite 构建器的各项配置能力。需要更细致的 Vite 配置时还可以在main配置中使用viteFinal钩子直接改写 Vite 配置对象参考 main-config-vite-final.md例如注入别名、插件或环境变量——这一机制同样适用于本框架。六、框架包的其他公开能力除了配置入口storybook/web-components-vite的主入口 src/index.ts 还做了如下导出export * from storybook/web-components; export * from ./types.ts; export { __definePreview as definePreview } from storybook/web-components;这意味着在你的 stories 文件中可以直接从storybook/web-components-vite导入Meta、StoryObj等 Web Components 渲染器的全部类型与工具如definePreview实验性 API。仓库自带的模板示例可参考 template/cli/ts/Button.stories.ts它展示了如何结合argTypes、args与render: (args) Button(args)编写一个自定义按钮元素的完整故事可作为接入框架后编写首个故事的起点。七、常见问题与排查要点版本匹配本框架要求 Vite ≥ 5。安装前请确认项目的 Vite 版本满足 peer 依赖范围^5 || ^6 || ^7 || ^8否则可能出现模块解析或构建器不兼容问题。framework与core.builder的关系声明storybook/web-components-vite后一般无需再手动设置core.builder——preset 已自动将构建器解析为storybook/builder-vite。若手动配置注意类型约束要求 builder 必须为 Vite 构建器。CSF Next 导入路径defineMain只能从storybook/web-components-vite/node导入若误从主入口导入会导致 Node 环境下的解析错误。配置文件二选一.storybook/main.js与.storybook/main.ts同时存在时可能引发歧义建议只保留一个。至此你已经完成了从安装到配置的全部步骤。无论采用字符串形式、带类型的StorybookConfig还是 CSF Next 的defineMain其核心都是让framework指向storybook/web-components-vite从而让 Storybook 以 Vite 为构建器、以 Web Components 为渲染器为你提供一个隔离、可文档化、可测试的组件工作台。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考