使用 nx/rollup 在 Nx 中构建与发布 JavaScript 库执行器、推断插件与迁移实战【免费下载链接】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/rollup插件包展开介绍如何在 Nx 工作区中借助 Rollup 将库构建为 ESM / CommonJS 产物从readme-template.md所定义的包定位出发覆盖快速开始、nx/rollup:rollup执行器的全部配置项、自定义rollup.config与withNx编程式 API、样式与依赖处理原理以及从执行器迁移到nx/rollup/plugin推断插件的完整路径。读完本文你将掌握在 Nx 中为库项目配置 Rollup 构建、按需定制产物格式与外置依赖、并平滑迁移到新式推断目标的全套方案。一、包定位nx/rollup是什么在 packages/rollup/readme-template.md 中这个包被一句话定义清楚This package is a Rollup plugin for Nx.即nx/rollup是 Nx 的 Rollup 插件包使命是在 Nx 工作区中Packages a library for different web usages (ESM, CommonJS)——把一个库项目打包成面向不同 Web 使用场景的 ESM 与 CommonJS 产物。包内同时提供执行器executor与生成器generator以及新式的推断插件inferred plugin具体能力可以从包的清单文件确认packages/rollup/package.json 中描述为 The Nx Plugin for Rollup contains executors and generators that support building applications using Rollup.其peerDependencies声明支持rollup: ^3.0.0 || ^4.0.0且为 optionalrollup 由工作区自行安装packages/rollup/executors.json 注册了唯一执行器nx/rollup:rollupBundle a package using Rolluppackages/rollup/generators.json 注册了init、configuration别名rollup-project与convert-to-inferred三个生成器包还通过 packages/rollup/plugin.ts 暴露createNodes/createNodesV2/RollupPluginOptions通过 packages/rollup/with-nx.ts 暴露withNx编程式配置函数。值得注意的是readme-template.md本身是一个发布模板其中{{links}}与{{content}}是占位符。scripts/copy-readme.js 会在打包发布时用 scripts/readme-fragments/links.md 与 scripts/readme-fragments/content.md 替换它们最终生成dist/packages/rollup/README.md。这意味着模板中的Getting Started章节是所有 Nx 包通用的入门指引而本文下面将结合仓库源码把模板中一句话带过的Rollup plugin展开成可落地的完整方案。二、快速开始在 Nx 中启用 Rollup 构建模板的 Getting Started 部分即 scripts/readme-fragments/content.md给出了两种进入路径它们是使用nx/rollup的前提1. 创建全新 Nx 工作区# 方式一npx npx create-nx-workspace # 方式二npm init npm init nx-workspace # 方式三yarn create yarn create nx-workspace2. 为已有仓库接入 Nxnpx nxlatest init进入工作区后先安装插件包与 rollupnpm install -D nx/rollup rollup随后通过init生成器完成插件初始化该生成器在 packages/rollup/src/generators/init/init.ts 中实现支持skipFormat、skipPackageJson、keepExistingVersions、updatePackageScripts等选项再为具体库项目生成构建配置nx g nx/rollup:configuration my-libconfiguration生成器别名rollup-project的参数定义见 packages/rollup/src/generators/configuration/schema.json常用参数包括参数说明默认值project要配置的库项目名必填compiler编译源码使用的编译器babel可选swc、tscmain入口文件相对工作区根projectRoot/src/index.tstsConfig构建用的 tsconfig相对工作区根projectRoot/tsconfig.lib.jsonformat输出模块格式[esm]可选cjsexternal不打进产物、保持外置的模块列表[]rollupConfig自定义 rollup 配置文件路径相对工作区根无buildTarget生成的构建目标名buildimportPath库的导入名如myorg/my-lib无生成后project.json中会得到一个使用nx/rollup:rollup执行器的build目标随后即可运行nx build my-lib三、nx/rollup:rollup执行器全参数详解执行器的完整 schema 定义在 packages/rollup/src/executors/rollup/schema.json实现位于 packages/rollup/src/executors/rollup/rollup.impl.ts。核心参数整理如下带默认值参数类型默认值说明mainstring必填入口文件路径相对项目别名entryFileoutputPathstring必填产物输出目录outputFileNamestring与main同名主输出文件名tsConfigstring必填tsconfig 路径deleteOutputPathbooleantrue构建前清空输出目录format(esm\|cjs)[]与 tsconfig 匹配输出模块格式列表别名fexternalstring[]|all|none[]外置模块列表all表示全部外置、none表示全部打进产物watchbooleanfalse文件变更时增量重建rollupConfigstring | string[]无一个或多个接收 rollup config 并返回新 config 的模块路径extractCssboolean | stringtrue提取 CSS 到输出目录也可传自定义文件名如styles.cssassetsobject[] | string[][]静态资源列表globinputoutputcompilerbabel \| swc \| tscbabel使用的编译器babelUpwardRootModebooleanfalseBabelrootMode: upward用于 monorepo 中逐包应用.babelrcjavascriptEnabledbooleanfalse为 less loader 开启javascriptEnabledgenerateExportsFieldbooleanfalse在输出package.json中生成exports字段别名exportsadditionalEntryPointsstring[][]追加到exports字段的额外入口buildLibsFromSourcebooleantrue直接以源码方式读取可构建库而非预先单独构建它们skipTypeCheckbooleanfalse跳过 TypeScript 类型检查skipTypeFieldbooleanfalse不在输出package.json写入type字段sourceMapboolean无输出 sourcemapprojectstring无package.json文件路径已废弃自动探测项目根package.json一个典型的project.json配置示例{ my-lib: { targets: { build: { executor: nx/rollup:rollup, outputs: [{workspaceRoot}/dist/my-lib], options: { main: packages/my-lib/src/index.ts, outputPath: dist/my-lib, tsConfig: packages/my-lib/tsconfig.lib.json, compiler: swc, format: [esm, cjs], external: [react, react-dom], assets: [{ glob: *.md, input: ., output: . }], generateExportsField: true } } } } }3.1 底层执行流程从 rollup.impl.ts 可以看清执行器的工作方式先执行warnRollupExecutorDeprecation()见 packages/rollup/src/utils/deprecation.ts提示该执行器已废弃、将在 Nx v24 移除通过require(rollup)懒加载 rollup因为 rollup 是 optional peer dependency图构建阶段可能尚未安装默认把NODE_ENV置为production非watch模式下rollup.rollup(opts)创建 bundle再对每个 output 执行bundle.write(o)计时并输出⚡ Done in ${duration}watch模式下则切换到rollup.watch监听START/END/ERROR事件并在SIGTERM/SIGINT/SIGQUIT时关闭 watcher支持同时产出 ESM 与 CJS当format包含cjs时resolveOutfile会把 CJS 主文件解析为outputPath/name.cjs.js。3.2 用户自定义 rollupConfig 的合并规则createRollupOptionsrollup.impl.ts展示了自定义配置的两类合并语义导出为函数finalConfig config(finalConfig, options)把默认配置与标准化后的 options 交给你做任意改写导出为对象做浅合并且plugins采用默认插件 用户插件拼接的方式追加而不是覆盖。无论哪种方式generatePackageJson插件都会被确保保留在最终插件列表中以维持输出package.json的生成能力。四、用withNx编写自定义 rollup.config除了在project.json中声明式配置nx/rollup还提供了编程式配置入口withNx导出自 packages/rollup/with-nx.ts实现位于 packages/rollup/src/plugins/with-nx/with-nx.ts。它的调用形态为withNx(options, overrideConfig, dependencies)第一参传入与执行器一致的标准化选项第二参传入需要覆盖/追加的 rollup 配置第三参为可构建依赖节点列表执行器内部调用时即为withNx(options, {}, dependencies)。典型用法新建rollup.config.ts并把rollupConfig指向它import { withNx } from nx/rollup/with-nx; export default withNx( { main: ./src/index.ts, outputPath: ./dist, tsConfig: ./tsconfig.lib.json, compiler: swc, format: [esm, cjs], external: [react, react-dom], generateExportsField: true, }, { // 此处可叠加任意原生 rollup 配置或自定义插件 plugins: [myCustomPlugin()], } );可用的RollupWithNxPluginOptions完整字段定义见 packages/rollup/src/plugins/with-nx/with-nx-options.ts与执行器选项一一对应并额外支持generatePackageJson?: boolean是否在输出目录生成package.jsonTypeScript Project References 包管理器 Workspaces 场景下不支持其余场景默认true。选项在 packages/rollup/src/plugins/with-nx/normalize-options.ts 中被归一化字符串形式的assets必须位于项目 source root 内目录会展开为**/*的 glob对象形式的 asset 输出路径不允许以..开头不能写到输出目录之外format会去重并保持esm/cjs顺序。4.1 内置插件管线从with-nx.ts的导入packages/rollup/src/plugins/with-nx/with-nx.ts#L20-L42可以看到默认装配的完整工具链rollup/plugin-babel、rollup/plugin-commonjs、rollup/plugin-node-resolve、rollup/plugin-image、rollup/plugin-json、rollup/plugin-typescript内联的 postcss 插件不依赖外部rollup-plugin-postcss实现在 packages/rollup/src/plugins/postcss/postcss-plugin.ts并附带 sass/less/stylus 三套 loaderpackages/rollup/src/plugins/postcss/loaders配合autoprefixer处理前缀nxCopyAssetsPluginpackages/rollup/src/plugins/nx-copy-assets.plugin.ts负责把assets拷贝到输出目录generatePackageJsonpackages/rollup/src/plugins/package-json/generate-package-json.ts负责生成输出package.jsonswcpackages/rollup/src/plugins/swc.ts在compiler: swc时替代 babel 编译。五、依赖包含与babelUpwardRootMode实战细节packages/rollup/docs/rollup-examples.md 是该执行器 schema 的examplesFile在 schema.json 中被引用包含两个高频实战要点5.1 把依赖写进输出 package.json要让某个依赖出现在输出产物的package.json的dependencies中它必须安装在仓库根package.json的dependencies区而不是devDependencies{ dependencies: { some-dependency: ^1.0.0 } }这是generatePackageJson插件生成输出package.json时的依据只有根dependencies中的包才会被视为运行时依赖写入产物清单。5.2babelUpwardRootMode的正确打开方式babelUpwardRootMode: true会把 Babel 的rootMode设为upward令 Babel 从工作目录向上查找babel.config.json并将其位置作为 root。这在 monorepo 中适用于每个项目必须应用各自.babelrc的场景。配置示例{ my-app: { targets: { build: { executor: nx/rollup:rollup, options: { babelUpwardRootMode: true } } } } }开启后工作区根需要一份包含所有包范围的babel.config.json{ babelrcRoots: [*] }每个包再提供自己的.babelrc例如{ presets: [babel/preset-env, babel/preset-typescript] }目录形态如下├── packages │ ├── a │ │ └── .babelrc │ └── b │ └── .babelrc └── babel.config.json注意其语义细节若a导入了b则b会应用packages/b/.babelrc而不会应用a自己的配置babel.config.json中的内容对所有包生效。由于各包需各自维护正确的 presets/plugins这种模式容易造成包间构建差异官方文档明确建议默认不要设置babelUpwardRootMode保持默认false仅在确实需要逐包.babelrc时才启用。六、迁移到推断插件nx/rollup/pluginnx/rollup:rollup执行器已在 schema 中标记废弃packages/rollup/src/utils/deprecation.ts 明确说明Thenx/rollup:rollupexecutor is deprecated and will be removed in Nx v24.Nx v24 中执行器将被移除而推断插件nx/rollup/plugin与convert-to-inferred生成器会继续得到支持。因此executor → plugin的迁移是当前仓库指向的标准演进路径。6.1 一条命令完成迁移# 迁移所有使用 nx/rollup:rollup 的项目 nx g nx/rollup:convert-to-inferred # 只迁移指定项目 nx g nx/rollup:convert-to-inferred --projectmy-lib生成器参数见 packages/rollup/src/generators/convert-to-inferred/schema.json实现见 packages/rollup/src/generators/convert-to-inferred/convert-to-inferred.ts。其工作步骤包括assertSupportedRollupVersion(tree)校验工作区的 rollup 版本forEachExecutorOptions遍历所有使用nx/rollup:rollup的目标--project指定时只处理该项目跳过命名 configuration把nx.json中targetDefaults里针对nx/rollup:rollup的默认选项拷贝到目标上弥补移除 executor 后 defaults 不再生效的问题通过 extract-rollup-config-from-executor-options.ts 把 executor 选项转写为rollup.config.ts内部走withNx形态并删除project.json中的旧 target通过 add-plugin-registrations.ts 在nx.json的plugins中注册nx/rollup/plugin。6.2 推断插件的工作机制推断插件的实现位于 packages/rollup/src/plugins/plugin.ts以 glob**/rollup.config.{js,cjs,mjs,ts,cts,mts}扫描工作区plugin.ts#L44只要项目根含package.json或project.json存在 rollup 配置文件就自动为其生成build目标无需在project.json手工声明通过calculateHashesForCreateNodes对项目根与选项做哈希并把生成结果缓存到 Nx 的workspace-data目录rollup-optionsHash.hash未变更时直接复用缓存中的目标配置加载配置时优先解析工作区自身安装的 rollup的loadConfigFile以保证与 rollup 大版本兼容例如 rollup2 允许 config 中使用requirerollup4 则不行TypeScript 写的 config 会附加--configPlugin typescript{tsconfig:tsconfig.lib.json}并以 watch 模式加载配置以规避缓存生成的build目标为command: rollup -c configcwd指向项目根cache: truedependsOn: [^build]先构建依赖库inputs使用production/default命名输入并声明对rollup的外部依赖outputs从 config 的output.dir/output.file推导缺失时默认dist插件选项通过nx.json中插件配置传入buildTargetName默认build、buildDepsTargetName、watchDepsTargetName。插件还通过addBuildAndWatchDepsTargets自动补充构建/监听依赖库的目标在 TypeScript Project References 场景isUsingTsSolutionSetup()下会额外挂上nx/js:typescript-sync同步生成器。6.3 迁移后的形态与配套迁移迁移完成后项目不再依赖 executorproject.json中的build目标消失构建行为完全由rollup.config.ts驱动nx build my-lib依然可用同时nx graph中会展示基于 Rollup 的目标关系。此外仓库还在 packages/rollup/src/migrations/update-23-0-0 提供了配套升级迁移createNodesV2迁移、移除已废弃的useLegacyTypescriptPlugin选项、内部子路径导入重写确保旧配置在升级后平滑衔接新式插件体系。七、总结nx/rollup是 Nx 生态中专用于 Rollup 构建的插件包其能力图谱如下声明式配置nx/rollup:rollup执行器schema.json覆盖入口、输出、格式、外置依赖、资源、样式提取、编译器选择等 20 余项参数编程式配置withNxpackages/rollup/with-nx.ts在原生rollup.config中复用 Nx 的库构建管线自包含工具链内联 postcsssass/less/stylus、assets 拷贝、输出package.json生成、exports字段与额外入口点支持面向未来执行器已废弃Nx v24 移除推荐通过nx g nx/rollup:convert-to-inferred迁移到nx/rollup/plugin推断目标实现配置即代码、缓存即收益的现代构建方式。无论你是要快速为现有库添加构建目标还是希望把 Rollup 构建完全收敛到配置文件、享受 Nx 的缓存与依赖图编排nx/rollup都提供了对应层级的接入方式。相关源码与示例可继续在仓库中查阅packages/rollup/docs/rollup-examples.md、packages/rollup/src/plugins/plugin.ts、packages/rollup/src/plugins/with-nx/with-nx.ts。【免费下载链接】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），仅供参考