Storybook 的 SWC 编译配置为 React JSX 启用 automatic runtimemain-config-swc-jsx-transform 实战指南【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook导读本文围绕 Storybook 仓库中的main-config-swc-jsx-transform文档片段展开讲解在基于 Webpack 的 Storybook 项目中如何通过.storybook/main配置文件的swc选项将 SWC 的 React JSX 转换切到runtime: automatic。该配置最常见的落地场景是解决 React 项目在启用 SWC 编译后因 JSX 文件未显式import React而导致的 Storybook 加载失败问题。读完本文你将掌握swc配置函数的签名、四种主流写法JS/TS 与 CSF 3/CSF Next 组合、jsc.transform.react.runtime的取值语义以及该修复方案背后的编译原理与适用范围。问题背景SWC 编译器不会自动导入jsx-runtime在 React 生态中JSX 只是语法糖最终需要被编译成真实的 JavaScript 函数调用。传统classic模式下JSX 会被编译为React.createElement(...)因此要求每个使用 JSX 的文件作用域内都存在React——这也是旧项目里每个jsx/tsx文件顶部都要写import React from react的原因。而在 compilers.mdx 的 Troubleshooting 章节The SWC compiler doesnt work with React中官方明确指出了一个问题如果在 React 项目中启用了 SWC builder且你的jsx/tsx文件没有显式导入 React会导致 Storybook 加载失败。SWC 在通过 SWC builder 编译时不会自动导入jsx-runtime模块。也就是说当编译器按 classic 语义处理、而源码又依赖automatic语义文件不写import React时产物运行时会因找不到 JSX runtime 而报错。要解决这个问题就需要在 Storybook 的配置文件中显式把 SWC 的 React JSX 转换指定为runtime: automatic让编译器在编译期自动注入对react/jsx-runtime的引用而不是把对React的引用写死在产物里。解决方案通过swc配置项开启 automatic runtime修复方式很直接编辑 Storybook 配置文件.storybook/main.js或.storybook/main.ts在导出的配置对象中加入swc选项将jsc.transform.react.runtime设置为automatic。仓库中的 main-config-swc-jsx-transform.md 提供了针对不同项目形态的四种标准写法。CSF 3JavaScript 版本.storybook/main.jsexport default { framework: { name: storybook/your-framework, options: {}, }, swc: (config, options) ({ jsc: { transform: { react: { runtime: automatic, }, }, }, }), };CSF 3TypeScript 版本.storybook/main.ts// Replace your-framework with the webpack-based framework you are using (e.g., react-webpack5) import type { StorybookConfig } from storybook/your-framework; const config: StorybookConfig { framework: { name: storybook/your-framework, options: {}, }, swc: (config, options) ({ jsc: { transform: { react: { runtime: automatic, }, }, }, }), }; export default config;注意CSF 3 的 TypeScript 写法的框架占位符应替换为基于 Webpack 的框架例如react-webpack5因为swc配置只对 Webpack 系的 Storybook 构建生效详见下文适用范围。CSF NextTypeScript 版本.storybook/main.tsCSF Next 是 Storybook 提供的新的 main 配置写法通过defineMain获得更完善的类型推导// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) import { defineMain } from storybook/your-framework/node; export default defineMain({ framework: { name: storybook/your-framework, options: {}, }, swc: (config, options) ({ jsc: { transform: { react: { runtime: automatic, }, }, }, }), });CSF NextJavaScript 版本.storybook/main.js// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) import { defineMain } from storybook/your-framework/node; export default defineMain({ framework: { name: storybook/your-framework, options: {}, }, swc: (config, options) ({ jsc: { transform: { react: { runtime: automatic, }, }, }, }), });CSF Next 的写法中占位符框架不再局限于 Webpack 系示例里给出的react-vite、nextjs、nextjs-vite即为可选项。无论是 CSF 3 还是 CSF Nextswc回调的核心返回值都一致——只要保证返回的 SWC 配置对象里带上了jsc.transform.react.runtime automatic即可。配置项签名与执行语义上述swc并非 Storybook 随意发明的字段而是 main.js/ts 顶层配置 中一个签名固定的配置项Type: (config: swc.Options, options: Options) swc.Options | Promiseswc.Options解读如下第一个入参configStorybook 当前生效的 SWC 选项swc.Options。你可以基于它做增量修改例如({ ...config, jsc: ... })main-config-swc-jsx-transform 文档给出的修正是直接返回一个全新的配置对象——因为该场景的目标是完整接管React 转换语义防止 Storybook 默认配置里残留 classic 模式的相关设定。第二个入参optionsStorybook 注入的上下文选项其类型为{ configType?: DEVELOPMENT | PRODUCTION }你可以据此判断当前是storybook dev还是storybook build从而让配置函数在不同环境返回不同的 SWC 配置。返回值既可以是swc.Options也可以是异步的Promiseswc.Options因此你完全可以在回调里读取文件或调用异步工具后返回结果。jsc字段SWC 的 JavaScript 编译选项命名空间。其中jsc.transform.react专门控制 React/JSX 相关的转换策略runtime可取值classic需要React在作用域中与automatic自动引用 JSX runtime无需显式导入React本文使用的automatic正是新式写法。为什么会出现SWC 不自动导入 jsx-runtime编译链路上的原因从源码结构看Storybook 的编译后端将编译器视为一个独立可枚举的选项。在 webpack.ts 中可以找到这一设计export enum CoreWebpackCompiler { Babel babel, SWC swc, }这意味着对同一个 Webpack 构建Storybook 可以分别按 Babel 或 SWC 两条链路组织编译管线。两者的 React JSX 处理策略并不一致Babel 链路若项目启用了对应 preset如babel/preset-react配合某些场景的自动处理经典/自动两种 runtime 都可能被透明处理兼容性更强SWC 链路由storybook/addon-webpack5-compiler-swc之类的插件将 SWC 接入 Webpack 构建loader 实际编译逻辑可参见 nextjs 的 SWC loader 实现 这类同构代码其行为完全取决于传入的 SWC 配置。一旦jsc.transform.react.runtime缺省或仍为classicSWC 就不会在编译阶段为文件注入react/jsx-runtime的导入语句产物运行时自然访问不到_jsx这类来自 JSX runtime 的符号最终表现为 Storybook 无法加载、控制台出现运行时错误。修复的本质就是把你项目里遵循的免import React约定对应编译器的 automatic 模式显式同步到 Storybook 的 SWC 配置中让 Storybook 的编译口径与你日常构建保持一致。适用范围与限制哪些项目会命中这段配置这段配置不是对每个 Storybook 项目都必需使用时请先核对下列边界条件仅 Webpack 构建链路生效swc配置服务的是 Webpack 场景与之配套的是storybook/addon-webpack5-compiler-swc插件。Vite 等其他构建体系使用各自的 JSX 转换通道不受本配置影响。存在默认排除的框架根据 compilers.mdx 的说明Storybook 对 Webpack 项目默认启用 SWC零配置、更快加载但 Angular、Create React App、Ember.js 与 Next.js 例外——这四类框架不在此默认范围内Next.js 的 SWC 支持目前属于实验性质默认关闭需要显式 opt in 后才能使用Create React App 走的是其自带编译工具链与通用 SWC 配置无关。runtime: automatic需要运行时依赖可达产物编译期会引用react/jsx-runtime请确保项目使用的 React 版本包含该入口React 17 引入 automatic runtime 机制。如果你的项目刻意使用 classic 模式、并在每个文件里显式import React则不需要也不应该套用这段配置。配置函数以最后返回值为准由于swc是回调式的最终生效的是其返回值。若项目同时存在其他 SWC 预设请留意叠加逻辑避免覆盖掉这里设定的runtime。验证与排错建议完成配置后可参考如下步骤验证修复是否生效重启本地开发服务.storybook/main的改动需要重启storybook dev才会重新执行。打开浏览器访问 Storybook确认原先报错的故事页能够正常渲染。若问题依旧可在编译产物中确认 JSX 调用是否以jsx/jsxsautomatic 产物特征而非React.createElement的形式出现以判断配置是否真正生效。需要说明的是本文给出的.storybook/main位置为常规约定若你的项目为 monorepo 或自定义了配置目录请以实际的 Storybook 配置文件为准。若你的 Webpack 项目走的是 Babel 而非 SWC则排查方向应转向 Babel 配置官方亦提供BABEL_SHOW_CONFIG_FOR环境变量用于输出 Babel 对指定文件生效的配置详见 compilers.mdx 的 Troubleshooting 章节。参考资料配置片段原文docs/_snippets/main-config-swc-jsx-transform.md使用该片段的应用文档含问题背景docs/configure/integration/compilers.mdxswc顶层配置项 APIdocs/api/main-config/main-config-swc.mdx编译器枚举类型定义code/core/src/types/modules/webpack.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），仅供参考