Nx Storybook 开发服务器 Executor 实战指南从基础配置到 Angular 进阶选项【免费下载链接】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本指南围绕 Nx 官方插件nx/storybook中的storybook开发服务器 executor对应project.json中的storybooktarget展开讲解在 Nx Monorepo 工作区中如何通过project.json声明开发服务器、如何在 CI 下静默运行以及面向非 Angular 与 Angular 项目的多种配置形态docsMode、browserTarget、compodoc、styles、stylePreprocessorOptions。阅读完本文你将掌握该 executor 的全部核心选项、底层调用链与废弃迁移路径能够直接在自己的 Nx 工作区中复制、运行并调优 Storybook 开发环境。概述nx/storybook:storybookexecutor 是什么nx/storybook:storybook是 Nx 官方 Storybook 插件提供的 executor作用是以开发模式启动 Storybook 服务器并持续运行。它在 executors.json 中注册对应的执行入口是 storybook.impl.ts参数校验则定义在 schema.json 中。与它配对的是nx/storybook:build生产模式构建实现在 build-storybook.impl.ts两者共享同一套基于 Storybook core-server 的启动逻辑区别仅在于运行模式devvsstatic。值得注意的事实在仓库当前版本中该 executor 已被标记为废弃详见本文最后一节但文档与生成器仍完整保留其用法示例便于存量工作区查阅与迁移。基础用法在project.json中声明并启动关联文档给出的最小可用配置如下它位于project.json的targets中ui: { targets: { storybook: { executor: nx/storybook:storybook, options: { port: 4400, configDir: libs/ui/.storybook }, configurations: { ci: { quiet: true } } } } }启动命令nx run ui:storybook要点拆解configDir指向项目的.storybook目录如libs/ui/.storybook是唯一必填项。执行器启动前会调用storybookConfigExistsCheck见 utilities.ts检查该目录是否存在若不存在会直接抛错并提示先运行nx g nx/storybook:configuration --nameui生成配置。configurations.ci是 Nx 的命名配置named configuration机制运行nx run ui:storybook --configurationci时quiet: true会覆盖基础 options用于压缩 CI 日志输出。schema 中标注了continuous: true表示该 executor 是长驻进程启动成功后不会退出而是持续提供服务直到进程被外部终止。完整参数速查表以下参数均来自 schema.json参数类型默认值说明portnumber9009监听端口configDirstring—必填Storybook 配置目录.storybookpreviewUrlstring—预览 URL用于 Storybook 8 的 preview 地址hoststring—监听的主机地址httpsbooleanfalse以 HTTPS 提供服务需自行提供证书sslCert/sslKey/sslCastring—HTTPS 证书、私钥与 CA启用https时的配套项openboolean—自动打开浏览器窗口noOpenboolean—不自动打开浏览器cibooleanfalseCI 模式跳过交互式提示、不打开浏览器quietboolean—抑制冗长的构建输出loglevelstringinfo日志级别silly、verbose、info、warn、silentdocsboolean—以文档模式启动 StorybookdocsModebooleanfalse以文档模式启动 Storybook等价于docs的显式开关smokeTestboolean—成功启动后立即退出用于冒烟测试webpackStatsJsonboolean/stringfalse将 Webpack Stats JSON 写入磁盘debugWebpackboolean—打印最终 Webpack 配置用于调试disableTelemetryboolean—关闭 Storybook 遥测uiFrameworkstring—Storybook 框架包名已废弃提示升级到 Storybook 7其中 HTTPS 相关参数与 Angular 场景下的browserTarget、compodoc、styles等并不冲突可按需组合configDir在 schema 中带有x-priority: important标记Nx Console 等工具会优先提示填写。底层原理executor 如何启动 Storybook从 storybook.impl.ts 可以看到完整调用链它有助于理解上面参数的真实作用废弃警告执行器首先调用warnStorybookExecutorDeprecation()见 deprecation.ts在控制台输出迁移提示。配置存在性校验storybookConfigExistsCheck(options.configDir, context.projectName)校验configDir。按 Storybook 版本选择 core-server 入口getInstalledStorybookVersion()读取已安装的 Storybook 版本若 8.2.0则动态导入storybook/internal/core-server否则回退到storybook/core-server从而兼容旧版本见 versions.ts 中的版本映射。以dev模式构建最终调用storybookCore.build({ ...options, mode: dev })——也就是说Nx 只是把你在project.json里配置的 options 原样透传给 Storybook 的 core-server 构建函数真正负责启动 dev server 的是 Storybook 自身。产出运行信息executor 通过yield返回{ success: true, info: { port, baseUrl } }其中baseUrl按options.https与options.host动态拼装默认http://localhost:port供下游任务或工具消费。保持进程存活执行器最后挂起在await new Promise(() {})上确保 dev server 持续运行直到被终止。这套实现也解释了为什么storybookexecutor 的 schema 中额外支持host、https、sslCert/sslKey/sslCa、smokeTest等选项——它们与 build-storybookbuild-storybook.impl.tsmode: static共享同一份透传通道只是 dev 模式更多用于本地开发与 CI 冒烟验证。非 Angular 项目示例以docsMode搭建纯文档站点对于非 Angular 项目关联文档提供了在文档模式下工作的示例设置docsMode: true并搭配storybook/addon-docs可以把 Storybook 变成纯文档站点只渲染 MDX/文档页不运行组件画布适合作为组件库的 API 文档门户。storybook: { executor: nx/storybook:storybook, options: { port: 4400, configDir: libs/ui/.storybook, docsMode: true }, configurations: { ci: { quiet: true } } }docsMode的默认值是false显式置为true后dev server 会按纯文档模式渲染schema 中另有docs布尔项语义相同二者均可用于此场景。若使用框架无关的生成器nx g nx/storybook:configuration ui --uiFrameworkstorybook/web-components-vite参见 configuration-generator-examples.md生成的.storybook/main.ts中addons数组可加入storybook/addon-docs该 addon 的详细能力可参考 Storybook 官方 addon-docs 文档页。需要构建而非仅开发预览时可参考 build-storybook 的 schemanx/storybook:build同样支持docsModebuild-storybook/schema.json用于产出文档站静态文件。Angular 项目示例Angular 项目的 Storybook 配置与泛化流程略有不同Nx 为 Angular 项目生成的目标直接使用 Storybook 原生的storybook/angular:start-storybookexecutor而不是nx/storybook:storybook。关联文档给出了三种典型形态下面逐一展开。默认配置使用storybook/angular:start-storybook这是 Angular 项目使用 Storybook 时的默认配置Nx 的nx/angular:storybook-configuration生成器会自动写入project.jsonstorybook: { executor: storybook/angular:start-storybook, options: { port: 4400, configDir: libs/ui/.storybook, browserTarget: ui:build, compodoc: false }, configurations: { ci: { quiet: true } } }关键选项说明browserTargetAngular 的 Storybook 需要知道使用哪套构建配置来编译应用。按照 overview-angular.mdoc 的说明如果项目可构建即存在buildtarget 且使用官方 Angular builder如angular/build:application、angular-devkit/build-angular:browser、angular-devkit/build-angular:application、angular-devkit/build-angular:browser-esbuild则browserTarget指向ui:build若项目不可构建则会改用ui:build-storybook。此配置由生成器自动完成即使从旧版 Nx 迁移Nx 也会把package.json中的旧脚本改写为新 schema。compodoc是否启用 Compodoc 来推断argTypes并生成组件文档。默认关闭false开启后需要额外配置 Compodoc详见 angular-storybook-compodoc.mdoc。上述 Angular 选项的详细配置参考可继续查阅仓库中的 overview-angular.mdoc。修改browserTarget指向build-storybook当你的项目没有独立的buildtarget例如不可直接构建的库可以把browserTarget改为build-storybook让 dev server 复用 Storybook 自身的构建产物storybook: { executor: storybook/angular:start-storybook, options: { port: 4400, configDir: libs/ui/.storybook, browserTarget: ui:build-storybook, compodoc: false }, configurations: { ci: { quiet: true } } }从实现角度看这一选择的依据与 utilities.ts 中findStorybookAndBuildTargetsAndCompiler的逻辑一致只有官方 Angular application/browser builder 才支持styles等额外选项因此基于这些 builder 的项目优先走build而基于nx/angular:*如ng-packagr-lite、package等不支持额外样式的 executor 时build-storybook是更合适的承载目标因为它可以携带样式类选项。添加样式与预处理器选项Angular 的 Storybook 目标支持通过styles数组引入全局样式文件并通过stylePreprocessorOptions.includePaths配置 SCSS/Sass 的 include 路径用法与 Angular builder 保持一致storybook: { executor: storybook/angular:start-storybook, options: { port: 4400, configDir: libs/ui/.storybook, browserTarget: ui:build, compodoc: false, styles: [some-styles.css], stylePreprocessorOptions: { includePaths: [some-style-paths] } }, configurations: { ci: { quiet: true } } }补充说明与替代方案同样形态的styles与stylePreprocessorOptions也出现在nx/storybook:build的 schema 中build-storybook/schema.json其中styles的每一项支持两种写法纯字符串路径或{ input, bundleName, inject }对象inject默认true决定是否注入到 HTMLincludePaths中的路径会解析到工作区根目录。若希望走更原生的 Storybook 路线也可以在.storybook/preview.ts中直接import全局样式如import ../src/styles.scss并在.storybook/main.ts中通过webpackFinal调整 sass-loader 的includePaths这些做法详见 angular-configuring-styles.mdoc。通过命名配置适配 CI关联文档中的所有示例都包含configurations.ci片段这是 Nx 的标准做法。在 CI 中运行nx run ui:storybook --configurationci即可自动应用quiet: true配合 executor 自身的ci选项schema 中描述为CI 模式跳过交互式提示、不打开浏览器可以避免 CI 管道因交互提示或浏览器弹窗而挂起。若需要在 CI 中验证 dev server 能正常启动后立即退出可另加--smokeTestschema 中smokeTest描述为成功启动后退出。迁移路径executor 已废弃推荐迁移到推断插件仓库源码明确标注nx/storybook:storybook以及nx/storybook:buildexecutor 已废弃将在 Nx v24 中移除废弃信息定义在 deprecation.ts并在 schema.json 的x-deprecated字段与运行时日志中双重提示。因此存量工作区应规划迁移nx g nx/storybook:convert-to-inferred迁移后的工作区不再在project.json中声明 executor target而是由nx/storybook/plugin推断插件自动识别项目中的.storybook/main.{js,ts,cjs,cts,mjs,mts}文件并生成storybook、build-storybook、test-storybook、static-storybook等目标推断逻辑位于 plugins/plugin.ts插件入口见 plugin.ts。目标名称可通过nx.json中plugins数组的插件选项调整如serveStorybookTargetName默认storybook、buildStorybookTargetName默认build-storybook相关内容可查阅 introduction.mdoc 与 convert-to-inferred.mdoc。迁移后运行的命令保持不变nx run ui:storybook但配置从project.json下沉到 Storybook 自身的配置文件与nx.json的targetDefaults可读性与缓存设置都会更好。对于本文讨论的 Angular 场景迁移时browserTarget、styles等选项会相应写入.storybook/main.ts等工具配置文件项目专属的偏离配置仍保留在project.json中。【免费下载链接】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），仅供参考