Razzle 贡献指南：Monorepo 本地开发、示例工作流与 PR 提交全流程

前端构建工具前端构建后端【免费下载链接】razzle✨ Create server-rendered universal JavaScript applications with no configuration项目地址https://gitcode.com/gh_mirrors/ra/razzle点击查看免费下载本篇指南面向希望为 Razzle 项目贡献代码、修复 Bug、新增功能的开发者。你将掌握在 Razzle 的 Lerna Yarn Workspaces Monorepo 中搭建本地开发环境、在examples示例目录中直接验证核心包改动、通过yarn new-example与yarn bootstrap-examples管理示例、运行端到端与示例测试以及遵循项目规范提交示例与 PR 的完整工作流。Razzle 的 Monorepo 结构从哪里入手Razzle 是一个由多个 npm 包组成的 Monorepo由 Lerna 驱动仓库根目录的 lerna.json 声明了lerna: 3.20.2、useWorkspaces: true、npmClient: yarn。整个仓库分为四大部分examples所有示例项目都放在这里例如 examples/basic、examples/with-react-router、examples/with-tailwindcss 等。packages核心代码所在包含babel-preset-razzleRazzle 默认的 Babel 预设create-razzle-app初始化新项目的 CLI 工具razzle核心库razzle-dev-utils工具函数与辅助模块以及razzle-start-server-webpack-plugin与一系列razzle-plugin-*插件。scripts与仓库清理、引导bootstrap相关的工具脚本例如 scripts/bootstrap-examples.js、scripts/new-example.js。test端到端测试配置位于 test/jest.e2e.config.json 与 test/jest.examples.config.js。理解这一结构是后续一切开发工作的基础核心逻辑在packages验证与演示在examples两者通过 Yarn Workspaces 的符号链接symlink直接相连。搭建本地开发环境官方推荐的本地开发流程如下先 fork 仓库到自己的 GitHub 账号再克隆 fork 到本地并创建独立分支不建议直接在master上开发这样便于随时拉取上游更新。git clone https://github.com/YOUR_GITHUB_USERNAME/razzle.git cd razzle git checkout -B my-branch NODE_ENVdevelopment yarn install ---ignore-engines # 可选安装 add-dependencies 全局工具 sudo npm install add-dependencies -g安装完成后所有包与示例的node_modules都会被安装且包之间的相互依赖会被符号链接。这意味着你在任意一个packages/*下做的本地修改可以立即在所有examples/*示例中生效并验证无需重新发布。add-dependencies工具则用来快捷地把新依赖写入示例的package.json更多用法见下文「向示例添加依赖」小节。说明NODE_ENVdevelopment与---ignore-engines三个连字符为文档原样写法若你的环境报错可尝试--ignore-engines用于绕过 Node 引擎版本检查避免因本机 Node 版本与仓库声明不符导致安装失败。常用命令速查仓库根目录 package.json 中定义了全部脚本与贡献文档一一对应命令作用底层实现package.json scriptsyarn clean清理所有node_modules移除各包与示例之间的符号链接lerna clean --yesyarn test --runInBand运行全部测试yarn test:e2e即 jest e2e 配置yarn test:packages运行各包的单元测试lerna run test --stream --scope razzle-* --ignore razzle-examples-*yarn test:e2e运行端到端测试jest --config ./test/jest.e2e.config.jsonyarn build-docs构建文档并更新文档 TOCnode ./scripts/build-docs.jsyarn publish-all-canary发布razzlecanary预发布版本yarn publish-all -p canary -c -t --push release --preyarn publish-all-stable发布稳定版本使用已发布的 npm 包版本yarn publish-all -c -t --push release node ./scripts/release-notes.jsyarn new-example from to基于已有示例创建新示例如yarn new-example basic new-examplenode ./scripts/new-example.jsyarn bootstrap-examples example将指定示例作为 Workspace 运行yarn自动符号链接相互依赖的模块在示例内运行yarn restrap可重新安装node ./scripts/bootstrap-examples.jsyarn test:examples:simple运行所有 simple 类型示例测试使用 npm 已发布版本的包jest --config ./test/jest.examples.config.js -t simpleyarn test:examples:complex运行所有 complex 类型示例测试同样使用已发布版本COMPLEXtrue jest --config ./test/jest.examples.config.js -t complexyarn test:examples运行全部示例测试jest --config ./test/jest.examples.config.js从源码看示例测试的配置在 test/jest.examples.config.js 中roots指向examples目录通过testMatch匹配*.test.*/*.spec.*文件并由COMPLEX环境变量区分 simple 与 complex 两类测试产物含 HTML 报告输出到test-artifacts/。在 Examples 上开发 Razzle 核心的完整工作流这是贡献文档的核心章节描述了一套在本地同时修改核心包并即时在示例中验证的循环流程git clone https://github.com/YOUR_GITHUB_USERNAME/razzle.git cd razzle git checkout -b my-feature-branch canary # 或者基于其他分支 # git checkout -b my-feature-branch master # git checkout -b my-feature-branch three sudo npm install add-dependencies yalc -g pwd # 确认当前位于仓库根目录例如 /home/oyvind/Documents/GitHub/razzle/ NODE_ENVdevelopment yarn install ---ignore-engines # 先确保现有测试全部通过 yarn test --runInBand # 基于已有示例创建新示例 yarn new-example existingexample with-somefeature # 进入示例目录开始工作 cd examples/basic example$(basename $PWD) pushd ../.. # 若该示例基于 webpack5需要临时安装对应版本 yarn add -W webpack5.24.0 html-webpack-plugin5.2.0 # 之后切回 webpack4 时再还原 yarn add -W webpack4.46.0 html-webpack-plugin4.5.2 # 将示例引导为 Workspace符号链接本地包 yarn bootstrap-examples $example popd yarn build # 如需向示例添加依赖 add-dependencies somedependency yarn restrap # 若修改了 razzle-start-server-webpack-plugin需要单独重新构建 pushd ../.. cd packages/razzle-start-server-webpack-plugin yarn build popd # 用未发布的 razzle 包 指定 webpack 版本 指定测试用例运行示例测试 WEBPACK_DEPSwebpack5.24.0 html-webpack-plugin5.2.0 PACKAGE_MANAGERyalc NPM_TAGdevelopment yarn test:examples --runInBand -t with-tailwindcss WEBPACK_DEPSwebpack4.46.0 html-webpack-plugin4.5.2 PACKAGE_MANAGERyalc NPM_TAGdevelopment yarn test:examples --runInBand -t with-tailwindcss其中几个关键步骤的原理可从源码得到印证yarn new-example existingexample with-somefeature对应 scripts/new-example.js其实现是复制源示例目录到新目录并把新示例的package.json中name改写为razzle-examples-新名称随后默认自动执行bootstrap-examples。这与贡献文档「先改包名再 bootstrap」的建议是吻合的。yarn bootstrap-examples $example对应 scripts/bootstrap-examples.js它会读取示例的package.json中的razzle_meta字段可声明nohoist与extraWorkspacedirs把示例目录临时追加到根 package.json 的workspaces中执行yarn install --no-lockfile并在示例的node_modules/.bin下生成restrap可执行脚本内部就是再次调用yarn bootstrap-examples example。引导完成后会把根package.json的workspaces恢复为package.meta.json中的原始值。yarn restrap即上一步生成在示例内node_modules/.bin的脚本用于重新安装并恢复符号链接。webpack 版本切换yarn add -W webpack... html-webpack-plugin...在仓库根目录统一管理这两个构建依赖的版本。仓库默认锁定在 webpack 4根 package.json 的devDependencies为webpack: 4.46.0、html-webpack-plugin: 4.5.2而示例中的依赖版本参考 scripts/exampleDependencyVersions.json内部包的 peer 依赖范围参考 scripts/internalPeerDependencyVersions.jsonwebpack: ~4||~5。带环境变量的示例测试WEBPACK_DEPS指定示例实际使用的 webpack 版本组合PACKAGE_MANAGERyalc表示通过 yalc 将本地未发布的 razzle 包注入示例NPM_TAGdevelopment指定发布标签-t with-tailwindcss则用 jest 的-t参数只跑指定示例的用例。测试运行期间命令输出与 Puppeteer 截图会统一存放在test-artifacts/目录参见 test/jest.examples.config.js 中的 jest-html-reporters 配置。如果遇到 Puppeteer 启动问题常见于 Linux 容器环境可以尝试调整内核参数sudo sysctl -w kernel.unprivileged_userns_clone1同步上游更新当需要拉取 fork 的上游改动时切回主分支并执行 pull 即可git checkout master git pull origin master添加示例模板、命名与合并要求以 examples/basic 为模板新增示例推荐直接复制 examples/basic 作为基础模板yarn new-example basic your-example创建后先修改新示例package.json中的包名再回到仓库根目录执行yarn bootstrap-examples your-example确保新示例使用的是本地版本的packages/*而非 npm 已发布版本。命名规范示例文件夹统一命名为with-thing-you-are-demonstrating例如with-tailwindcss、with-loadable-components示例的 npm 包名package.json中的name统一为razzle-examples-with-thing-you-are-demonstrating。这一规则同样体现在new-example脚本中脚本会自动生成razzle-examples-新目录名这样的包名。示例如何被合并对关键代码写清注释并附上一段高质量的 Idea behind the example示例背后的设计思路说明——这一点比代码本身更重要一个示例只聚焦一个想法/库/特性例如不要提交with-styled-components-and-material-ui。特殊情况下可放宽比如展示 Apollo Redux 或某个 Flux 库 React Router 的组合示例必须实现热模块替换Hot Module Replacement如果编辑代码时页面不更新说明实现有误示例应保持极简或直接复制原库的知名示例例如直接从 react-redux 复制的示例。提交信息规范遵循 Angular 仓库的提交信息Commit message规范具体规则可参考 Angular 官方 CONTRIBUTING 文档中的对应章节。为什么我的 PR 没有被合并维护者会在关闭 PR 前尽量说明理由但约 80% 的情况属于以下四类之一没有阅读本贡献文档改动破坏了内部应用维护者会明确说明改动与未来的某些规划冲突同样会明确说明言论不当或违反了行为准则Code of Conduct。贡献者认可项目通过 README 表彰社区成员的贡献。添加贡献者使用all-contributors add github_username doc,code其中第二个参数是 all-contributors 的贡献类型键例如doc文档、code代码等合法键集合以 all-contributors 官方的 emoji-key 文档为准。仓库根 package.json 的devDependencies中同样内置了all-contributors-cli与这一流程配套。获取帮助如果在贡献过程中遇到问题可以通过 Twitter / DM 联系维护者jaredpalmer、nima_arf、fivethreeo。小结贡献 Razzle 的关键在于把packages核心实现与examples验证载体通过 Workspace 符号链接打通用yarn new-example生成示例、用yarn bootstrap-examples挂载本地包、用yarn test:examples配合WEBPACK_DEPS/PACKAGE_MANAGER环境变量在指定 webpack 版本下回归验证。遵循示例命名规范、HMR 要求与提交信息规范是让 PR 顺利合并的重要前提。赞分享前端构建工具前端构建后端【免费下载链接】razzle✨ Create server-rendered universal JavaScript applications with no configuration项目地址https://gitcode.com/gh_mirrors/ra/razzle点击查看免费下载相关推荐sshmuxd源码解析深入理解Go语言实现的SSH代理机制sshmuxd源码解析深入理解Go语言实现的SSH代理机制 sshmuxd是一个基于Go语言开发的SSH代理工具它能够帮助用户高效管理多个SSH连接实现便后端前端Web框架开发工具从零参与 Scalar 开源贡献Monorepo 开发环境、测试与 PR 提交流程全指南从零参与 Scalar 开源贡献Monorepo 开发环境、测试与 PR 提交流程全指南 Scalar 是一个开源 API 平台同时提供现代 REST AP开发工具API 工具前端react-window 贡献指南从本地开发、测试到提交 PR 的完整工作流react window 贡献指南从本地开发、测试到提交 PR 的完整工作流 本指南以仓库根目录的 CONTRIBUTING.md https://link.上一篇霞鹜文楷GB2025年中文排版终极指南告别字体混乱的烦恼下一篇WinUtil批量安装系统调优一条命令搞定创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考