Storybook 中 storybook/preact-vite 框架选项配置详解.storybook/main 实战指南本指南围绕 Storybook 官方文档中的preact-vite-framework-options片段讲解在.storybook/main.js/main.ts中为 Preact Vite 框架声明framework.options的正确写法。文章不仅还原官方配置骨架更结合当前仓库中storybook/preact-vite的 TypeScript 类型定义、preset 实现与 Vite builder 的参数源码说明options究竟可以配置什么、如何透传给构建器帮助你写出类型安全、参数精准的 Storybook 配置。一、为什么要用framework.optionsStorybook 通过main配置文件中的framework字段来决定使用哪套渲染器与构建器组合。对 Preact 项目而言最常用的取值是storybook/preact-vite它的 renderer 能力来自storybook/preact打包与开发服务器能力来自storybook/builder-vite见 code/frameworks/preact-vite/package.json 的依赖声明。但framework不只可以写成一个字符串还可以写成对象形式framework: { name: storybook/preact-vite, options: { // ... }, },options就是框架层面的可调参数。它不负责 Preact 组件代码本身而是用来精细控制 Storybook 这个框架实例的构建行为——从源码类型看这一层目前唯一暴露的入口是Vite builder 的选项详见后文相当于在框架与底层构建器之间保留了一条受控的配置通道。二、配置骨架在.storybook/main中挂载 options官方文档片段给出了两种语言下的标准写法与项目是否使用 TypeScript 无关结构完全一致。JavaScript 版本.storybook/main.jsexport default { framework: { name: storybook/preact-vite, options: { // ... }, }, };TypeScript 版本.storybook/main.tsimport type { StorybookConfig } from storybook/preact-vite; const config: StorybookConfig { framework: { name: storybook/preact-vite, options: { // ... }, }, }; export default config;两段代码的核心语义完全一致framework.name指向框架包framework.options存放该框架的附加配置。TS 版本额外引入了storybook/preact-vite导出的StorybookConfig类型让整个 config 对象包括framework.options内的字段获得编译期校验——options中一旦出现框架不认识的顶层字段类型系统就会给出提示。三、options.builder把参数透传给 Vite 构建器options里究竟能放什么这是配置者最关心的问题。综合官方页面见 docs/get-started/frameworks/preact-vite.mdx 的 API / Options 小节与源码类型定义答案非常清晰官方 API 文档声明builder字段的类型为Recordstring, any用于配置框架所用构建器的选项该框架所用的构建器即 Vite builder其可用选项详见 docs/builders/vite.mdx。具体到本仓库的源码code/frameworks/preact-vite/src/types.ts 给出了严格的类型边界export type FrameworkOptions { builder?: BuilderOptions; };其中BuilderOptions从storybook/builder-vite导入。这意味着storybook/preact-vite的framework.options在类型层面就是一个透传层配置对象本身不定义业务化参数而是把builder下的配置原样交给 Vite 构建器。Vite builder 支持的具体选项查阅 code/builders/builder-vite/src/types.ts 可确认当前两个核心选项及其语义选项类型作用与注意事项viteConfigPathstringVite 配置文件路径相对于process.cwd()。当你希望 Storybook 使用一个独立的 Vite 配置而不是项目根目录默认的vite.config时设置它。configLoaderbundle \| runner \| native控制 Vite 加载配置文件的方式等价于 Vite CLI 的--configLoader标志与loadConfigFromFile的configLoader选项。要求 Vite 6.1.0 及以上在更低版本上会被静默忽略。对应的一个可落地示例JS 版export default { framework: { name: storybook/preact-vite, options: { builder: { // 使用独立的 Vite 配置文件 viteConfigPath: .storybook/vite.config.ts, }, }, }, };TS 版在StorybookConfig约束下写法一致且viteConfigPath、configLoader的取值会被逐字校验。四、源码视角options 是如何接线到构建器的要理解为什么options只有一个builder通道看框架的 preset 实现即可。当前仓库中 code/frameworks/preact-vite/src/preset.ts 的代码非常简短export const core: StorybookConfig[core] { builder: import.meta.resolve(storybook/builder-vite), renderer: import.meta.resolve(storybook/preact/preset), }; export const viteFinal: StorybookConfig[viteFinal] async (config) { // TODO: Add docgen plugin per issue https://github.com/storybookjs/storybook/issues/19739 return config; };从中可以推断出三条实现事实框架默认不额外改动 Vite 配置viteFinal目前原样返回config源码注释也标明尚未接入 docgen 插件对应一个 GitHub issue 的 TODO。也就是说当前版本下storybook/preact-vite自身没有吃掉任何专属 options 字段真正的扩展点都收敛到了 Vite 构建器层。构建器选项最终流入 buildertypes.ts中FrameworkOptions的结构把用户输入限定在builder键下与该 preset 声明的core.builderstorybook/builder-vite一一对应——框架收到的options.builder会作为 Vite 构建器初始化参数使用。同一FrameworkOptions同时约束core.builder.optionstypes.ts中core的类型同样复用了来自 builder 的BuilderOptions因此你在.storybook/main.ts的framework.options.builder里写的参数与直接在core.builder上配置所依据的类型规范是一致的。五、从 Webpack 迁移替换 framework 名即可启用 optionsframework.options是否生效取决于framework.name指向的是哪个框架。官方片段见 docs/_snippets/preact-vite-add-framework.md演示了把既有配置从旧框架切换为storybook/preact-vite的标准动作将framework一行从旧的storybook/preact-webpack5改为storybook/preact-viteJS 与 TS 写法对称。迁移后如需继续细化构建参数直接把前文所述的options对象补充到新的 framework 条目下即可例如import type { StorybookConfig } from storybook/preact-vite; const config: StorybookConfig { framework: { name: storybook/preact-vite, options: { builder: { configLoader: bundle, }, }, }, }; export default config;注意configLoader生效的前提是项目 Vite 版本不低于 6.1.0关于版本要求的权威信息可参考 code/frameworks/preact-vite/package.json 中的peerDependenciespreact 10、vite ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0。六、类型安全三件套与常见误区使用 defineMain 提升校验体验storybook/preact-vite除默认入口外还暴露了./node子路径其中 code/frameworks/preact-vite/src/node/index.ts 提供了defineMain辅助函数配合官方 snippet 中直接 import 的StorybookConfig类型可以二选一使用import { defineMain } from storybook/preact-vite/node; export default defineMain({ framework: { name: storybook/preact-vite, options: { builder: { viteConfigPath: .storybook/vite.config.ts, }, }, }, });常见误区自查不要往options顶层塞业务参数按当前类型定义options只有builder一个键其余写法即使能跑也不会被类型系统认可。不要把builder与viteFinal混为一谈options.builder是给构建器的初始化参数如需对 Vite 配置本身做编程式修改追加插件、改 alias 等应使用viteFinal钩子。configLoader有版本下限在 Vite 6.1.0 时该选项会被静默忽略配置前请核对构建环境版本。小结preact-vite-framework-options看似只是一个配置骨架但其背后贯穿了 Storybook 的框架抽象设计framework.options是框架与底层构建器之间的受控参数通道而storybook/preact-vite当前只透传builder选项。掌握了.storybook/main.js/.storybook/main.ts中的书写方式再结合viteConfigPath与configLoader两个参数及类型层面的约束你就能像查阅任何一份 Storybook 框架文档一样精确、无冗余地为 Preact Vite 项目完成框架级构建配置。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考