Onboarding: streamich/react-use

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/streamich/react-use shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across all four use cases

• Last commit 4mo ago
• 12 active contributors
• Unlicense licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 4mo ago
• ⚠ Concentrated ownership — top contributor handles 56% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live streamich/react-use repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/streamich/react-use.

What it runs against: a local clone of streamich/react-use — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in streamich/react-use | Confirms the artifact applies here, not a fork | | 2 | License is still Unlicense | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 135 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>streamich/react-use</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of streamich/react-use. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/streamich/react-use.git
#   cd react-use
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of streamich/react-use and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "streamich/react-use(\\.git)?\\b" \\
  && ok "origin remote is streamich/react-use" \\
  || miss "origin remote is not streamich/react-use (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Unlicense)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Unlicense\"" package.json 2>/dev/null) \\
  && ok "license is Unlicense" \\
  || miss "license drift — was Unlicense at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"
test -f "src/index.ts" \\
  && ok "src/index.ts" \\
  || miss "missing critical file: src/index.ts"
test -f "tsconfig.json" \\
  && ok "tsconfig.json" \\
  || miss "missing critical file: tsconfig.json"
test -f "babel.config.js" \\
  && ok "babel.config.js" \\
  || miss "missing critical file: babel.config.js"
test -f ".eslintrc.js" \\
  && ok ".eslintrc.js" \\
  || miss "missing critical file: .eslintrc.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 135 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~105d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/streamich/react-use"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

react-use is a collection of 100+ essential React Hooks covering sensors (battery, geolocation, keyboard events), state management (useAsync, useCounter, useToggle), side effects (useDebounce, useThrottle, useEffectOnce), and UI utilities (useCopyToClipboard, useClickAway, useHover). It solves the problem of repeatedly writing common hook patterns by providing production-ready, well-tested implementations that handle edge cases and browser APIs. Monolithic package structure: source hooks live in src/ organized by category (Sensors.md, State.md, Side-effects.md, etc.), compiled to both CommonJS (lib/) and ES modules (esm/) via TypeScript. Documentation lives in docs/ with one .md file per hook. Storybook stories in stories/ provide interactive demos, and comprehensive Jest tests are colocated with source.

Who it's for

React developers building interactive applications who need pre-built hooks for common UI patterns (form handling, async operations, event tracking) rather than writing custom hooks or relying on ad-hoc implementations. Also used by teams standardizing on a shared hooks library to reduce code duplication across projects.

Maturity & risk

Production-ready. At version 17.6.0 with 7.5k+ GitHub stars, comprehensive test coverage, TypeScript support throughout, and CI/CD via GitHub Actions (workflows for check-codebase, release, mirror). The codebase is actively maintained with semantic-release automation, though commit recency and issue response should be verified.

Low-to-medium risk. Single maintainer (@streamich) creates potential bus-factor risk for critical bugs. Dependency count is moderate (~12 direct dependencies including screenfull, nano-css, copy-to-clipboard) with some older libraries (js-cookie v2.2.1). The broad hook surface area means API changes could affect many downstream consumers, though semantic versioning is enforced via semantic-release.

Active areas of work

Unable to determine from provided data—no recent commit timestamps or PR list visible. However, the repo has semantic-release automation in .github/workflows/release.yml, suggesting active deployment. Check GitHub Issues and recent releases at https://github.com/streamich/react-use/releases for current activity.

Get running

git clone https://github.com/streamich/react-use.git && cd react-use && yarn install && yarn start

Daily commands: yarn start (launches Storybook on port 6008 with live demos) or yarn test (runs Jest suite) or yarn build (compiles TypeScript to lib/ and esm/).

Map of the codebase

• package.json — Entry point definition with main/module exports; all contributors must understand the dual CJS/ESM build strategy and published artifact paths
• src/index.ts — Central barrel export aggregating all hooks; required reading to understand the library's public API surface
• tsconfig.json — TypeScript configuration controlling type checking, output targets, and declaration generation; affects all hook implementations
• babel.config.js — Babel transformation pipeline for JSX and modern syntax; critical for ensuring hooks compile correctly across environments
• .eslintrc.js — Linting rules enforcing React Hooks best practices (hooks dependencies, etc.); every PR must pass these checks
• jest.config.js — Test harness configuration; contributors must understand how hooks are unit-tested before adding new ones
• .github/workflows/check-codebase.yml — CI/CD pipeline validating build, tests, and types on every PR; establishes quality gates contributors must meet

Components & responsibilities

• useAsync / useAsyncFn (React.useState, React.useEffect, Promise) — Manages async operation lifecycle (loading, success, error); retries on demand; tracks promise state
  • Failure mode: Unhandled promise rejections if error state not rendered; stale closures if dependency array omitted
• useLocalStorage / useSessionStorage (React.useState, React.) — Syncs React state with browser storage; reads/writes on mount and state change; handles quota errors

How to make changes

Add a new Hook

1. Create hook implementation file in src/ named useMyFeature.ts following existing hook patterns (e.g., src/useMouse.ts for reference) (src/useMyFeature.ts)
2. Export the hook from the main barrel export (src/index.ts)
3. Write unit tests covering hook behavior with mocking (see jest.config.js for test patterns) (tests/useMyFeature.test.ts)
4. Create markdown documentation at docs/useMyFeature.md with usage example and signature (docs/useMyFeature.md)
5. Optional: Create Storybook demo in stories/ directory to show interactive usage (stories/useMyFeature.stories.tsx)

Update Hook Types or Signature

1. Modify the hook implementation and TypeScript signature in src/useExisting.ts (src/useExisting.ts)
2. Run yarn lint:types to validate TypeScript compatibility (tsconfig.json)
3. Update corresponding markdown documentation with new parameters or return values (docs/useExisting.md)
4. Update or add tests to cover new behavior in tests/useExisting.test.ts (tests/useExisting.test.ts)

Fix a Bug in Hook

1. Add a failing test case reproducing the bug in tests/useTargetHook.test.ts (tests/useTargetHook.test.ts)
2. Fix the implementation in src/useTargetHook.ts until test passes (src/useTargetHook.ts)
3. Run yarn test to ensure no regression in other hooks (jest.config.js)
4. Update docs/useTargetHook.md if behavior changes or edge case is clarified (docs/useTargetHook.md)

Why these technologies

• TypeScript — Provides type safety for hook signatures and return types; enables IDE autocompletion and catches parameter mismatches at development time
• Jest + React Testing Library — Allows isolation testing of hooks in JSDOM environment; simulates DOM events and hook state changes without requiring a full browser
• Dual CJS/ESM builds (tsc outputs) — Supports both CommonJS (legacy Node/bundlers) and ES modules (modern bundlers, native browser imports); maximizes compatibility across ecosystems
• Storybook — Provides interactive visual testing and documentation of hook behavior; enables contributors to verify UI changes without writing full pages
• GitHub Actions — Automates linting, type-checking, and testing on every PR; ensures quality gates are enforced before merge

Trade-offs already made

• Dual CJS/ESM output via tsc (not a bundler like Rollup)

  • Why: Simpler build pipeline; allows tree-shaking in ES module consumers; direct TypeScript transpilation without extra abstraction
  • Consequence: Users must transpile TypeScript themselves if targeting older JS versions; no automatic polyfills

• Collection of independent hooks rather than monolithic utility library

  • Why: Allows granular imports and tree-shaking; users only pay for what they use; easier to test and reason about individual hooks
  • Consequence: Higher cognitive load for first-time users; must learn 100+ APIs; some utility patterns duplicated across hooks

• No server-side rendering (SSR) safety by default (except useIsomorphicLayoutEffect)

  • Why: Reduces bundle size and complexity; most hooks assume DOM availability; SSR is opt-in concern
  • Consequence: Developers must manually check for typeof window and conditional imports to avoid hydration mismatches

• Zero external dependencies (pure React/DOM APIs only)

  • Why: Minimizes supply-chain risk; ensures hooks remain lightweight; maximum compatibility
  • Consequence: Developers cannot use rich third-party libraries within hooks (e.g., for gesture detection); must implement patterns manually

Non-goals (don't propose these)

• Does not provide form state management (forms are deferred to react-hook-form or similar)
• Does not provide global state management (context factories only; full Redux/Zustand deferred to user choice)
• Does not handle server-side rendering by default (browser APIs assumed; SSR requires manual wrapping)
• Does not provide UI components (only state/lifecycle/sensor logic hooks)
• Does not include performance optimization libraries beyond React.memo helpers

Traps & gotchas

SSR testing: hooks using browser APIs (window, document, navigator) fail in Node.js without polyfills—see jest.config.node.ts and test:ssr script. TypeScript strict mode enabled in tsconfig.json (verify before adding types). Pre-push hook runs full build+test+lint suite and can be slow on first commit—use git push --no-verify carefully. Storybook webpack config (.storybook/webpack.config.js) may need updates if adding new asset types. Semantic-release requires specific commit message format (feat:, fix:, BREAKING CHANGE:) for version bumps.

Architecture

Concepts to learn

• React Hooks (Custom Hooks) — Core abstraction of this library—understanding how to write reusable stateful logic as functions (not classes) is essential to using and contributing to react-use
• Sensor/Observable Pattern — Many react-use hooks (useBattery, useGeolocation, useMedia, useIntersection) track browser/device state changes in real-time; understanding event subscription and cleanup is critical
• SSR Compatibility & Hydration — Hooks must work in both browser and Node.js environments; the library handles this via feature detection and polyfills (test:ssr tests Node.js scenarios)
• Shallow vs Deep Equality — react-use includes both fast-shallow-equal and fast-deep-equal for dependency comparison; choosing the right one affects performance and correctness in hooks like useDeepCompareEffect
• Debouncing and Throttling — Foundational patterns in useDebounce, useThrottle, and event handlers; essential for optimizing expensive operations (API calls, resize handlers) and preventing rapid re-renders
• Dual ESM/CJS Build Outputs — react-use exports both CommonJS (lib/) and ES modules (esm/) via TypeScript compilation flags; necessary for compatibility with different bundler ecosystems (webpack, esbuild, Node.js require)
• Lifecycle Timing (useEffect dependencies & cleanup) — Hooks like useEffectOnce, useAsync, and event listeners rely on precise cleanup timing to prevent memory leaks; misunderstanding useEffect dependency arrays is a common source of bugs

Related repos

• alibaba/hooks — Direct competitor: Chinese React Hooks library with 70+ hooks, similar scope (useRequest, useVirtualList, useForm), different maintenance model
• streamich/libreact — Predecessor/inspiration: the original non-hooks version of react-use; react-use is explicitly a port of libreact to modern React Hooks API
• react-hook-form/react-hook-form — Companion library: specialized for form state management; often used alongside react-use's simpler useInput/useToggle for complex forms
• vercel/swr — Ecosystem alternative: data fetching hook library; provides useAsync-like functionality but with built-in caching and revalidation for API calls
• lodash/lodash — Foundational dependency source: react-use wraps utilities like debounce/throttle from lodash-adjacent libraries (throttle-debounce) for React-specific use cases

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive SSR/Node.js tests for browser-dependent hooks

The repo has a separate Jest config for SSR testing (jest.config.node.ts) and a test:ssr script, but many hooks like useFullscreen, useHover, useDrop, useIntersection likely lack SSR-safe test coverage. This prevents runtime errors in Next.js/SSR apps. A new contributor could audit hooks that access browser APIs (window, document, DOM) and add explicit SSR tests to ensure graceful degradation.

• [ ] Identify hooks accessing browser APIs in src/ that lack SSR tests (check tests/ for missing *ssr.test.ts files)
• [ ] For hooks like useFullscreen, useHover, useDrop, useIntersection, add tests in jest.config.node.ts that verify they return safe defaults or early-exit in Node.js
• [ ] Ensure tests verify no runtime errors occur when these hooks are called in SSR context
• [ ] Run yarn test:ssr to validate the new tests pass

Add missing hook documentation files for hooks in src/ without docs/

The docs/ folder is incomplete. By comparing src/ hook implementations against docs/*.md files, there are likely hooks like useMediaQuery, useNetworkState, useHistory, or others missing dedicated documentation. Each hook deserves a docs file with signature, examples, and use cases to match the existing pattern.

• [ ] List all exported hooks from src/index.ts and cross-reference against existing docs/*.md files
• [ ] For each missing hook, create a docs/{hookName}.md file following the format of existing docs (e.g., docs/useAsync.md)
• [ ] Include TypeScript signature, parameters, return type, and a practical example
• [ ] Update docs/Usage.md or main README.md to link to any newly documented hooks

Add GitHub Actions workflow to detect missing TypeScript definitions or type coverage regressions

The repo has types: 'lib/index.d.ts' but no CI check to enforce that all exported hooks have proper TypeScript definitions. A new workflow could run dtslint or a custom type-checking script on PRs to prevent type definition drift, especially important given the broad API surface of 50+ hooks.

• [ ] Create .github/workflows/type-coverage.yml that runs on pull_request and push to master
• [ ] Add a lint:types check (already in package.json but not in CI) or implement a script using dtslint to validate lib/index.d.ts completeness
• [ ] Ensure the workflow fails if any exported hook lacks a corresponding TypeScript definition
• [ ] Test the workflow by temporarily breaking a type definition and verifying it fails the CI check

Good first issues

• Write missing integration tests for SSR edge cases: some hooks using window/document may not have Node.js test coverage. Check jest.config.node.ts and test:ssr output for untested paths.
• Expand TypeScript docs for hooks with complex generics: review docs/ folder—hooks like useAsync and useAsyncFn accept complex type parameters but lack detailed TypeScript usage examples in their .md files.
• Add Storybook stories for accessibility scenarios: many UI hooks (useHover, useClickAway, useKeyPress) lack ARIA labeling examples in stories/*.tsx—add a11y annotations to existing stories to improve docs.

Top contributors

• @renovate[bot] — 56 commits
• @streamich — 22 commits
• @semantic-release-bot — 9 commits
• @suisous — 3 commits
• @mahmoud-elgammal — 2 commits

Recent commits

• 9ef9535 — chore(deps): update babel monorepo to v7.28.3 (#2666) (renovate[bot])
• 68723a5 — chore(deps): update dependency eslint-plugin-react to v7.37.5 (#2659) (renovate[bot])
• e19a114 — chore(deps): update dependency eslint-plugin-jsx-a11y to v6.10.2 (#2658) (renovate[bot])
• 756784f — chore(deps): update dependency eslint-plugin-import to v2.32.0 (#2657) (renovate[bot])
• f6b9c35 — chore(deps): update dependency babel-loader to v8.4.1 (#2656) (renovate[bot])
• c60dda9 — chore(deps): update babel monorepo (#2655) (renovate[bot])
• b80305e — chore(deps): update semantic-release monorepo (#2654) (renovate[bot])
• 7ff66bc — chore(deps): update dependency react-spring to v9.7.5 (#2652) (renovate[bot])
• 7dafd4c — chore(deps): update dependency rxjs to v7.8.2 (#2653) (renovate[bot])
• 9547d8e — chore(deps): update dependency eslint-plugin-prettier to v4.2.5 (#2651) (renovate[bot])

Security observations

The react-use library has a moderate security posture. The primary concerns are outdated dependencies (js-cookie@2.2.1 is from 2017), incomplete package.json configuration, and lack of explicit security scanning in CI/CD pipelines. The library maintains a security policy and contact process, which is positive. However, dependency updates and automated security testing should be prioritized. As this is a widely-used React Hooks library, vulnerabilities in dependencies could affect numerous downstream projects. No hardcoded secrets, injection risks via raw SQL, or infrastructure misconfigurations were identified.

• High · Outdated Dependency: js-cookie — package.json - dependencies.js-cookie. The package uses js-cookie@^2.2.1, which is significantly outdated. Version 2.2.1 was released in 2017 and may contain known security vulnerabilities. Current versions are in the 3.x range with security patches and improvements. Fix: Update js-cookie to the latest stable version (^3.0.0 or higher). Run 'npm audit' to identify specific CVEs and update accordingly.
• Medium · Outdated Dependency: screenfull — package.json - dependencies.screenfull. The package uses screenfull@^5.1.0 from 2020. Newer versions (5.2.x) contain bug fixes and potential security improvements. Consider updating to the latest version. Fix: Update screenfull to the latest available version. Review changelog for security-related fixes before updating.
• Medium · Outdated Dependency: nano-css — package.json - dependencies.nano-css. The package uses nano-css@^5.6.2. This CSS-in-JS library should be reviewed for any known security issues related to style injection or XSS vulnerabilities in CSS processing. Fix: Run 'npm audit' to check for known vulnerabilities. Consider using css-in-js libraries with active maintenance and regular security updates.
• Medium · Incomplete package.json - Missing peerDependencies — package.json - peerDependencies field. The peerDependencies field in package.json is incomplete (truncated). This could indicate incomplete configuration or potential dependency resolution issues. Fix: Complete and review the peerDependencies section to ensure proper React version compatibility is specified.
• Low · Missing Security.md Implementation Details — SECURITY.md. While a SECURITY.md file exists with vulnerability reporting guidelines, there are no details about security testing practices, dependency scanning, or security release procedures documented. Fix: Expand SECURITY.md to include: dependency scanning policies (e.g., npm audit frequency), security testing in CI/CD pipeline, and security release procedures.
• Low · No SAST/Dependency Scanning in CI/CD — .github/workflows/. Review of GitHub workflows (check-codebase.yml, release.yml) does not show explicit security scanning steps like npm audit, SNYK, or similar tools integrated into the pipeline. Fix: Add automated security scanning to CI/CD pipeline: npm audit, Dependabot, or SNYK integration to catch vulnerabilities before release.
• Low · Potential XSS Risk in DOM Manipulation Hooks — src/ (not fully visible - hooks like useCss, useLocalStorage). The library includes multiple hooks that interact with the DOM (useCss, useLocalStorage, etc.). While the codebase wasn't fully reviewed, DOM manipulation hooks may be vulnerable to XSS if user input is not properly sanitized. Fix: Audit all DOM-manipulation hooks for proper input validation and sanitization. Ensure no user input is directly inserted into innerHTML or similar dangerous APIs.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.