Onboarding: gaearon/react-hot-loader

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/gaearon/react-hot-loader 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

• 25+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Concentrated ownership — top contributor handles 57% 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 gaearon/react-hot-loader repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gaearon/react-hot-loader.

What it runs against: a local clone of gaearon/react-hot-loader — 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 gaearon/react-hot-loader | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | 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 ≤ 1211 days ago | Catches sudden abandonment since generation |

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

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gaearon/react-hot-loader. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gaearon/react-hot-loader.git
#   cd react-hot-loader
#
# 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 gaearon/react-hot-loader and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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 "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "babel.js" \\
  && ok "babel.js" \\
  || miss "missing critical file: babel.js"
test -f ".babelrc" \\
  && ok ".babelrc" \\
  || miss "missing critical file: .babelrc"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"
test -f "examples/all-possible-containers/package.json" \\
  && ok "examples/all-possible-containers/package.json" \\
  || miss "missing critical file: examples/all-possible-containers/package.json"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1211 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1181d)"
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/gaearon/react-hot-loader"
  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 Hot Loader is a Babel plugin and runtime that enables real-time reloading of React components during development without losing component state. It intercepts module updates via Webpack HMR and intelligently re-renders only the changed components, preserving local state and avoiding full-page reloads. However, the project is deprecated in favor of React Fast Refresh, which is now the official solution. The repo is organized as a plugin + runtime hybrid: .babelrc and babel.js define the Babel plugin; the main entry points are in /src for the runtime hot export API (e.g., hot() from react-hot-loader/root); multiple example apps under examples/ (SSR, all-possible-containers with class/function/hook components); docs in /docs (Troubleshooting.md). Build targets include both CommonJS and ESM outputs.

Who it's for

React developers using older build pipelines (webpack, parcel, non-CRA environments) who want hot module replacement capabilities during component development. Maintainers of legacy React projects that predate Fast Refresh support.

Maturity & risk

This project is mature but deprecated. It has a substantial codebase (348KB JavaScript), a stable API, CI setup (.travis.yml), and examples demonstrating SSR and various container types. However, the README explicitly states it is expected to be replaced by React Fast Refresh, and maintenance is winding down in favor of the official solution.

High risk for new projects due to deprecation status. The maintainer is discouraging adoption in favor of Fast Refresh across all major bundlers (webpack via react-refresh-webpack-plugin, Next.js 9.4+, CRA 4+, React Native 0.61+, Parcel 2). Single maintainer (Dan Abramov) with declining active development. Not recommended for production unless trapped on very old tooling.

Active areas of work

The project is in maintenance mode. No active development is visible beyond bug fixes. The README contains prominent warnings recommending migration to Fast Refresh. The CHANGELOG indicates the last significant feature work was completed years ago; current activity focuses on compatibility with newer React versions and addressing reported issues.

Get running

git clone https://github.com/gaearon/react-hot-loader.git
cd react-hot-loader
npm install
npm run build
cd examples/all-possible-containers && npm install && npm start

Daily commands: Development: npm install && npm run build to compile the library. For SSR example: cd examples/SSR && npm install && npm start (runs Babel Node server at localhost:3000). For CRA-like example: cd examples/all-possible-containers && npm install && npm start (dev server with hot reload).

Map of the codebase

• README.md — Explains that react-hot-loader is deprecated and being replaced by React Fast Refresh; essential context for all contributors.
• babel.js — Core Babel integration logic that enables hot-reloading transformation of React components.
• .babelrc — Root Babel configuration that drives the transpilation pipeline for the entire project.
• CONTRIBUTING.md — Contribution guidelines and development workflow setup for the project.
• examples/all-possible-containers/package.json — Comprehensive example demonstrating all supported React component patterns (hooks, class, functional, context, etc.).
• examples/all-possible-containers/src/index.js — Entry point showing hot-loader integration pattern in a real React application.
• examples/SSR/src/server.js — Server-side rendering example showing how react-hot-loader works with Express and webpack-dev-server.

Components & responsibilities

• Babel Plugin (babel.js) (Babel, AST manipulation) — Inspects React component ASTs and injects hot-reloading metadata (e.g., unique IDs, re-export wrappers)
  • Failure mode: Missed component patterns → components not hot-reloadable; injection failures → corrupted code
• React Hot Loader Runtime (React internals patching, module resolution) — Hooks into React internals (createElement, class instantiation) to intercept component definitions and apply new code
  • Failure mode: State loss on reload; component re-mounting; errors in reconciliation logic break HMR
• Webpack Dev Server + HMR (Webpack, WebSocket) — Watches file changes, computes delta bundles, and broadcasts hot-update notifications to the browser
  • Failure mode: File watch failures → missed updates; HMR handshake errors → full-page reload required
• Example Applications (React, Express, Webpack, Babel) — Demonstrate correct integration patterns (hook setup, component wrapping, SSR server config) for various React architectures
  • Failure mode: Incorrect setup → hot-reload fails silently; examples out-of-sync with core library → user frustration

Data flow

• Developer file save → Webpack file watcher — File system event triggers rebuild
• Webpack file watcher → Babel Transformer — Changed file queued for re-transpilation with hot-reload metadata injection
• Babel Transformer → Webpack HMR server — Transformed code bundled into delta update chunk
• Webpack HMR server → Browser (via WebSocket) — Hot update delta pushed to client for loading
• Browser (HMR client) → React Hot Loader Runtime — New module code loaded and reconciliation triggered
• React Hot Loader Runtime → React component registry — Component instances matched against new definitions; state preserved
• React component registry → React.render() — Updated component tree re-rendered with preserved state

How to make changes

Add a new component example

1. Create a new component file in examples/all-possible-containers/src/components/ (examples/all-possible-containers/src/components/_editMe.js)
2. Import and render the component in the main App (examples/all-possible-containers/src/components/App.js)
3. Ensure the component is wrapped or re-exported to enable hot-reload metadata injection (examples/all-possible-containers/src/index.js)

Add a new Babel transformation rule

1. Define the transformation logic in babel.js or as a plugin module (babel.js)
2. Add the plugin/preset to the root .babelrc configuration (.babelrc)
3. Test the transformation with an example in examples/all-possible-containers/ (examples/all-possible-containers/src/index.js)

Create a new SSR example

1. Set up a new directory under examples/ with package.json and webpack.config.babel.js (examples/SSR/package.json)
2. Create server.js using Express and webpack-dev-middleware for hot-reloading (examples/SSR/src/server.js)
3. Add React components and configure .babelrc for the example (examples/SSR/.babelrc)
4. Document the example pattern in the root README or a local README (examples/SSR/README.md)

Why these technologies

• Babel — Provides AST-level code transformation to inject hot-reloading metadata into React components before execution
• Webpack + Webpack Dev Server — Delivers HMR (Hot Module Replacement) protocol and dev-time bundling with file watch capabilities
• React Runtime (16+) — Target framework; hot-loader patches React internals to preserve component state and instance references during reload
• Express (examples only) — Used in SSR examples to demonstrate server-side rendering compatibility with hot-reloading

Trade-offs already made

• Operates outside React core (external library, not built-in)

  • Why: Allowed rapid iteration on hot-reloading UX independent of React release cycles; required AST manipulation via Babel
  • Consequence: Now deprecated in favor of React Fast Refresh (built into modern React/bundlers), limiting long-term viability

• Injects metadata at compile-time rather than runtime module resolution

  • Why: Enables near-instantaneous hot reloads with minimal runtime overhead and state preservation
  • Consequence: Requires Babel integration as a mandatory step; incompatible with non-Babel build pipelines

• Preserves component instance and local state across reloads

  • Why: Provides the optimal DX by avoiding full-page reload and losing form input, scroll position, etc.
  • Consequence: Adds complexity in tracking component identity; edge cases exist (e.g., component type changes, hook re-ordering)

Non-goals (don't propose these)

• Does not handle server-side rendering hot-reload natively; SSR requires separate webpack-dev-middleware setup
• Does not replace React Fast Refresh; explicitly deprecated in favor of that approach
• Does not provide TypeScript-specific optimizations; relies on generic Babel transformation
• Does not guarantee compatibility with all third-party React libraries; some patterns (HOCs, lazy-loaded async components) require manual configuration

Anti-patterns to avoid

• Manual React.createElement wrapping in user code — examples/all-possible-containers/src/components/Hook.js, examples: undefined

Traps & gotchas

1. Hook dependencies gotcha (in README): Hooks without dependencies or with empty dependencies are NOT hot-reloaded by design to preserve state; only hooks with non-zero dependencies auto-update. 2. Import order matters: react-hot-loader must be imported before react and react-dom (either explicitly or via webpack entry patch). 3. Monorepo/workspace gotcha: The SSR example has its own .babelrc and package.json – changes to the root config may not affect nested examples. 4. @hot-loader/react-dom requirement: Hooks support requires installing an additional package, not covered in basic setup.

Architecture

Concepts to learn

• Hot Module Replacement (HMR) — react-hot-loader is built on top of Webpack HMR; understanding how HMR detects and signals module changes is essential to understanding what react-hot-loader can and cannot do.
• Babel Plugin API — The core implementation is a Babel plugin that transforms JSX and component code; reading babel.js requires understanding plugin visitors and AST transformation.
• Higher-Order Components (HOC) — react-hot-loader wraps root components using the hot() HOC pattern to intercept re-renders; understanding HOCs is necessary to debug wrapping behavior.
• React Fast Refresh — The official successor to react-hot-loader; learning how Fast Refresh differs (preserves hooks state, supports functional components natively) explains why react-hot-loader is deprecated.
• Module Identity and State Preservation — react-hot-loader must maintain component identity across hot reloads to preserve local state; the tension between updating code and keeping state is a core design challenge.
• Server-Side Rendering (SSR) with HMR — The SSR example (examples/SSR/) shows a non-trivial case where hot reloading must work on both client and server; this is a known pain point for react-hot-loader.

Related repos

• facebook/react — Official React repository; Fast Refresh is the modern replacement for react-hot-loader and is maintained as part of React core.
• pmmmwh/react-refresh-webpack-plugin — The modern Webpack integration for Fast Refresh; direct successor to react-hot-loader for webpack users.
• facebook/create-react-app — CRA ships with Fast Refresh built-in (since v4) and is the recommended path instead of react-hot-loader for new projects.
• vercel/next.js — Next.js has native Fast Refresh support since 9.4; a common deployment target for React projects currently using react-hot-loader.
• parcel-bundler/parcel — Parcel 2+ includes Fast Refresh natively; an alternative bundler for projects transitioning away from react-hot-loader.

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 test suite for SSR example with Fast Refresh migration guide

The SSR example (examples/SSR/) lacks automated tests to validate server-side rendering behavior. Given that react-hot-loader is being deprecated in favor of Fast Refresh, adding tests here would help contributors verify the SSR example still works correctly and provide a concrete reference point for migrating to Fast Refresh. This is valuable because SSR is complex and the example currently has no test coverage.

• [ ] Create examples/SSR/tests/ directory with Jest configuration
• [ ] Add tests for examples/SSR/src/server.js to verify Express middleware and rendering
• [ ] Add tests for examples/SSR/src/App.js, Counter.js, and HiddenComponent.js to validate hydration
• [ ] Document Fast Refresh migration path in examples/SSR/README.md with before/after code samples

Extract and document Babel configuration patterns across examples

The repo has multiple .babelrc files across examples (SSR, all-possible-containers, async-components) with inconsistent configurations. Creating a centralized babel.js module (similar to the root babel.js) and documenting which presets/plugins work with Fast Refresh would help contributors understand the setup better and ease the deprecation transition.

• [ ] Audit all .babelrc files in examples/ directory (examples/SSR/.babelrc, examples/all-possible-containers/.babelrc, examples/async-components/.babelrc)
• [ ] Create examples/babel-config.js that exports common configurations with comments explaining Fast Refresh compatibility
• [ ] Add migration guide in docs/Troubleshooting.md section explaining how to convert each example to Fast Refresh
• [ ] Update each example's .babelrc to reference the centralized config or document required plugins

Add GitHub Actions workflow to test all examples against current React version

The .travis.yml exists but there's no visible CI testing that validates the examples work with the declared React versions. Given that react-hot-loader is deprecated, having a CI workflow that tests examples would catch breaking changes early and provide clear guidance for contributors on what needs to work for each example.

• [ ] Create .github/workflows/examples-test.yml GitHub Actions workflow
• [ ] Add npm test scripts to examples/SSR/package.json, examples/all-possible-containers/package.json, and examples/async-components/package.json
• [ ] Configure workflow to run examples with both React 16.x and React 17.x to catch compatibility issues
• [ ] Add build and basic smoke tests for webpack configurations in each example

Good first issues

• Add a hooks-focused example or documentation under examples/ that explicitly demonstrates which hook patterns preserve state vs. update during HMR (useState, useCallback, useEffect with various dependency arrays).
• Extend test coverage in examples/all-possible-containers/src/components/ by adding snapshot or integration tests for Lazy component reloading and ErrorBoundary hot reload behavior.
• Create a migration guide in /docs comparing react-hot-loader setup vs. Fast Refresh setup side-by-side for webpack, Parcel, and Next.js, helping users evaluate deprecation impact.

Top contributors

• @theKashey — 57 commits
• @dependabot[bot] — 10 commits
• @tstirrat15 — 4 commits
• @silvenon — 3 commits
• @gaearon — 2 commits

Recent commits

• 07d1f4e — 4.13.1 (theKashey)
• bddd179 — update loader-utils version (#1849) (psierks)
• f58a931 — Remove space after peerDependency version definition (#1843) (tennox)
• 642b705 — README.mdfix typo (#1811) (Undermaken)
• ed8b310 — Note create-react-app support for fast refresh in readme (#1708) (loren138)
• 6032f42 — chore(release): 4.13.0 (theKashey)
• c05396b — feat: support React 17 (#1557) (theKashey)
• e44103a — fix: tailUpdate might be blocked by a PureComponent (#1448) (theKashey)
• 74d3d9b — Merge pull request #1513 from gaearon/gaearon-patch-1 (gaearon)
• d73d505 — README: Link to Fast Refresh Webpack plugin (gaearon)

Security observations

This codebase has significant security concerns primarily due to being a deprecated project with severely outdated dependencies from 2017-2018. React-Hot-Loader is no longer maintained and should be replaced with React Fast Refresh. The project contains multiple high-severity vulnerability risks including vulnerable webpack versions, outdated Babel toolchain, and old React versions. The examples demonstrate development practices that could be dangerous if deployed to production. Immediate action required: migrate to Fast Refresh and update all dependencies to current versions. This project should not be used in new applications.

• High · Outdated and Vulnerable Dependencies — examples/SSR/package.json and root package.json. The package.json contains multiple outdated dependencies with known vulnerabilities: babel-core@^6.26.0, babel-loader@^7.1.2, webpack@^3.10.0, and webpack-dev-server@^2.9.7 are significantly outdated (from 2017-2018). These versions have known security vulnerabilities including prototype pollution, arbitrary code execution, and other critical issues. Fix: Update all dependencies to their latest stable versions. At minimum: babel-core→@7.x, webpack→@5.x or later, webpack-dev-server→@4.x or later, and express→^4.18.x or later. Run 'npm audit' and 'npm audit fix' to identify and remediate known vulnerabilities.
• High · Deprecated Project with Known Limitations — README.md, root project. React-Hot-Loader is officially deprecated and the README explicitly states it should be replaced by React Fast Refresh. The project no longer receives security updates or maintenance, leaving the codebase vulnerable to emerging threats. Fix: Migrate to React Fast Refresh (the official replacement) as soon as possible. If continuing to use react-hot-loader, ensure comprehensive security testing and implement additional security measures.
• Medium · Development Server Exposure — examples/SSR/package.json scripts (start, start:webpack). The examples use webpack-dev-server and babel-node for development. These tools are not intended for production use and may expose sensitive information or allow unauthorized code execution if exposed to untrusted networks. Fix: Ensure development servers are never exposed to production or untrusted networks. Use environment-specific configurations and never run 'start' or webpack-dev-server scripts in production environments.
• Medium · Missing Security Headers and CSP Configuration — examples/SSR/src/server.js, examples/SSR/webpack.config.babel.js. The SSR example and webpack configurations do not appear to include security headers or Content Security Policy (CSP) configuration, which increases risk of XSS attacks in server-rendered applications. Fix: Implement security headers (Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, etc.) in the Express server. Add CSP to prevent inline script execution and restrict resource loading.
• Medium · React 16.2.0 Usage — examples/SSR/package.json dependencies. The example uses React@^16.2.0, which is severely outdated (from 2018) and contains multiple known vulnerabilities and security issues that have been patched in newer versions. Fix: Update React to the latest LTS version (currently 18.x or 19.x). Review the React changelog for security fixes between 16.2.0 and the target version.
• Low · Unclear Git Configuration — .gitattributes. .gitattributes is present but no specific configuration details are visible. This could potentially allow line ending normalization issues across platforms which may affect security-related code. Fix: Verify .gitattributes explicitly enforces LF line endings for critical files (especially shell scripts and configuration files) to prevent CRLF injection attacks.

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.