Nx Nuxt Storybook 配置生成器实战指南从nx/nuxt:storybook-configuration到交互测试与 Story 自动化生成【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nxnx/nuxt:storybook-configuration是 Nx 为 Nuxt 项目提供的 Storybook 配置生成器它在底层复用nx/vue:storybook-configuration生成器并额外注入 Nuxt 特有的样式导入与tsconfig.storybook.json处理帮助你一键为 Nuxt 应用搭建基于 Vue 3 Vite 的 Storybook 环境。读完本文你将掌握该生成器的全部交互提示与命令行参数interactionTests、generateStories、ignorePaths、js、tsConfiguration、configureStaticServe等理解其内部调用链与测试验证方式并能结合仓库源码灵活定制 Story 的生成范围与文件格式。生成器概述Nuxt 项目里的 Storybook 骨架该生成器会为你的Nuxt项目搭建完整的 Storybook 配置。它的设计哲学是复用而非重造nx/nuxt:storybook-configuration在底层直接调用nx/vue:storybook-configuration生成器见 packages/nuxt/src/generators/storybook-configuration/configuration.ts而 Vue 生成器又会调用nx/storybook的configurationGenerator最终形成一条完整的生成链路nx/nuxt:storybook-configuration └─ nx/vue:storybook-configuration ├─ nx/storybook configurationGenerator生成 .storybook/main.ts、preview 等 └─ nx/vue storiesGenerator为组件生成 .stories.ts最基本的用法是在终端中执行nx g nx/nuxt:storybook-configuration project-name其中project-name是你要生成配置的 Nuxt 项目名。运行生成器时Nx 会以交互式提示prompt的方式向你询问以下问题项目name要为哪个项目生成 Storybook 配置必填否则生成器无法运行。是否启用 Storybook 交互测试interactionTests选择yes后会在你的 stories 中添加play函数安装全部所需依赖并在项目project.json中生成一个test-storybook目标其命令用于调用 Storybooktest-runner。是否为项目中的组件自动生成 storiesgenerateStories选择yes后会在每个组件旁边生成对应的.stories.ts文件。关于交互测试的完整细节play函数写法、test-runner使用方式等可参考 Nx 官方文档中 Storybook for Vue 概览页 与 Nx Storybook 交互测试文档 的相关章节对应仓库中的 overview-vue.md 与 storybook-interaction-tests.md。重要默认行为默认情况下该生成器会自动启用 Storybook 交互测试。如果你不希望启用可以显式传入--interactionTestsfalse但官方并不推荐这样做——交互测试是保证组件行为正确性的重要手段。交互测试背后的依赖test-storybook目标在 schema 中interactionTests的默认值为true见 packages/nuxt/src/generators/storybook-configuration/schema.json。启用后生成器会在 stories 文件中注入play函数模拟用户交互并断言结果自动安装storybook/test-runner等必要依赖在项目project.json中注册test-storybook目标方便你随时通过nx test-storybook project-name运行回归测试。生成器内部实现Nuxt 特有的三步定制与纯 Vue 生成器相比Nuxt 版本在调用 Vue 生成器之后还做了三件关键的事见 configuration.ts① 判断源码目录结构。生成器读取项目的sourceRoot根据它以/app还是/src结尾来决定源码目录名——Nuxt v4 默认使用app/目录Nuxt v3 使用src/旧版本向后兼容时回退到srcconst sourceDir sourceRoot?.endsWith(/app) ? app : sourceRoot?.endsWith(/src) ? src : src; // default to src for backward compatibility② 写入 Nuxt 特有的样式导入。生成器在.storybook/目录下根据tsConfiguration决定是preview.ts还是preview.js写入一行 CSS 导入把 Nuxt 应用入口的全局样式带进 Storybooktree.write( joinPathFragments(root, .storybook, preview. (tsConfiguration ? ts : js)), import ../${sourceDir}/assets/css/styles.css; );这就是测试快照中preview.ts内容为import ../src/assets/css/styles.css;的原因见snapshots/configuration.spec.ts.snap。③ 修正tsconfig.storybook.json。将compilerOptions.composite强制设为true确保 Storybook 的 TypeScript 项目引用project references能正常工作updateJson(tree, ${root}/tsconfig.storybook.json, (json) { json.compilerOptions { ...json.compilerOptions, composite: true }; return json; });生成器注册与版本校验该生成器在nx/nuxt插件的generators.json中注册见 packages/nuxt/generators.json工厂函数指向./dist/src/generators/storybook-configuration/configurationschema 指向同目录下的schema.json并在examplesFile字段中引用了本文所对应的 storybook-configuration-examples.md。生成器执行前还会调用assertSupportedNuxtVersion(tree)见 configuration.ts确保当前工作区使用的 Nuxt 版本在插件支持范围内。完整参数一览schema 定义除交互式提示外该生成器还支持通过命令行显式传入以下参数完整定义见 packages/nuxt/src/generators/storybook-configuration/schema.jsonTypeScript 类型见同目录的 schema.d.ts参数类型默认值说明projectstring—必填要生成 Storybook 配置的项目名支持别名name、projectName也是第一个位置参数interactionTestsbooleantrue是否启用 Storybook 交互测试别名configureTestRunnergenerateStoriesbooleantrue是否为项目中的组件自动生成*.stories.ts文件configureStaticServebooleantrue是否配置静态文件服务器目标用于加速 CI 构建/测试jsbooleanfalse生成 JavaScript 故事文件.stories.js而非 TypeScripttsConfigurationbooleantrue是否使用 TypeScript 配置生成main.ts/preview.ts而非main.js/preview.jslinterstring—运行 lint 检查的工具可选eslint或oxlintignorePathsstring[][*.stories.ts,*.stories.tsx,*.stories.js,*.stories.jsx,*.stories.mdx]查找组件时需要忽略的路径glob 模式数组其中project是唯一必填参数不提供name时生成器无法工作。实战示例示例一生成 Storybook 配置基础用法nx g nx/nuxt:storybook-configuration ui这将为ui项目生成 Storybook 配置并默认使用TypeScript编写 Storybook 配置文件——即.storybook目录下的文件为.storybook/main.ts等。生成的main.ts快照内容如下见 configuration.spec.ts.snapimport type { StorybookConfig } from storybook/vue3-vite; import { nxViteTsPaths } from nx/vite/plugins/nx-tsconfig-paths.plugin; import { mergeConfig } from vite; import vue from vitejs/plugin-vue; const config: StorybookConfig { stories: [../src/**/*.(mdx|stories.(js|jsx|ts|tsx))], addons: [], framework: { name: storybook/vue3-vite, options: {}, }, viteFinal: async (config) mergeConfig(config, { plugins: [vue(), nxViteTsPaths()], }), }; export default config;可以看到Nuxt 项目的 Storybook 使用storybook/vue3-vite作为 UI 框架这个选择来自 Vue 生成器内部传入的uiFramework: storybook/vue3-vite见 packages/vue/src/generators/storybook-configuration/configuration.ts并通过viteFinal合并了vitejs/plugin-vue与 Nx 的nxViteTsPaths插件后者负责解析 Nx workspace 的 TypeScript 路径别名。同时生成的tsconfig.storybook.json会继承项目 tsconfig开启composite并把 stories 文件与.storybook/*.ts纳入编译范围见 configuration.spec.ts.snap。示例二生成 stories 时忽略特定路径nx g nx/nuxt:storybook-configuration ui --generateStoriestrue --ignorePathslibs/ui/src/not-stories/**,**/**/src/**/*.other.*,apps/my-app/**/*.something.ts这个命令会为ui项目生成 Storybook 配置并为libs/ui/src/lib目录下的组件生成 stories但会跳过以下三类文件libs/ui/src/not-stories目录下的组件apps/my-app目录下以.something.ts结尾的文件文件名符合*.other.*模式的组件。这一能力在项目里包含不适合独立展示的组件通常作为更大组件的一部分使用时非常有用。忽略规则基于 picomatch。默认忽略规则Nx 默认会忽略所有已存在的 Story 文件本身避免重复生成*.stories.ts, *.stories.tsx, *.stories.js, *.stories.jsx, *.stories.mdx不过你可以像上面的例子一样轻松覆盖这一行为。示例三用 JavaScript 生成 storiesnx g nx/nuxt:storybook-configuration ui --generateStoriestrue --jstrue这会为ui项目中所有组件生成JavaScript版本的 stories 文件——即在组件旁边生成.stories.js而非.stories.ts。底层 stories 生成器在生成文件时会根据js参数从files/ts或files/js模板目录中选择对应模板见 packages/vue/src/generators/stories/lib/component-story.ts。示例四用 JavaScript 编写 Storybook 配置nx g nx/nuxt:storybook-configuration ui --tsConfigurationfalse默认情况下生成器使用 TypeScript 编写 Storybook 配置文件。传入--tsConfigurationfalse后.storybook目录下生成的文件将是 JavaScript 版本如.storybook/main.js。tsConfiguration同样会影响 Nuxt 特有样式导入文件的命名——当其为false时生成器写入的是.storybook/preview.js见 configuration.ts。深入原理组件发现、props 解析与只给组件生成 stories理解生成器如何找到组件、如何生成 stories有助于你在复杂项目里预判结果。底层nx/vue的 stories 生成器见 stories.ts会扫描以下三类目录{sourceRoot}/app应用默认组件目录Nuxt v4 的app/结构{sourceRoot}/lib库默认组件目录{sourceRoot}/componentsNuxt 特有的附加组件目录。扫描时会跳过以_开头的私有文件、命中ignorePaths的文件以及已经存在.stories.js/.stories.ts的文件只对*.vue文件生成 stories。页面不会生成 stories——这一点有测试明确验证在 configuration.spec.ts 中测试在src/components/my-component/my-component.vue旁生成组件 story断言.stories.ts存在而src/pages/about.vue则被确认不会生成 story。这与 Nuxt 的页面是路由单元、组件才是可复用 UI 单元的理念一致。props 自动提取从defineProps到 Storybook args生成 stories 时生成器会解析组件源码中的defineProps类型或props选项对象把每个 prop 提取出来并生成对应的默认值见 packages/vue/src/generators/stories/lib/utils.tsstring类型默认值取prop名boolean取falsenumber取0。随后这些 props 会被写入 Story 的args让你在 Storybook 面板中直接调节属性。组件名中的连字符也会被转换为驼峰命名camelCase作为 Story 名使用。这解释了为什么测试用例中的组件defineProps{ name: string; displayAge: boolean; age: number }()会对应生成三个带默认值的 args。生成器行为验证测试与快照该生成器由 configuration.spec.ts 覆盖核心测试断言Vue 3 框架与样式导入运行生成器后main.ts使用storybook/vue3-vite框架、preview.ts包含import ../src/assets/css/styles.css;与tsconfig.storybook.jsoncomposite: true均与快照一致configuration.spec.ts只给组件生成 storiessrc/components下的组件生成.stories.tssrc/pages下的页面不生成configuration.spec.ts。测试通过createTreeWithEmptyWorkspace构建空工作区依次运行applicationGenerator与componentGenerator准备测试项目再执行storybookConfigurationGenerator断言产物整个流程可作为你排查生成器行为异常的参考。小结与推荐用法nx/nuxt:storybook-configuration把 Nuxt、Vue、Storybook 三者无缝衔接它继承了 Vue 生成器的全部能力Vue 3 Vite 框架、交互测试、Story 自动化生成、ignorePaths过滤、JS/TS 双格式并针对 Nuxt 增加了全局样式导入、app/与src/双目录适配以及tsconfig.storybook.json修正。推荐的日常用法组合# 基础为 ui 项目生成 TypeScript 配置 交互测试 自动生成 stories nx g nx/nuxt:storybook-configuration ui # 定制跳过不适合独立展示的组件目录同时改用 JavaScript 生成 stories nx g nx/nuxt:storybook-configuration ui --ignorePathslibs/ui/src/not-stories/** --jstrue # 运行生成的交互测试 nx test-storybook ui如果你需要更细粒度的控制——例如只给组件生成 stories 而不想改动 Storybook 主配置也可以直接调用底层生成器nx g nx/vue:storybook-configuration project不含 Nuxt 特有定制或nx g nx/vue:stories project仅生成 stories。结合本文的参数表与源码链路你可以按项目实际情况灵活组合快速搭建出一套可维护、可测试的 Nuxt 组件文档环境。【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考