为 react-use 贡献一个 React Hook完整贡献指南与源码级实战解析【免费下载链接】react-useReact Hooks — 项目地址: https://gitcode.com/gh_mirrors/re/react-use本篇指南围绕 react-use 官方贡献文档CONTRIBUTING.md展开完整讲解从环境搭建、新建/更新 Hook、编写测试与文档到按语义化提交规范推送代码的完整流程。react-use 是一个以 TypeScript 编写的 React Hooks 集合库当前仓库版本 17.6.1本指南将带你以useToggle为实例逐一印证贡献流程中每一个步骤在仓库中的真实落点读完即可上手提交你的第一个 Hook。一、贡献前必读react-use 的项目结构与四件套约定在动手之前先理解 react-use 的组织方式。这是一个React Hooks 集合库所有 Hook 按功能分类登记在 README.md 中Sensors、UI、Animations、Side-effects、Lifecycles、State 等分类而仓库目录结构遵循一套严格的一 Hook 四文件约定目录文件作用src/useYourHookName.tsHook 的 TypeScript 实现stories/useYourHookName.story.tsxStorybook 交互演示tests/useYourHookName.test.tsJest 单元测试docs/useYourHookName.md使用文档以useToggle为例这套约定在仓库中完整存在src/useToggle.ts、stories/useToggle.story.tsx、tests/useToggle.test.ts、docs/useToggle.md。贡献一个 Hook 的过程本质上就是补全这套四件套并完成登记。此外官方贡献指南明确指出本库是 React Hooks 集合因此新 Hook 的提案必须内部使用 React Hooks API 才有资格被纳入考虑——例如useToggle的实现就是基于 React 内置的useReducer封装而成。二、环境搭建Fork、克隆与依赖安装贡献流程的第一步是建立本地开发环境官方文档给出了三步标准操作Fork 并克隆仓库先在托管平台 Fork 一份到自己的账号下再克隆到本地安装依赖在仓库根目录运行yarn install本项目使用 Yarn 1.x 管理依赖锁文件为 yarn.lock创建 PR 分支运行git checkout -b pr/your-branch-name为你的 Pull Request 单独建立分支。Tip保持master与上游同步建议让本地master分支始终指向原始仓库并只从 fork 的分支发起 PR。官方推荐执行git remote add upstream https://github.com/streamich/react-use.git git fetch upstream git branch --set-upstream-toupstream/master master这三条命令依次完成将原始仓库添加为名为upstream的远程源、拉取上游的 git 信息、让本地master分支在每次git pull时跟踪上游 master。之后你所有的 PR 分支都基于这个保持同步的master创建需要更新本地 master 时执行常规的git pull即可。另外需要注意贡献即意味着你同意将你的工作成果按本项目许可证发布本项目采用 Unlicense 许可证见 LICENSE。如果你是第一次提 PR可参考社区通用的 First Contributions 入门教程熟悉整体流程。三、开发新 Hook 的标准流程四步走官方贡献文档为新建一个 Hook 定义了清晰的四步流程每步都对应一个可运行的开发工具。下面以useToggle为实例逐一解析。第一步编写实现与 Storybook 演示创建src/useYourHookName.ts与stories/useYourHookName.story.tsx然后运行yarn start启动 Storybook 开发服务器端口 6008见 package.json 中start: yarn storybook、storybook: start-storybook -p 6008在浏览器中边写边看效果。useToggle的实现非常精简可作为新 Hook 的模板src/useToggle.tsimport { Reducer, useReducer } from react; const toggleReducer (state: boolean, nextValue?: any) typeof nextValue boolean ? nextValue : !state; const useToggle (initialValue: boolean): [boolean, (nextValue?: any) void] { return useReducerReducerboolean, any(toggleReducer, initialValue); }; export default useToggle;可以看到它内部使用了 React 的useReducer通过一个纯 reducer 表达传入布尔值则直接设置、否则取反的切换逻辑——这正是贡献指南要求的利用 React Hooks API的典型实现。对应的 Story 文件stories/useToggle.story.tsx结构如下用storiesOf注册分组Docs页通过ShowDocs组件直接渲染docs/useToggle.md文档Demo页提供一个可交互的 ON/OFF 演示import { storiesOf } from storybook/react; import * as React from react; import { useToggle } from ../src; import ShowDocs from ./util/ShowDocs; const Demo () { const [on, toggle] useToggle(true); return ( div div{on ? ON : OFF}/div button onClick{toggle}Toggle/button button onClick{() toggle(true)}set ON/button button onClick{() toggle(false)}set OFF/button /div ); }; storiesOf(State/useToggle, module) .add(Docs, () ShowDocs md{require(../docs/useToggle.md)} /) .add(Demo, () Demo /);仓库中的演示工具组件统一放在 stories/util/ 下如ShowDocs、CenterStory、ConsoleStory、NewTabStory新 Hook 的 Story 可以直接复用。第二步编写测试并进入 watch 模式创建tests/useYourHookName.test.ts运行yarn test:watch即jest --watch见 package.json启动 Jest 的监听模式边写测试边看结果。useToggle的测试tests/useToggle.test.ts展示了本项目测试的标准写法使用testing-library/react-hooks的renderHook渲染 Hook用act包裹触发状态更新的调用然后断言返回值import { act, renderHook } from testing-library/react-hooks; import useToggle from ../src/useToggle; const setUp (initialValue: boolean) renderHook(() useToggle(initialValue)); it(should init state to true, () { const { result } setUp(true); expect(result.current[0]).toBe(true); expect(typeof result.current[1]).toBe(function); }); it(should toggle state from true, () { const { result } setUp(true); const [, toggle] result.current; act(() { toggle(); }); expect(result.current[0]).toBe(false); }); it(should ignore non-boolean parameters and toggle state, () { const { result } setUp(true); const [, toggle] result.current; act(() { toggle(string); }); expect(result.current[0]).toBe(false); });值得注意的细节项目针对浏览器类 Hook 使用 jsdom 测试环境jest.config.ts 中testEnvironment: jsdom基础配置聚合在 jest.config.base.ts普通yarn test命令为jest --maxWorkers 2另有针对 SSR 场景的yarn test:ssr使用 jest.config.node.ts 配置。如果你更习惯测试驱动开发TDD官方文档也明确说明可以先写测试、后写实现。第三步编写文档创建docs/useYourHookName.md为你的 Hook 编写使用文档。文档会被 Storybook 的 Docs 页直接渲染见上文的ShowDocs用法同时也会登记在 README.md 中供用户查阅。docs/useToggle.md是极简但完整的文档范例——说明 Hook 用途、给出可直接运行的用法代码# useToggle React state hook that tracks value of a boolean. useBoolean is an alias for useToggle. ## Usage jsx import {useToggle} from react-use; const Demo () { const [on, toggle] useToggle(true); return ( div div{on ? ON : OFF}/div button onClick{toggle}Toggle/button button onClick{() toggle(true)}set ON/button button onClick{() toggle(false)}set OFF/button /div ); }; 第四步导出并登记到 README最后在 src/index.ts 中导出你的 Hook并在 README.md 的分类列表中添加条目。src/index.ts是库的唯一公共入口共 117 行导出声明例如useToggle通过export { default as useToggle } from ./useToggle;导出。这里有一个值得新贡献者注意的细节并非所有 Hook 都会从入口导出。从 src/index.ts 源码可以看到useKeyboardJs和useSpring被注释掉并标注了原因——not exported because of peer dependency因 peer 依赖问题未导出。如果你开发的新 Hook 依赖了额外的 peer 依赖需要评估是否适合作为默认导出。四、更新已有 Hook 的工作流如果你要修改的是仓库中已有的 Hook官方文档给出了更轻量的三步流程运行yarn start启动 Storybook 开发服务器开始应用修改随时通过交互演示验证行为运行yarn test:watch监听测试根据你的改动同步更新测试用例同步更新文档docs/useYourHookName.md确保文档与行为一致。核心原则与新建 Hook 一致实现、测试、文档三者同步演进任何行为变更都必须有测试覆盖、有文档说明。五、提交与推送Commit 规范与 Git HooksConventional Commits 与语义化发布本仓库使用 semantic-release 与 conventional commit messages 规范自动生成版本与发布。因此你的提交消息需要以前缀开头以fix:开头——你的改动会进入修复版本patch的发布说明以feat:开头——你的改动会进入新功能版本minor的发布说明发布说明统一记录在仓库根目录的 CHANGELOG.md 中。从 package.json 的release配置可以看到发布细节发布分支为master另有next分支作为预发布prereleaserc发布管线由semantic-release/changelog、semantic-release/npm、semantic-release/git三个插件协同完成。Git Hooks 自动校验与临时跳过项目通过 Husky 配置了 Git hooks依赖安装后自动启用。从 package.json 的husky.hooks可以看到pre-commit: lint-staged, pre-push: yarn lint yarn clean yarn build yarn testpre-commit执行lint-staged仅对暂存区中src/**下的.ts/.tsx文件运行eslint --fix并重新git add见lint-staged配置保证提交的代码通过 ESLint 检查pre-push执行完整的质量链路——yarn lintESLint 检查src/tests/stories下的 TypeScript 文件、yarn clean清理旧构建产物、yarn build分别构建 CJS 与 ESM 产物、yarn test运行全部测试。这些 hooks 在创建提交时自动测试和校验代码非常方便。但当你希望提交尚未完成的代码以快速获得反馈时可以给 commit 命令加上--no-verify标志临时跳过校验。六、项目需要你的帮助Issues 与测试覆盖率除了提交新 Hook官方贡献文档还列出了两类特别需要帮助的方向回应用 open issues帮助维护者处理问题报告bug与功能请求feature request参与讨论本身就是重要的贡献形式提升测试覆盖率项目正在努力改善代码覆盖率。运行yarn test:coverage即jest --coverage即可生成覆盖率报告——结果会直接输出在终端也可以打开coverage/lcov-report/index.html查看可视化的 HTML 报告据此找出尚未覆盖的 Hook 并补写测试。从 tests/ 目录可以看到绝大多数 Hook 都已有对应的测试文件如 tests/useToggle.test.ts、tests/useAsyncFn.test.tsx 等贡献者可以对照覆盖率报告找到薄弱环节。七、贡献流程速查表阶段操作对应命令/文件环境搭建Fork 克隆、安装依赖、建分支yarn install、git checkout -b pr/your-branch-name同步上游添加 upstream 远程并跟踪 mastergit remote add upstream ...、git fetch upstream、git branch --set-upstream-to新建 Hook实现 Story 测试 文档yarn start、yarn test:watch登记导出入口导出 README 登记修改 src/index.ts、README.md更新 Hook改实现、同步测试与文档yarn start、yarn test:watch提交Conventional Commits 前缀fix:/feat:见 CHANGELOG.md推送校验自动 lint build testpre-commit / pre-push hooks可用--no-verify临时跳过帮助项目回应 issues、提升覆盖率yarn test:coverage查看coverage/lcov-report/index.html几点实用建议始终从同步好的master切出 PR 分支避免直接向 master 推送提交消息严格遵循fix:/feat:前缀以配合语义化发布新 Hook 务必同时交付实现、Story、测试、文档四件套并确认内部使用 React Hooks API如果选择 TDD可以先写测试再实现。遵循这套流程你的贡献就能顺畅地进入 react-use 的版本发布周期。【免费下载链接】react-useReact Hooks — 项目地址: https://gitcode.com/gh_mirrors/re/react-use创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 为 react-use 贡献一个 React Hook：完整贡献指南与源码级实战解析
为 react-use 贡献一个 React Hook完整贡献指南与源码级实战解析【免费下载链接】react-useReact Hooks — 项目地址: https://gitcode.com/gh_mirrors/re/react-use本篇指南围绕 react-use 官方贡献文档CONTRIBUTING.md展开完整讲解从环境搭建、新建/更新 Hook、编写测试与文档到按语义化提交规范推送代码的完整流程。react-use 是一个以 TypeScript 编写的 React Hooks 集合库当前仓库版本 17.6.1本指南将带你以useToggle为实例逐一印证贡献流程中每一个步骤在仓库中的真实落点读完即可上手提交你的第一个 Hook。一、贡献前必读react-use 的项目结构与四件套约定在动手之前先理解 react-use 的组织方式。这是一个React Hooks 集合库所有 Hook 按功能分类登记在 README.md 中Sensors、UI、Animations、Side-effects、Lifecycles、State 等分类而仓库目录结构遵循一套严格的一 Hook 四文件约定目录文件作用src/useYourHookName.tsHook 的 TypeScript 实现stories/useYourHookName.story.tsxStorybook 交互演示tests/useYourHookName.test.tsJest 单元测试docs/useYourHookName.md使用文档以useToggle为例这套约定在仓库中完整存在src/useToggle.ts、stories/useToggle.story.tsx、tests/useToggle.test.ts、docs/useToggle.md。贡献一个 Hook 的过程本质上就是补全这套四件套并完成登记。此外官方贡献指南明确指出本库是 React Hooks 集合因此新 Hook 的提案必须内部使用 React Hooks API 才有资格被纳入考虑——例如useToggle的实现就是基于 React 内置的useReducer封装而成。二、环境搭建Fork、克隆与依赖安装贡献流程的第一步是建立本地开发环境官方文档给出了三步标准操作Fork 并克隆仓库先在托管平台 Fork 一份到自己的账号下再克隆到本地安装依赖在仓库根目录运行yarn install本项目使用 Yarn 1.x 管理依赖锁文件为 yarn.lock创建 PR 分支运行git checkout -b pr/your-branch-name为你的 Pull Request 单独建立分支。Tip保持master与上游同步建议让本地master分支始终指向原始仓库并只从 fork 的分支发起 PR。官方推荐执行git remote add upstream https://github.com/streamich/react-use.git git fetch upstream git branch --set-upstream-toupstream/master master这三条命令依次完成将原始仓库添加为名为upstream的远程源、拉取上游的 git 信息、让本地master分支在每次git pull时跟踪上游 master。之后你所有的 PR 分支都基于这个保持同步的master创建需要更新本地 master 时执行常规的git pull即可。另外需要注意贡献即意味着你同意将你的工作成果按本项目许可证发布本项目采用 Unlicense 许可证见 LICENSE。如果你是第一次提 PR可参考社区通用的 First Contributions 入门教程熟悉整体流程。三、开发新 Hook 的标准流程四步走官方贡献文档为新建一个 Hook 定义了清晰的四步流程每步都对应一个可运行的开发工具。下面以useToggle为实例逐一解析。第一步编写实现与 Storybook 演示创建src/useYourHookName.ts与stories/useYourHookName.story.tsx然后运行yarn start启动 Storybook 开发服务器端口 6008见 package.json 中start: yarn storybook、storybook: start-storybook -p 6008在浏览器中边写边看效果。useToggle的实现非常精简可作为新 Hook 的模板src/useToggle.tsimport { Reducer, useReducer } from react; const toggleReducer (state: boolean, nextValue?: any) typeof nextValue boolean ? nextValue : !state; const useToggle (initialValue: boolean): [boolean, (nextValue?: any) void] { return useReducerReducerboolean, any(toggleReducer, initialValue); }; export default useToggle;可以看到它内部使用了 React 的useReducer通过一个纯 reducer 表达传入布尔值则直接设置、否则取反的切换逻辑——这正是贡献指南要求的利用 React Hooks API的典型实现。对应的 Story 文件stories/useToggle.story.tsx结构如下用storiesOf注册分组Docs页通过ShowDocs组件直接渲染docs/useToggle.md文档Demo页提供一个可交互的 ON/OFF 演示import { storiesOf } from storybook/react; import * as React from react; import { useToggle } from ../src; import ShowDocs from ./util/ShowDocs; const Demo () { const [on, toggle] useToggle(true); return ( div div{on ? ON : OFF}/div button onClick{toggle}Toggle/button button onClick{() toggle(true)}set ON/button button onClick{() toggle(false)}set OFF/button /div ); }; storiesOf(State/useToggle, module) .add(Docs, () ShowDocs md{require(../docs/useToggle.md)} /) .add(Demo, () Demo /);仓库中的演示工具组件统一放在 stories/util/ 下如ShowDocs、CenterStory、ConsoleStory、NewTabStory新 Hook 的 Story 可以直接复用。第二步编写测试并进入 watch 模式创建tests/useYourHookName.test.ts运行yarn test:watch即jest --watch见 package.json启动 Jest 的监听模式边写测试边看结果。useToggle的测试tests/useToggle.test.ts展示了本项目测试的标准写法使用testing-library/react-hooks的renderHook渲染 Hook用act包裹触发状态更新的调用然后断言返回值import { act, renderHook } from testing-library/react-hooks; import useToggle from ../src/useToggle; const setUp (initialValue: boolean) renderHook(() useToggle(initialValue)); it(should init state to true, () { const { result } setUp(true); expect(result.current[0]).toBe(true); expect(typeof result.current[1]).toBe(function); }); it(should toggle state from true, () { const { result } setUp(true); const [, toggle] result.current; act(() { toggle(); }); expect(result.current[0]).toBe(false); }); it(should ignore non-boolean parameters and toggle state, () { const { result } setUp(true); const [, toggle] result.current; act(() { toggle(string); }); expect(result.current[0]).toBe(false); });值得注意的细节项目针对浏览器类 Hook 使用 jsdom 测试环境jest.config.ts 中testEnvironment: jsdom基础配置聚合在 jest.config.base.ts普通yarn test命令为jest --maxWorkers 2另有针对 SSR 场景的yarn test:ssr使用 jest.config.node.ts 配置。如果你更习惯测试驱动开发TDD官方文档也明确说明可以先写测试、后写实现。第三步编写文档创建docs/useYourHookName.md为你的 Hook 编写使用文档。文档会被 Storybook 的 Docs 页直接渲染见上文的ShowDocs用法同时也会登记在 README.md 中供用户查阅。docs/useToggle.md是极简但完整的文档范例——说明 Hook 用途、给出可直接运行的用法代码# useToggle React state hook that tracks value of a boolean. useBoolean is an alias for useToggle. ## Usage jsx import {useToggle} from react-use; const Demo () { const [on, toggle] useToggle(true); return ( div div{on ? ON : OFF}/div button onClick{toggle}Toggle/button button onClick{() toggle(true)}set ON/button button onClick{() toggle(false)}set OFF/button /div ); }; 第四步导出并登记到 README最后在 src/index.ts 中导出你的 Hook并在 README.md 的分类列表中添加条目。src/index.ts是库的唯一公共入口共 117 行导出声明例如useToggle通过export { default as useToggle } from ./useToggle;导出。这里有一个值得新贡献者注意的细节并非所有 Hook 都会从入口导出。从 src/index.ts 源码可以看到useKeyboardJs和useSpring被注释掉并标注了原因——not exported because of peer dependency因 peer 依赖问题未导出。如果你开发的新 Hook 依赖了额外的 peer 依赖需要评估是否适合作为默认导出。四、更新已有 Hook 的工作流如果你要修改的是仓库中已有的 Hook官方文档给出了更轻量的三步流程运行yarn start启动 Storybook 开发服务器开始应用修改随时通过交互演示验证行为运行yarn test:watch监听测试根据你的改动同步更新测试用例同步更新文档docs/useYourHookName.md确保文档与行为一致。核心原则与新建 Hook 一致实现、测试、文档三者同步演进任何行为变更都必须有测试覆盖、有文档说明。五、提交与推送Commit 规范与 Git HooksConventional Commits 与语义化发布本仓库使用 semantic-release 与 conventional commit messages 规范自动生成版本与发布。因此你的提交消息需要以前缀开头以fix:开头——你的改动会进入修复版本patch的发布说明以feat:开头——你的改动会进入新功能版本minor的发布说明发布说明统一记录在仓库根目录的 CHANGELOG.md 中。从 package.json 的release配置可以看到发布细节发布分支为master另有next分支作为预发布prereleaserc发布管线由semantic-release/changelog、semantic-release/npm、semantic-release/git三个插件协同完成。Git Hooks 自动校验与临时跳过项目通过 Husky 配置了 Git hooks依赖安装后自动启用。从 package.json 的husky.hooks可以看到pre-commit: lint-staged, pre-push: yarn lint yarn clean yarn build yarn testpre-commit执行lint-staged仅对暂存区中src/**下的.ts/.tsx文件运行eslint --fix并重新git add见lint-staged配置保证提交的代码通过 ESLint 检查pre-push执行完整的质量链路——yarn lintESLint 检查src/tests/stories下的 TypeScript 文件、yarn clean清理旧构建产物、yarn build分别构建 CJS 与 ESM 产物、yarn test运行全部测试。这些 hooks 在创建提交时自动测试和校验代码非常方便。但当你希望提交尚未完成的代码以快速获得反馈时可以给 commit 命令加上--no-verify标志临时跳过校验。六、项目需要你的帮助Issues 与测试覆盖率除了提交新 Hook官方贡献文档还列出了两类特别需要帮助的方向回应用 open issues帮助维护者处理问题报告bug与功能请求feature request参与讨论本身就是重要的贡献形式提升测试覆盖率项目正在努力改善代码覆盖率。运行yarn test:coverage即jest --coverage即可生成覆盖率报告——结果会直接输出在终端也可以打开coverage/lcov-report/index.html查看可视化的 HTML 报告据此找出尚未覆盖的 Hook 并补写测试。从 tests/ 目录可以看到绝大多数 Hook 都已有对应的测试文件如 tests/useToggle.test.ts、tests/useAsyncFn.test.tsx 等贡献者可以对照覆盖率报告找到薄弱环节。七、贡献流程速查表阶段操作对应命令/文件环境搭建Fork 克隆、安装依赖、建分支yarn install、git checkout -b pr/your-branch-name同步上游添加 upstream 远程并跟踪 mastergit remote add upstream ...、git fetch upstream、git branch --set-upstream-to新建 Hook实现 Story 测试 文档yarn start、yarn test:watch登记导出入口导出 README 登记修改 src/index.ts、README.md更新 Hook改实现、同步测试与文档yarn start、yarn test:watch提交Conventional Commits 前缀fix:/feat:见 CHANGELOG.md推送校验自动 lint build testpre-commit / pre-push hooks可用--no-verify临时跳过帮助项目回应 issues、提升覆盖率yarn test:coverage查看coverage/lcov-report/index.html几点实用建议始终从同步好的master切出 PR 分支避免直接向 master 推送提交消息严格遵循fix:/feat:前缀以配合语义化发布新 Hook 务必同时交付实现、Story、测试、文档四件套并确认内部使用 React Hooks API如果选择 TDD可以先写测试再实现。遵循这套流程你的贡献就能顺畅地进入 react-use 的版本发布周期。【免费下载链接】react-useReact Hooks — 项目地址: https://gitcode.com/gh_mirrors/re/react-use创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考