Storybook 预设插件 babelDefault API 深度指南如何为 Storybook 注入自定义 Babel 配置【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇指南围绕 Storybook 预设Preset体系中的核心配置 APIbabelDefault展开讲解 addon 作者如何通过它向 Storybook 注入自定义 Babel 插件与预设并与普通用户的babel配置选项区分开来。读完本文你将掌握babelDefault的函数签名、配置写法JS/TS、叠加执行顺序与底层合并机制并能在 docs/addons/writing-presets.mdx 与 code/core/src/core-server/presets/common-preset.ts 的佐证下独立写出可发布的 preset 插件。一、Preset 插件体系与babelDefault的定位Storybook 的预设Preset本质上是预配置好的设置或配置项它让开发者通过一组声明式 API 快速装配并定制 Storybook 的功能与集成。官方文档对预设 API 的划分非常清晰本地预设Local Preset负责将builder 支持、Babel 配置或第三方集成封装成文件根级预设Root-level Preset则面向最终用户负责注册 addon 的 UI 与 preview 特性。babelDefault正是本地预设中用于接管编译链路的那一个 API。它定义在文档 docs/api/main-config/main-config-babel-default.mdx类型签名为(config: Babel.Config, options: Options) Babel.Config | PromiseBabel.Config其中Options的最简形态为{ configType?: DEVELOPMENT | PRODUCTION }。该 API 的作用是在任何用户预设被应用之前先对 Storybook 的 Babel 配置做一次预处理——这一点决定了它是 addon 作者定制编译行为、同时把最终控制权交还用户的关键设计。二、如何在 preset 中实现babelDefault在编写预设时通常会为不同 builder/编译器分别建立独立文件并在统一的preset.js|ts入口中重新导出。官方给出的最小化预设入口文件如下import { webpackFinal as webpack } from ./webpack/webpackFinal; import { viteFinal as vite } from ./vite/viteFinal; import { babelDefault as babel } from ./babel/babelDefault; export const webpackFinal webpack; export const viteFinal vite; export const babelDefault babel;TypeScript 版本由于各 builder 的配置对象类型彼此独立实践中常以any收窄后导出import { webpackFinal as webpack } from ./webpack/webpackFinal; import { viteFinal as vite } from ./vite/viteFinal; import { babelDefault as babel } from ./babel/babelDefault; export const webpackFinal webpack as any; export const viteFinal vite as any; export const babelDefault babel as any;一个可直接运行的实现范例babelDefault的函数本体接收当前 Babel 配置对象返回一份扩展后的新配置。核心技巧在于先展开spread原配置再覆盖、追加你关心的字段这样不会丢失 Storybook 已注入的其他默认项。以下代码来自 docs/_snippets/storybook-addons-preset-babelDefault.md演示了如何为babel/plugin-transform-react-jsx追加插件——这是一种典型的场景你的 addon 需要处理 JSX而使用方项目未必启用该转换export function babelDefault(config) { return { ...config, plugins: [ ...config.plugins, [import.meta.resolve(babel/plugin-transform-react-jsx), {}, preset], ], }; }对应 TypeScript 版本会使用babel/core导出的TransformOptions作为参数类型标注import { TransformOptions } from babel/core; export function babelDefault(config: TransformOptions) { return { ...config, plugins: [ ...config.plugins, [import.meta.resolve(babel/plugin-transform-react-jsx), {}, preset], ], }; }两点值得注意的细节插值数组形态[plugin, {}, preset]是 Babel 插件项的三重元组写法依次表示插件模块/路径、插件选项、以及在plugins中用于去重/标识的name。这里的name被固定为字符串preset。import.meta.resolve这是 Node.js 提供的模块解析 API需在支持该语法的运行环境或经打包器转换后使用可把裸模块说明符解析为绝对路径。相比拼接require.resolve的目录import.meta.resolve(babel/plugin-transform-react-jsx)更能正确处理由包管理器pnpm/yarn PnP 等产生的非扁平node_modules布局。三、babelDefault与babel两类写入者的分工Storybook 将 Babel 相关的配置入口分成两层不同身份的使用者应当各取其一入口目标使用者应用时机覆盖顺序babelDefaultaddon / 预设作者用户预设之前先应用作为基底babel最终用户在.storybook/main.js|ts中配置用户配置阶段后应用可覆盖前者结果配置字段本身定义在 docs/api/main-config/main-config-babel.mdx。在类型层面code/core/src/types/modules/core-common.ts中的StorybookConfigRaw约 第 716-724 行同时声明了二者且注释明确写道 We cannot use a particular Babel type here because we need to support a variety of versions无法在此绑定某个具体 Babel 类型因为需要兼容多种版本因此两个字段都被宽松声明为babel?: any与babelDefault?: any。这意味着你的 preset 中不必也无法强依赖某一个babel/core大版本的类型只要最终产出物是 Babel 可识别的配置对象Storybook 即可消费。推荐的协作模式addon 通过babelDefault提供开箱即用的默认能力终端用户如果希望关闭、调整或替换这些默认插件则在自己的.storybook/main.js|ts中使用babel选项进行覆盖——因为babel在babelDefault之后应用。这正是官方建议 addon 作者使用babelDefault而非babel的根本原因。与既有.babelrc的关系如果你的项目根目录已经存在.babelrc之类的 Babel 配置文件Storybook 会自动检测并采用无需任何额外配置。因此 addon 的babelDefault需要在用户已有 .babelrc / 用户通过babel配置两层之上工作而它选择在管线最早期介入恰好保证后续任何用户级设置都能稳压它一头。一个必须注意的适用前提官方文档特别提醒Babel 配置只对内部使用 Babel 的框架生效。如果目标框架走的是 SWC 或 esbuild 等不同编译器链路例如启用了对应 compiler addon那么babelDefault返回的配置会被直接忽略。在为某个框架编写预设前请先确认该框架的官方编译器方案。四、源码视角babelDefault究竟如何被合并与消费只看 API 用法还不够下面从 Storybook 自身的 core-server 实现中找出它的真实消费点这对理解叠加顺序与为什么必须展开原配置至关重要。在 code/core/src/core-server/presets/common-preset.ts 中babel预设的实现大致如下节选核心逻辑export const babel async (_: unknown, options: Options) { const { presets } options; const babelDefault ((await presets.apply(babelDefault, {}, options)) ?? {}) as Record string, any ; const presetConfig: Recordstring, unknown { targets: { // 与 manager/preview 打包目标一致的最低浏览器版本 chrome: 100, safari: 15, firefox: 91, }, }; // 由 features.babelRemoveBugfixes 控制是否去掉 bugfixes const shouldRemoveBugfixes options?.features babelRemoveBugfixes in options.features options.features.babelRemoveBugfixes; if (!shouldRemoveBugfixes) { presetConfig.bugfixes true; } return { ...babelDefault, overrides: [ ...(babelDefault?.overrides ?? []), { include: /\.(story|stories)\.[cm]?[jt]sx?$/, presets: [[babel/preset-env, presetConfig]], }, ], }; };这段源码揭示了三个关键事实通过presets.apply(babelDefault, ...)汇聚所有已注册 preset包括你在 addon 中导出的babelDefault都会在这一步被依次调用其返回对象会参与后续合并。换言之你的函数返回值不是替换而是注入到配置管线中的一个片段。外层对象采用浅合并、overrides采用深合并外层{ ...babelDefault }会展开 addon 返回的一切字段而overrides数组则会先收集babelDefault.overrides再附加一个 Storybook 内置的 override——它用正则/\.(story|stories)\.[cm]?[jt]sx?$/命中所有 story/stories 文件并对其强制应用按chrome 100 / safari 15 / firefox 91目标配置的babel/preset-env。这保证了即使 addon 或用户放宽了转译目标故事文件也永远不会被转译到低于 Storybook 官方支持浏览器的 ES 级别该行为与 interaction-testing 所需的mount运行时代码支持直接相关。features.babelRemoveBugfixes是一个可调旋钮该 feature flag 关闭时默认开启bugfixes: true只有显式开启该 flag 才会去掉 bugfix 优化。如果你编写的 preset 对babel/preset-env的 bugfix 行为敏感可以留意使用方是否开启了这个features配置。五、完整落地从本地 preset 到发布 addon要使用babelDefault并不需要先把代码发布成 npm 包——Storybook 支持私有预设private preset模式例如你的.storybook/main.js|ts本身就是一个私有预设实例可直接在其中修改行为。而babelDefault属于本地预设文件通常放在 addon 包的src/下并按以下目录组织example-addon/ └── src/ ├── preset.js|ts # 统一入口重新导出 babelDefault/webpackFinal/viteFinal ├── babel/ │ └── babelDefault.js|ts # 本文主角 ├── webpack/ │ └── webpackFinal.js|ts └── vite/ └── viteFinal.js|ts编写完成后把该 preset 目录通过使用方的addons数组或预设组合机制加载即可。最终用户若想兜底调整可在 main.js 配置 中给出export default { babel: (config) ({ ...config, // 这里会作用于 babelDefault 之后的最终配置 }), };六、小结与实践清单围绕babelDefault可以把决策规则压缩成一句话addon 想让所有使用者默认获得某种 Babel 能力用babelDefault终端用户想在自己的项目里改 Babel用babel或在已被自动检测的.babelrc中配置。动手实现时请对照以下清单自查函数总是返回展开后的新对象{ ...config, ... }不要原地修改入参追加插件时复用config.plugins避免覆盖用户已有插件用import.meta.resolve解析插件模块路径以适配非扁平node_modules明确你的目标框架确实走 Babel 编译器链路SWC/esbuild 框架会忽略该配置导出的函数应支持返回PromiseBabel.Config因为类型签名允许异步在preset.js|ts入口统一导出便于同时提供webpackFinal/viteFinal/babelDefault能力。继续深入阅读编写预设完整指南 可查看viteFinal、webpackFinal、managerEntries、previewAnnotations等并列 APImain-config-babel 参考 与 babelDefault 参考 提供了两个入口的类型与适用场景对照若想从实现层继续追踪可阅读 common-preset.ts 中babel预设的完整合并逻辑以及 core-common.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），仅供参考