Storybook 切换 framework 到 storybook/nextjs-vite从配置原理到迁移实战的完整指南【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本文聚焦 Storybook 仓库中 nextjs-vite-add-framework.md 所演示的核心操作把.storybook/main.js|ts中的framework属性切换到storybook/nextjs-vite并同步更新配置入口的类型导入CSF 3 的StorybookConfig与 CSF Next 的defineMain两种风格。读完后你将能够独立完成 Next.js 项目从 Webpack 系框架如storybook/react-webpack5、storybook/nextjs到 Vite 系框架的切换并理解该配置项在 Storybook 内部到底驱动了哪些构建行为以及切换后还需做哪些收尾工作。一、这条配置改动到底在做什么在 Next.js 项目的 Storybook 中framework字段决定了“用什么框架预设来渲染组件、用什么构建器来打包”。切换到storybook/nextjs-vite的完整改动如下对应 nextjs-vite-add-framework.md 中的 diff 片段JavaScript 项目.storybook/main.jsCSF 3export default { // ... - framework: storybook/react-webpack5, framework: storybook/nextjs-vite, };TypeScript 项目.storybook/main.tsCSF 3——注意导入的类型来源也要同步更换- import type { StorybookConfig } from storybook/your-previous-framework; import type { StorybookConfig } from storybook/nextjs-vite; const config: StorybookConfig { // ... - framework: storybook/react-webpack5, framework: storybook/nextjs-vite, }; export default config;新配置风格CSF Next 实验性写法defineMain从框架包的/node入口导入- import { defineMain } from storybook/your-previous-framework/node; import { defineMain } from storybook/nextjs-vite/node; export default defineMain({ // ... - framework: storybook/react-webpack5, framework: storybook/nextjs-vite, });仓库源码可以佐证这两处导入的真实来源/node入口确实存在。package.json 的exports字段声明了./node: { code: ./src/node/index.ts, ... }而 node/index.ts 的内容非常简洁——它只导出一个defineMain(config)函数原样返回带storybook/nextjs-vite类型约束的StorybookConfig对象import type { StorybookConfig } from ../types.ts; export function defineMain(config: StorybookConfig) { return config; }因此把defineMain的导入路径从旧框架换成storybook/nextjs-vite/node本质上是让main.ts里的framework与core.builder字段获得storybook/nextjs-vite专属的类型约束。类型层面也做了框架绑定。types.ts 中定义了FrameworkName CompatibleStringstorybook/nextjs-viteStorybookConfig类型要求framework只能是storybook/nextjs-vite或{ name, options }对象形式且core.builder只能是storybook/builder-vite。如果你把framework写错TypeScript 会直接报错——这也是为什么 diff 里要求同步更换StorybookConfig的类型导入。二、切换后的底层行为preset 是如何工作的仅改framework字段之所以能完成整个构建链的切换是因为框架包通过 preset 预设接管了构建器与渲染器。查看 preset.ts 可以看到关键实现export const core: PresetPropertycore { builder: import.meta.resolve(storybook/builder-vite), renderer: import.meta.resolve(storybook/react/preset), };从源码结构看core.builder指向storybook/builder-vitecore.renderer指向storybook/reactpreset——也就是说framework: storybook/nextjs-vite一句配置实际等价于“Vite 构建器 React 渲染器”的组合这正是它与storybook/nextjsWebpack 5 构建器的核心区别previewAnnotations会把storybook/nextjs-vite/preview以及 Next.js 16 以下的兼容版storybook/nextjs-vite/config/preview追加为 preview 注解从而注入路由/导航桩、next/image与next/font支持、next/head装饰器等 preview 层能力这些能力无需用户额外注册viteFinal会先调用storybook/react-vite/preset的viteFinal拿到基础 React Vite 配置然后在此基础上自动归一化 PostCSS 配置normalizePostCssConfig从而支持你项目里的 Tailwind/PostCSS 定制、把styled-jsx及其style子模块写入resolve.alias零配置支持 styled-jsx、最后追加vitePluginStorybookNextjs插件来处理nextConfigPath/image等框架选项。三、framework 的 options 参数切换时的进阶配置types.ts 中的FrameworkOptions定义了切换framework时可同时传入的选项写作对象形式export type FrameworkOptions { /** The path to the Next.js configuration file. */ nextConfigPath?: string; image?: { includeFiles?: string[]; excludeFiles?: string[]; }; builder?: BuilderOptions; };对应的.storybook/main.ts用法取自 nextjs-vite.mdx 的 Options 一节import type { StorybookConfig } from storybook/nextjs-vite; const config: StorybookConfig { // ... framework: { name: storybook/nextjs-vite, options: { // 当 next.config.js 不在项目根目录时必须提供 nextConfigPath: /path/to/your/next.config.js, }, }, }; export default config;各选项的作用结合 preset.ts 中options.presets.applyFrameworkOptions(frameworkOptions)的消费逻辑nextConfigPathstringnext.config.js的绝对路径。preset 会取它的dirname作为dir传给 Next.js 的 Vite 插件用于定位你的 Next.js 项目结构imageobject与 Vite 插件交互的图片处理选项含includeFiles/excludeFiles过滤规则决定哪些文件走next/image风格的导入转换builderRecordstring, any透传给storybook/builder-vite的构建器选项如test相关配置。框架贡献的 stories 参数则在NextJsParameters中声明同样见 types.tsnextjs.appDirectoryboolean默认falsenext/navigation组件故事需置true、nextjs.navigationnext/navigation上下文覆盖与nextjs.routernext/router上下文覆盖可按 story / meta / 项目三级 parameters 继承。这些参数在切换到该框架后即可直接使用是它与旧 Webpack 框架相比新增的运行时能力。四、切换前后的收尾工作framework字段只是迁移的一部分。nextjs-vite.mdx 的 “Manual migration” 章节本文关联 diff 片段的实际使用处指出了切换后必须核对的两件事webpackFinal→viteFinal如果旧配置里存在自定义 Webpack 操作webpackFinal需要手工改写成等价的 Vite 配置viteFinal。注意并非所有 Webpack 修改可以原样照搬需结合 Vite 的插件与 resolve 机制重写.md文件导入Webpack 时代直接import content from ./doc.md得到的字符串行为在 Vite 下需要显式加?raw后缀。此外若你之前用独立的插件addon来集成 Next.js 的路由/导航能力切换到该框架后这些能力已由框架内置相关插件可以移除。更稳妥的做法automigrate 工具如果你的旧框架是storybook/nextjs仓库内置了自动迁移工具等价于上面所有手工步骤npx storybook automigrate nextjs-to-nextjs-vite从 nextjs-to-nextjs-vite.ts 的源码可以确认它执行三步动作与本文“Manual migration”完全对应更新所有package.json移除storybook/nextjs按当前 Storybook 版本添加storybook/nextjs-vite若项目未装 Vite还会补装vite^7.0.0见源码中的VITE_DEFAULT_VERSION改写.storybook/main.js|ts用负向先行断言正则/storybook\/nextjs(?!-vite)/g精确替换框架名避免误伤已经是-vite的引用扫描 stories 与配置目录中的所有导入语句把storybook/nextjs的导入批量重写为storybook/nextjs-vite。而本文关联文档覆盖的场景是从任意旧框架示例中为storybook/react-webpack5切入storybook/nextjs-vite这类切换没有自动工具需要按第一、二节的 diff 手工完成。五、版本前提与验证清单从 package.json 的peerDependencies可确认适用前提next要求^14.1.0 || ^15.0.0 || ^16.0.0vite要求^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0React 支持 16.8 至 19.x。切换完成后建议按以下清单验证framework字段与StorybookConfig/defineMain的导入源已同步为storybook/nextjs-viteTypeScript 项目若不同步类型检查会报错旧的webpackFinal已迁移为viteFinal.md导入已加?raw启动 dev server 后next/image、next/font、路由/导航桩与nextjs.*参数按预期工作详见 nextjs-vite.mdx 各特性章节。参考路径docs/_snippets/nextjs-vite-add-framework.md —— 本文关联的 framework 切换 diff 片段docs/get-started/frameworks/nextjs-vite.mdx —— 该框架的完整文档安装、配置、API、FAQcode/frameworks/nextjs-vite/src/preset.ts ——core/previewAnnotations/viteFinal预设实现code/frameworks/nextjs-vite/src/node/index.ts ——defineMain入口code/frameworks/nextjs-vite/src/types.ts ——StorybookConfig、FrameworkOptions、NextJsParameters类型定义code/lib/cli-storybook/src/automigrate/fixes/nextjs-to-nextjs-vite.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），仅供参考 Storybook 切换 framework 到 @storybook/nextjs-vite：从配置原理到迁移实战的完整指南
Storybook 切换 framework 到 storybook/nextjs-vite从配置原理到迁移实战的完整指南【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本文聚焦 Storybook 仓库中 nextjs-vite-add-framework.md 所演示的核心操作把.storybook/main.js|ts中的framework属性切换到storybook/nextjs-vite并同步更新配置入口的类型导入CSF 3 的StorybookConfig与 CSF Next 的defineMain两种风格。读完后你将能够独立完成 Next.js 项目从 Webpack 系框架如storybook/react-webpack5、storybook/nextjs到 Vite 系框架的切换并理解该配置项在 Storybook 内部到底驱动了哪些构建行为以及切换后还需做哪些收尾工作。一、这条配置改动到底在做什么在 Next.js 项目的 Storybook 中framework字段决定了“用什么框架预设来渲染组件、用什么构建器来打包”。切换到storybook/nextjs-vite的完整改动如下对应 nextjs-vite-add-framework.md 中的 diff 片段JavaScript 项目.storybook/main.jsCSF 3export default { // ... - framework: storybook/react-webpack5, framework: storybook/nextjs-vite, };TypeScript 项目.storybook/main.tsCSF 3——注意导入的类型来源也要同步更换- import type { StorybookConfig } from storybook/your-previous-framework; import type { StorybookConfig } from storybook/nextjs-vite; const config: StorybookConfig { // ... - framework: storybook/react-webpack5, framework: storybook/nextjs-vite, }; export default config;新配置风格CSF Next 实验性写法defineMain从框架包的/node入口导入- import { defineMain } from storybook/your-previous-framework/node; import { defineMain } from storybook/nextjs-vite/node; export default defineMain({ // ... - framework: storybook/react-webpack5, framework: storybook/nextjs-vite, });仓库源码可以佐证这两处导入的真实来源/node入口确实存在。package.json 的exports字段声明了./node: { code: ./src/node/index.ts, ... }而 node/index.ts 的内容非常简洁——它只导出一个defineMain(config)函数原样返回带storybook/nextjs-vite类型约束的StorybookConfig对象import type { StorybookConfig } from ../types.ts; export function defineMain(config: StorybookConfig) { return config; }因此把defineMain的导入路径从旧框架换成storybook/nextjs-vite/node本质上是让main.ts里的framework与core.builder字段获得storybook/nextjs-vite专属的类型约束。类型层面也做了框架绑定。types.ts 中定义了FrameworkName CompatibleStringstorybook/nextjs-viteStorybookConfig类型要求framework只能是storybook/nextjs-vite或{ name, options }对象形式且core.builder只能是storybook/builder-vite。如果你把framework写错TypeScript 会直接报错——这也是为什么 diff 里要求同步更换StorybookConfig的类型导入。二、切换后的底层行为preset 是如何工作的仅改framework字段之所以能完成整个构建链的切换是因为框架包通过 preset 预设接管了构建器与渲染器。查看 preset.ts 可以看到关键实现export const core: PresetPropertycore { builder: import.meta.resolve(storybook/builder-vite), renderer: import.meta.resolve(storybook/react/preset), };从源码结构看core.builder指向storybook/builder-vitecore.renderer指向storybook/reactpreset——也就是说framework: storybook/nextjs-vite一句配置实际等价于“Vite 构建器 React 渲染器”的组合这正是它与storybook/nextjsWebpack 5 构建器的核心区别previewAnnotations会把storybook/nextjs-vite/preview以及 Next.js 16 以下的兼容版storybook/nextjs-vite/config/preview追加为 preview 注解从而注入路由/导航桩、next/image与next/font支持、next/head装饰器等 preview 层能力这些能力无需用户额外注册viteFinal会先调用storybook/react-vite/preset的viteFinal拿到基础 React Vite 配置然后在此基础上自动归一化 PostCSS 配置normalizePostCssConfig从而支持你项目里的 Tailwind/PostCSS 定制、把styled-jsx及其style子模块写入resolve.alias零配置支持 styled-jsx、最后追加vitePluginStorybookNextjs插件来处理nextConfigPath/image等框架选项。三、framework 的 options 参数切换时的进阶配置types.ts 中的FrameworkOptions定义了切换framework时可同时传入的选项写作对象形式export type FrameworkOptions { /** The path to the Next.js configuration file. */ nextConfigPath?: string; image?: { includeFiles?: string[]; excludeFiles?: string[]; }; builder?: BuilderOptions; };对应的.storybook/main.ts用法取自 nextjs-vite.mdx 的 Options 一节import type { StorybookConfig } from storybook/nextjs-vite; const config: StorybookConfig { // ... framework: { name: storybook/nextjs-vite, options: { // 当 next.config.js 不在项目根目录时必须提供 nextConfigPath: /path/to/your/next.config.js, }, }, }; export default config;各选项的作用结合 preset.ts 中options.presets.applyFrameworkOptions(frameworkOptions)的消费逻辑nextConfigPathstringnext.config.js的绝对路径。preset 会取它的dirname作为dir传给 Next.js 的 Vite 插件用于定位你的 Next.js 项目结构imageobject与 Vite 插件交互的图片处理选项含includeFiles/excludeFiles过滤规则决定哪些文件走next/image风格的导入转换builderRecordstring, any透传给storybook/builder-vite的构建器选项如test相关配置。框架贡献的 stories 参数则在NextJsParameters中声明同样见 types.tsnextjs.appDirectoryboolean默认falsenext/navigation组件故事需置true、nextjs.navigationnext/navigation上下文覆盖与nextjs.routernext/router上下文覆盖可按 story / meta / 项目三级 parameters 继承。这些参数在切换到该框架后即可直接使用是它与旧 Webpack 框架相比新增的运行时能力。四、切换前后的收尾工作framework字段只是迁移的一部分。nextjs-vite.mdx 的 “Manual migration” 章节本文关联 diff 片段的实际使用处指出了切换后必须核对的两件事webpackFinal→viteFinal如果旧配置里存在自定义 Webpack 操作webpackFinal需要手工改写成等价的 Vite 配置viteFinal。注意并非所有 Webpack 修改可以原样照搬需结合 Vite 的插件与 resolve 机制重写.md文件导入Webpack 时代直接import content from ./doc.md得到的字符串行为在 Vite 下需要显式加?raw后缀。此外若你之前用独立的插件addon来集成 Next.js 的路由/导航能力切换到该框架后这些能力已由框架内置相关插件可以移除。更稳妥的做法automigrate 工具如果你的旧框架是storybook/nextjs仓库内置了自动迁移工具等价于上面所有手工步骤npx storybook automigrate nextjs-to-nextjs-vite从 nextjs-to-nextjs-vite.ts 的源码可以确认它执行三步动作与本文“Manual migration”完全对应更新所有package.json移除storybook/nextjs按当前 Storybook 版本添加storybook/nextjs-vite若项目未装 Vite还会补装vite^7.0.0见源码中的VITE_DEFAULT_VERSION改写.storybook/main.js|ts用负向先行断言正则/storybook\/nextjs(?!-vite)/g精确替换框架名避免误伤已经是-vite的引用扫描 stories 与配置目录中的所有导入语句把storybook/nextjs的导入批量重写为storybook/nextjs-vite。而本文关联文档覆盖的场景是从任意旧框架示例中为storybook/react-webpack5切入storybook/nextjs-vite这类切换没有自动工具需要按第一、二节的 diff 手工完成。五、版本前提与验证清单从 package.json 的peerDependencies可确认适用前提next要求^14.1.0 || ^15.0.0 || ^16.0.0vite要求^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0React 支持 16.8 至 19.x。切换完成后建议按以下清单验证framework字段与StorybookConfig/defineMain的导入源已同步为storybook/nextjs-viteTypeScript 项目若不同步类型检查会报错旧的webpackFinal已迁移为viteFinal.md导入已加?raw启动 dev server 后next/image、next/font、路由/导航桩与nextjs.*参数按预期工作详见 nextjs-vite.mdx 各特性章节。参考路径docs/_snippets/nextjs-vite-add-framework.md —— 本文关联的 framework 切换 diff 片段docs/get-started/frameworks/nextjs-vite.mdx —— 该框架的完整文档安装、配置、API、FAQcode/frameworks/nextjs-vite/src/preset.ts ——core/previewAnnotations/viteFinal预设实现code/frameworks/nextjs-vite/src/node/index.ts ——defineMain入口code/frameworks/nextjs-vite/src/types.ts ——StorybookConfig、FrameworkOptions、NextJsParameters类型定义code/lib/cli-storybook/src/automigrate/fixes/nextjs-to-nextjs-vite.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），仅供参考