ngx-bootstrap v7 发布工程清单解读：从巨型 Bundle 拆分到 Nx 驱动的 CI/CD 与文档发布流水线

UI组件前端【免费下载链接】ngx-bootstrapFast and reliable Bootstrap widgets in Angular (supports Ivy engine)项目地址https://gitcode.com/gh_mirrors/ng/ngx-bootstrap点击查看免费下载导读本文围绕仓库根目录下的 breakin-7.md 展开——这是一份 ngx-bootstrap 团队为v7 大版本发布准备的工程改造任务清单release planning checklist记录了从「拆分巨型 bundle」到「GitHub Actions 自动化发布」的完整落地路径。我们将以这份清单为骨架结合当前仓库版本 21.2.1Angular 21 Nx 22 时代中真实存在的源码、配置与工作流文件逐条还原每一项工程决策的最终形态帮助你理解一个大型 Angular 组件库是如何组织包结构、测试体系、文档站点与发布流水线的并为自己的组件库或 Monorepo 项目提供可直接借鉴的工程模板。一、文档定位一份「可执行」的大版本发布清单breakin-7.md不是一篇用户手册而是一份面向维护者的工程任务清单。它按优先级分为四块Done已完成7 项落地改造包括拆包、版本管理、gh-pages 部署、Scully、Nx 配置、测试覆盖率与 Jest 迁移v7 release blockers发布阻塞项8 项必须在正式发版前解决的任务从 schematics 修复到 GitHub Actions 自动化To be discussed待讨论3 个 API 层面的取舍问题v8 与 Nice to have远期规划Bootstrap 5、SSR、搜索等方向性内容。这份清单的价值在于它把「发布一个 Angular 组件库」拆成了一个个可验收的工程动作。下文按此骨架逐条展开并用仓库证据说明每一项最终变成了什么。二、Done已完成的基础工程改造1. 拆分巨型 bundle按需导入组件清单第 1 条是本次改造的核心Dropped huge mega bundlengx-bootstrap, please import only components you are actually using在 v7 之前ngx-bootstrap 作为一个整体包发布用户即使只用 Accordion 也要下载全部组件代码。拆包后每个组件子库都是独立的 npm 包入口。从当前仓库结构看这一目标已完全落地每个组件拥有独立的 ng-package.json例如 accordion 的输出目录为../../dist/ngx-bootstrap/accordion每个子库拥有自己的 package.jsonname字段为ngx-bootstrap/accordion即发布为scoped 子路径包每个子库通过 public_api.ts 导出自己的组件、指令、Module 与 Config。用户在应用中的导入方式也随之变化。以 accordion 为例libs/doc-pages/accordion/src/lib/docs/usage.md 展示了两种用法// Standalone component usage import { BrowserAnimationsModule } from angular/platform-browser/animations; import { AccordionComponent, AccordionPanelComponent } from ngx-bootstrap/accordion; Component({ standalone: true, imports: [ BrowserAnimationsModule, AccordionComponent, AccordionPanelComponent ] }) export class AppComponent() {}// Module usage import { BrowserAnimationsModule } from angular/platform-browser/animations; import { AccordionModule } from ngx-bootstrap/accordion; NgModule({ imports: [BrowserAnimationsModule, AccordionModule] }) export class AppModule {}从源码结构看AccordionModule如今只是一个薄封装src/accordion/accordion.module.tsNgModule({ imports: [AccordionComponent, AccordionPanelComponent], exports: [AccordionComponent, AccordionPanelComponent] }) export class AccordionModule {}即组件本体是standalone的accordion-group.component.ts 中standalone: trueModule 仅为兼容旧写法而存在。这正是「只导入你实际使用的组件」的架构基础。2. 版本号统一管理一个脚本同步全部包清单第 2 条要求「Update package json and current version in assets」。仓库中的 scripts/set-version.ts 实现了这一点它以根package.json的version为唯一事实来源通过 glob 扫描./src/**/package.json把版本号同步写入所有组件子库的package.json文档站的 current-version.json当前为21.2.1schematics 的依赖版本表 current_dependency_versions.json若存在NGX_BOOTSTRAP_VERSION字段也会一并更新。对应地根 package.json 的version脚本被设计为npx tsx ./scripts/set-version.ts——这正是清单第 5 条阻塞项「Check that it works on npm version script (generate api-docs)」要求的机制打版时由 npm 触发脚本让版本号在发布前自动贯穿所有子包与文档资源。3. gh-pages 部署baseHref 与 404.html清单第 3 条要求改造 gh-pages 部署使其「include base and disable hash page 404.html」。仓库中的落地证据有两处构建侧——文档应用 project.json 中build目标设置baseHref: /ngx-bootstrap/保证静态资源在/ngx-bootstrap/前缀下可访问assets中包含了apps/ngx-bootstrap-docs/src/404.html用于 SPA 路由在静态托管下的回退。部署侧——scripts/gh-pages-predeploy.ts 实现了完整的发布编排读取根package.json的version与 gh-pages 中current-version.json记录的上一次版本比对若版本变化将旧站点文件整体移入gh-pages/old/prevVersion/归档将dist/apps/ngx-bootstrap的构建产物拷贝到 gh-pages 根目录生成versions.json含Current与全部历史版本条目并写入current-version.json。这套逻辑对应了清单第 3 条「change gh-pages deployment to include base and disable hash page」以及第 4 条阻塞项「Drop old versions from gh-pages, keep only latest major versions」——旧版本不是被删除而是归档到old/目录保证文档站始终以最新版本为主入口。4. Scully 静态站点生成清单第 4 条「deploy scully」要求文档站支持预渲染。当前仓库保留了 scully.ngx-bootstrap-docs.config.tsexport const config: ScullyConfig { projectRoot: ./apps/ngx-bootstrap-docs/src, projectName: ngx-bootstrap-docs, outDir: ./dist/static/ngx-bootstrap, extraRoutes: [/documentation, /discover, /accordion, /alerts, /buttons, /carousel, /collapse, /datepicker, /dropdowns, /modals, /pagination, /popover, /progressbar, /rating, /sortable, /tabs, /timepicker, /tooltip, /typeahead], routes: {}, guessParserOptions: { excludedFiles: [src/app/app.routing.ts], }, };可见文档站的全部组件页面都被列为extraRoutes进行预渲染配合 gh-pages 的baseHref与404.html构成一个可被搜索引擎索引、无 hash 路由依赖的静态文档站点。根 package.json 中scully与scully:serve脚本保持可用。5. Nx本地默认 runnerCI 启用 nx-cloud清单第 5 条「nx: use local runner by default and nx-cloud in ci」是工程化的关键一环。当前仓库的落地情况decorate-angular-cli.js 在postinstall阶段执行把ng命令符号链接到nx让所有命令默认走 Nx 的计算缓存与任务编排nx.json 中设置了nxCloudAccessTokennx-cloud 云端缓存凭证并定义了namedInputsdefault/sharedGlobals/production与targetDefaults在 CI 侧.github/workflows/on-push-or-pull.yml 与 .github/workflows/on-release.yml 均设置了NX_CLOUD_AUTH_TOKEN环境变量使云端任务缓存仅在 CI 中生效——这正是「本地默认、CI 上云」的配置策略。从targetDefaults还可以看到 Nx 20 时代的默认输入规则production输入显式排除了*.spec.ts、tsconfig.spec.json、jest.config.ts等测试相关文件确保「构建产物缓存」与「测试任务缓存」相互独立。6. 测试修复覆盖率与相对导入清单第 6 条「test: fix coverage and use relative imports of ngx-bootstrap modules」要求修复覆盖率统计并在测试中改用相对导入而不是引用 npm 上已发布的ngx-bootstrap包避免测试的是旧版本代码。仓库证据nx.json 中nx/jest:jest的ci配置显式开启ci: true, codeCoverage: true每个子库的 jest.config.ts 声明独立的coverageDirectory如../../coverage/src/accordion配合 jest.preset.js 统一切片组件库源码内的交叉导入使用相对路径与别名例如 accordion-group.component.ts 中import { CollapseModule } from ngx-bootstrap/collapse——在 Nx 工作区中该路径经由 tsconfig.base.json 的路径映射解析到本地src/collapse源码从而保证测试永远针对当前工作区代码而非已发布包。7. 测试运行器迁移到 Jest清单第 7 条「test: update tests for jest runner」。当前仓库已全面 Jest 化每个子库的 jest.config.ts 使用jest-preset-angular并通过transform配置处理.ts/.mjs/.js/.html支持模板字符串化快照snapshotSerializers使用no-ng-attributes、ng-snapshot、html-comment三件套根 package.json 的test脚本为nx run-many --all --targettest即通过 Nx 批量跑全部子库的单测。对比_root目录中遗留的 scripts/test-demo.ts 与 scripts/test-source.ts基于 Karma zone.js 的旧测试入口可以推断 Jest 迁移正是 v7 周期内完成的新旧测试体系切换旧 Karma 入口仅作为历史痕迹保留在_root归档目录中。三、v7 Release Blockers发布前必须解决的工程问题1. schematics 适配 Angular 11Nx 11清单要求修复 schematics 在 Angular 11 / Nx 11 下的构建与测试。当前仓库的 collection.json 保留了完整的ng-addschematic{ $schema: ../../../node_modules/angular-devkit/schematics/collection-schema.json, schematics: { ng-add: { description: Adds ngx-bootstrap to the application without affecting any templates, factory: ./ng-add/index, schema: ./ng-add/schema.json } } }根 package.json 中schematics: ./schematics/src/collection.json把该集合注册为包的 schematics 入口用户执行ng add ngx-bootstrap --component accordion即可按需安装该命令在 accordion-section.list.ts 的importInfo中也有体现。schematic 需要跟随 Angular/Nx 主版本演进反复验证这正是它被列为「blocker」的原因——它直接关系到用户的首次安装体验。2. root lib 三件套README、Sass 资源、Sauce 跨浏览器测试清单第 2 条要求补齐 root 库的三件事均已标记 donewith .md根库 src/root/README.md 提供包级说明build sass assets组件样式通过 ng-packagr 的assets配置随包发布。例如 datepicker 的 bs-datepicker.scss 被文档应用直接引用为全局样式见 project.json 的stylePreprocessorOptions.includePaths: [src/datepicker]说明样式资源与组件源码同构发布test sauce_root目录遗留的 .travis.yml 与 scripts/sauce 系列脚本记录了基于 Sauce Labs 的跨浏览器矩阵测试方案testing-cross、sauce_connect 等这是 v7 时代主流的跨浏览器验证手段后续被 GitHub Actions 原生矩阵逐步取代。从根库的 ng-package.json 可见其特殊职责dest指向../../dist/ngx-bootstrap包根deleteDestPath: false避免清掉各子库产物并将 postinstall.js 作为 asset 打入包内用于在安装时向用户输出升级提示。root lib 本质上是「包的聚合外壳」负责装配、提示与文档。3. gh-pages 只保留最新大版本已划线完成清单第 3 条带删除线标记说明已在清单撰写时完成。对应实现即上文介绍的 scripts/gh-pages-predeploy.ts每次发布把当前版本整体归档进old/version/站点主目录始终是最新版本。文档站根目录的 versions.json 目前为空数组[]也印证了「当前只有最新版本、旧版本归档策略已生效」的状态。4. 文档站拆分 latest / next 版本清单第 4 条要求在文档中拆分 latest 与 next 版本线。_root下遗留的 .travis.yml 提供了历史实现通过NGVlatest|next环境变量分别构建并部署到ngx-bootstrap-latest.surge.sh/ngx-bootstrap-next.surge.sh。而清单第 5 条「remove links to surge」表明这套基于 surge.sh 的预览机制在 v7 周期内被移除取而代之的是 Firebase Preview Channel见 scripts/firebase/deploy-to-preview-channel.sh 与 firebase.json。从当前 .github/workflows/on-push-or-pull.yml 看PR 预览已完全迁移到 Firebase Hosting 的临时频道channelId按分支动态切换expires: 7d。5. npm version 脚本联动生成 API 文档清单第 5 条要求验证「发布 RC 后npm version能自动生成 api-docs」。仓库证据链完整根 package.json 的version脚本 npx tsx ./scripts/set-version.ts同步所有包版本号生成后的 API 文档静态资源为 apps/ngx-bootstrap-docs/src/ng-api-doc.ts由scripts/docs/api-doc.js从源码注释抽取组件/指令/Config 的输入输出属性生成例如其中记录了AccordionPanelComponent的heading、isOpenInput、isOpenChange、panelClass等完整 API文档页通过 accordion-section.list.ts 的NgApiDocComponent/NgApiDocConfigComponent把这份 JSON 渲染为 API Reference 页。这套「版本号变更 → 同步子包 → 生成 API 文档」的链路保证每次发版文档与代码严格同版本。6. 文档审查更新贡献指南、移除 surge 链接清单要求系统性 review 文档包括更新贡献文档与移除 surge 链接。当前仓库的 CONTRIBUTING.md 与 CODE_OF_CONDUCT.md 即为这一轮治理的产物而 surge 相关痕迹仅保留在_root归档的 .travis.yml 中历史快照活跃工作流已不再引用。7. GitHub Actionstag 触发全自动发布清单第 7 条要求建立「打 tag 即发布」的自动化。当前仓库的 .github/workflows/on-release.yml 完整实现了三件事阶段动作实现构建npx nx build ngx-bootstrap --configurationproductionnpx nx prerender产出dist并缓存dist供后续 job 复用gh-pages 更新检出 gh-pages 分支 → 执行scripts/gh-pages-predeploy.ts→ 提交并推送站点自动更新npm 发布JS-DevTools/npm-publish发布dist/ngx-bootstrap/package.json包自动上 npm同时on-release.yml 中预留了被注释的update_release_draft阶段对应清单的「create release notes」基于CONVENTIONAL_GITHUB_RELEASER_TOKEN可推断 Release Notes 生成能力在后续版本中被 release-it见根 package.json 的release脚本与release-it/conventional-changelog依赖取代。8. GitHub Actions 分两档 E2Esmoke 与 full清单第 8 条规划了两档 Cypress 任务PR 上跑 smokeintegrationFoldercypress/integration「ready for testing」时跑 fullintegrationFoldercypress/full。当前仓库把这一策略升级为Playwright Nx 目标分档playwright.config.tschromium-integrationtestDir: ./src/integration→ 对应 smokechromium-fulltestDir: ./src/full→ 对应 fullchromium-alltestDir: ./src→ 全量兜底。CI 工作流 on-push-or-pull.yml 中e2e_smoke与e2e_full两个 job 均按matrix.shard分片并行并优先在 Firebase 预览 URL 上执行、失败可回落到本地服务根 package.json 提供了对应的本地命令npm run pw:run:smoke # nx run ngx-bootstrap-docs-e2e:e2e --pwProjectchromium-integration --headed npm run pw:run:full # nx run ngx-bootstrap-docs-e2e:e2e --pwProjectchromium-full --headed npm run pw:show-report # npx playwright show-report apps/ngx-bootstrap-docs-e2e/playwright-report从_root遗留的 .travis.ymlcy:run:smoke/cy:run:full配APPLITOOLS_CONCURRENCY可以看出这套「smoke/full 分档」的设计理念从 Cypress 时代延续到了 Playwright 时代只是运行底座与并行分片方式完全重构。四、To be discussed发布前的 API 取舍清单列出三个待讨论事项结合当前仓库源码可以推断出这些讨论的最终走向DroppedforRoot()?—— 当前src/下所有组件均已 standalone 化accordion.module.ts 这类 Module 只是空壳聚合全仓库搜索不到任何forRoot()调用。可以推断团队选择了「弃用 forRoot、拥抱 standalone 可注入 Config」的路线组件配置通过AccordionConfig这类可注入对象按需提供见 src/accordion/accordion.config.ts。remove deprecated datepicker—— 当前 src/datepicker 依然完整存在说明 datepicker 并未被移除而是保留了新引擎engine/、reducer/、themes/等模块只在 API 层持续做清理。remove deprecated properties—— 从 ng-api-doc.ts 的 API 记录与组件声明看大量属性已迁移为 signal 风格input()/output()可以推断「移除 deprecated properties」是通过逐步迁移到新 API 的方式完成的而非一次性破坏。这一节在清单中是「待讨论」在仓库中是「已解决的历史决策」——这正是把清单与当前代码对照阅读的价值所在。五、v8 方向清单前瞻的落地情况清单对 v8 的规划同样可以在当前仓库中找到对应物bs5 support当前依赖 package.json 已不含 Bootstrap 3 时代的样式依赖组件样式如 accordion.scss、tabs.scss均已适配 Bootstrap 5 的 CSS 变量与类名体系animation文档用法明确要求BrowserAnimationsModulecollapse-animations.ts、datepicker-animations.ts、dropdown-animations.ts、typeahead-animations.ts 等动画模块构成了组件级动画的基础设施test: usecollectCoverageFromnx.json 中 jest 的ci配置已用codeCoverage配合各子库coverageDirectory实现按模块收集覆盖率nx: split docs into libs文档站已拆为 libs/doc-pages 下 18 个独立文档库accordion、alerts、buttons、carousel、collapse、datepicker、dropdown、modal、pagination、popover、progressbar、rating、sortable、tabs、timepicker、tooltip、typeahead每个库通过 project.json 独立构建与测试配合 libs/common-docs 提供ExamplesComponent、ApiSectionsComponent、NgApiDocComponent等通用渲染组件split generated api docs into json per componentng-api-doc.ts 按组件类名AccordionPanelComponent、AccordionComponent、AccordionConfig…组织 API 数据即「每组件一份 JSON 记录」的结构。六、Nice to haveSSR 与长期演进清单最后的远期规划中SSR 是权重最高的一项。当前仓库已经把它从「nice to have」做成了一等公民apps/ngx-bootstrap-docs/server.ts 提供 Express 服务端入口scripts/universal 目录保留了服务端渲染的辅助脚本server.ts、prerender.ts、static.paths.ts、webpack.server.config.js、configure-heroku.js根 package.json 提供完整命令链npm run dev:ssr # ng run ngx-bootstrap-docs:serve-ssr npm run build:ssr # ng build ng run ngx-bootstrap-docs:server npm run serve:ssr # node dist/ngx-bootstrap-docs/server/main.js npm run prerender # ng run ngx-bootstrap-docs:prerender清单中提到的 Heroku Preview 实例、Algolia 搜索、恢复 n-1 版本 Angular 的回归测试历史实现见 scripts/ci/npm-ng-min.sh其中固定 Angular 6.0.1 用于验证最小支持版本以及图片级视觉测试均属于清单撰写时的规划项其中「恢复 n-1 版本测试」的思路在 scripts/ci/npm-ng-latest.sh 与 scripts/ci/npm-ng-next.sh 中保留为 CI 脚本即通过 CI 矩阵同时验证 current/latest/next 三条 Angular 版本线的构建与测试。七、结语从清单到流水线回看breakin-7.md它表面上是一份待办列表实质上是一张组件库工程化路线图。清单中的每一条最终都在当前仓库留下了可验证的产物巨型 bundle 拆分 → 18 个独立子库 standalone 组件版本管理 →set-version.ts单一事实来源同步机制gh-pages Scully →baseHref404.html 旧版本归档的静态文档站点Nx 本地/云端双轨 →decorate-angular-cli.js nx-cloud token 的 CI 注入Jest 覆盖率 → 每子库独立 jest 配置与ci覆盖模式schematics、root lib、Sauce → 安装体验、包聚合外壳与跨浏览器验证GitHub Actions → tag 触发「构建 → gh-pages → npm」全自动发布链加上 smoke/full 两档 E2E。对于正在维护 Angular 组件库或 Nx Monorepo 的你这份清单的「拆包 → 单测 → E2E → 文档 → 发布」五步模型以及「本地默认缓存、CI 上云」的 Nx 实践都是可以直接迁移到你自己仓库的工程范式。深入阅读 breakin-7.md 本身、对照 scripts/gh-pages-predeploy.ts 与 .github/workflows/on-release.yml即可完整还原这套发布流水线的全貌。赞分享UI组件前端【免费下载链接】ngx-bootstrapFast and reliable Bootstrap widgets in Angular (supports Ivy engine)项目地址https://gitcode.com/gh_mirrors/ng/ngx-bootstrap点击查看免费下载相关推荐FastGPT 企业微信机器人接入指南不写代码半小时让知识库住进企微聊天框FastGPT 企业微信机器人接入指南不写代码半小时让知识库住进企微聊天框 跟着本文操作你会得到一个挂在企业微信里的智能问答机器人员工在企微中提问答案人工智能AI AgentRAG大模型工作流自动化后端前端3分钟彻底告别激活烦恼KMS智能激活脚本完全指南3分钟彻底告别激活烦恼KMS智能激活脚本完全指南 你是否曾经遇到过这样的尴尬时刻在准备重要演示的前一刻Office突然弹出产品未激活的警告或者每次开运维Python通达信数据读取实战指南从零开始构建你的金融分析系统Python通达信数据读取实战指南从零开始构建你的金融分析系统 你是否曾经为了获取A股市场数据而烦恼是否厌倦了昂贵的API费用和复杂的接入流程今天我将带金融科技数据分析上一篇usearch的缓存策略减少重复计算提升检索速度下一篇CKAN坎巴拉太空计划模组管理的终极解决方案与完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考