Why Did You Render rewires JSX through your Babel config, not your code
why-did-you-render by Welldone Software monkey patches React to notify you about potentially avoidable re-renders. (Works with React Native as well.)
At a glance
- What is it?
- why-did-you-render is a development-only monkey patch on React, and nearly all of its friction comes from how it has to enter your app: as the JSX import source, wired through one of three different Babel shapes, in a file imported before anything else.
- Who is it for?
- Why Did You Render earns its place on a React 19 application where you suspect a specific heavy component is re-rendering for a reason you can name. It is the wrong tool if your build runs the React Compiler, if you cannot change your Babel configuration, or if you want a production-safe measurement.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Activity is slowing. The repository last received commits 7 months ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- welldone-software/why-did-you-render12,534 ★ · +8
| Repository | 2026-09-22 | 2026-11-15 |
|---|---|---|
| welldone-software/why-did-you-render | 12.5k | 12.5k |
8 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The patch replaces React internals, which is why it must never ship
why-did-you-render is not a profiler attached to your build. It takes the React module as an argument and patches it at runtime so component updates can report why they happened. That is why the package has to enter through the compiler as the JSX import source rather than as an ordinary wrapper component, and why the README insists the entry file is imported first. The patch is invasive by design, and the project states the cost without hedging. Two warnings say the library should never be used in production: it significantly slows down React, and monkey patching React can result in unexpected behavior.
Both failures follow from the mechanism rather than from how you configure it. A setup that leaves the patch active in a shipped bundle gives you both problems at once, and the guard shown in the setup is the environment check inside the entry file itself, so verifying that your production build is clean is your job.
One requirement splits into three different Babel shapes
React 19 requires the automatic JSX transformation, so the library has to arrive through the compiler rather than through a hand written import. That single requirement fans out into three configurations, because there are three build setups to satisfy. With @babel/preset-react you pass runtime, development, and importSource as a single options array. With the bare React Native workflow you nest the same options inside an env.development block on top of module:metro-react-native-babel-preset, where the default babel env is development. With Expo managed you never touch Babel plugins directly and instead hand jsxImportSource to babel-preset-expo from a babel.config.js.
['@babel/preset-react', {
runtime: 'automatic',
development: process.env.NODE_ENV === 'development',
importSource: '@welldone-software/why-did-you-render',
}]Create React App at ^4 gets called out separately because it already uses the automatic transformation, with a link to a discussion explaining how to complete the step. When a build produces no output at all, the README sends you to a troubleshooting section and to the issue tracker.
The entry file has to win the import race, even against react-hot-loader
Ordering is part of the contract. The entry file is imported first in your application, and the README is specific that this means before react-hot-loader if you use it, which is why the sample places the wdyr import on its own line above the hot loader and above React itself. Import it later and the components it needs to observe are already rendered.
import React from 'react';
if (process.env.NODE_ENV === 'development') {
const whyDidYouRender = require('@welldone-software/why-did-you-render');
whyDidYouRender(React, {
trackAllPureComponents: true,
});
}TypeScript users rename the file to wdyr.ts and add one triple slash line to pull in the package types. The guard above keys off process.env.NODE_ENV, and for React Native the README suggests swapping that for the __DEV__ flag instead, since that is the dependable signal on that platform. Get the check wrong for your bundler and the slowdown you were warned about applies in every build, including the ones you ship.
React Compiler support was never tested, and the version matrix is split by branch
The support matrix is narrow and presented as fact rather than plan. The latest version was tested with unit tests and E2E against React 19 only. React 18 users are sent to the readme on the version-8 branch, and React 17 and 16 users to the readme on the version-7 branch. The configuration steps that work for you therefore depend on which major line your application is on, and the current instructions are not automatically the right ones.
On top of that sits a caution that the library was not tested with React Compiler at all, with the author's own assessment that it is completely incompatible. The consequence is concrete: if your application enables the compiler, this tool reports nothing trustworthy about what the compiler is doing to your renders. You would be reading output from a React runtime the README already tells you it does not understand.
Hook tracking is passed as module and name, and webpack can break it
Custom hooks are opt in through trackExtraHooks, and the value is a pair of a module and an export name rather than a function reference. The React Redux example shows the full shape:
import React from 'react';
// For react-native you might want to use
// the __DEV__ flag instead of process.env.NODE_ENV === 'development'
if (process.env.NODE_ENV === 'development') {
const whyDidYouRender = require('@welldone-software/why-did-you-render');
const ReactRedux = require('react-redux');
whyDidYouRender(React, {
trackAllPureComponents: true,
trackExtraHooks: [
[ReactRedux, 'useSelector']
]
});
}The mechanism has a known failure mode stated outright: rewriting exports of imported files in webpack interferes with it, and the offered answer is the workaround in issue 85 rather than a fix in the library. So on a webpack project hook tracking can break because of bundler behavior you do not control. That matters most in hook heavy code, which is exactly where you would want visibility, so you may end up falling back to the React DevTools Profiler the README recommends for measuring effects.
The published package is older than the repository, and the bump is scripted
The npm artifact and the repository sit at different points in time. The version field in package.json reads 10.0.1, the React 19 release landed as 10.0.0 on the same day in January 2025, and the version before that, 8.0.3, dates from June 2024. The most recent push on the master branch is 2026-04-15, so there is repository activity well after the last published release, and you cannot assume the code on master is what npm handed you.
The release path is scripted rather than manual. Bumping the version runs a health check first and pushes the tags afterwards:
"version": "yarn checkHealth",
"postversion": "git push && git push --tags",That health check chains the production rollup build, eslint with zero allowed warnings, jest, and the Cypress run against a demo server on port 3003. The documented bump command is npm version major/minor/patch. The package ships dist, types.d.ts, and separate jsx-runtime and jsx-dev-runtime entry files, which matches the importSource wiring but also means the package carries its own runtime shims.
Tracking everything is a choice with a measured downside
The README argues against its own broadest setting before it explains it. Not every re-render is a problem: reducing re-renders for its own sake can hurt performance or make no measurable difference, in which case the effort is wasted and the code ends up more complicated than it started. The advice attached to that warning is to focus on heavier components and measure changes with the React DevTools Profiler rather than trusting a log line.
Tracking breadth is a dial. trackAllPureComponents turns on tracking for every React.PureComponent and React.memo in the tree, which covers the whole application at once. Otherwise you set whyDidYouRender = true on individual ad hoc components. The README's production warning already states that the library significantly slows down React. A tool that slows the runtime you are trying to speed up needs measurement before you adopt it wholesale, and the profiler, not the log, is what tells you whether a given fix paid for itself.
Editorial conclusion
Why Did You Render earns its place on a React 19 application where you suspect a specific heavy component is re-rendering for a reason you can name. It is the wrong tool if your build runs the React Compiler, if you cannot change your Babel configuration, or if you want a production-safe measurement. Before installing it, confirm which React major line you are on, because the setup steps for React 18 and for React 17 and 16 live on separate branches, and check whether webpack rewriting of module exports blocks the hook tracking you were counting on.
Frequently asked questions
how to use why did you render
Install it as a dev dependency, set it as React's importSource with @babel/preset-react in development mode, then create a wdyr file that requires the package and call it with the React module. Import that file as the very first import in your application, before react-hot-loader if you use it.
Which React versions does why-did-you-render support?
The latest version was tested with React 19 only, using both unit tests and E2E. React 18 users are pointed to the version-8 branch readme, and React 17 and 16 users to the version-7 branch readme.
Can I use why-did-you-render in production?
No. The README states the library should never be used in production because it significantly slows down React and because monkey patching React can result in unexpected behavior.
Does why-did-you-render work with the React Compiler?
The library was not tested with React Compiler at all, and the author's read is that it is completely incompatible.
How do I track just one component with why-did-you-render?
Leave trackAllPureComponents off and set whyDidYouRender = true on the ad hoc component you care about. Turning that option on instead tracks every pure component built with React.PureComponent or React.memo.
How do I track a custom hook with why-did-you-render?
Pass trackExtraHooks with a pair of the module and the hook export name, for example the react-redux module paired with useSelector. The README notes a known problem with webpack rewriting exports of imported files and links a workaround discussion.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/welldone-software-why-did-you-render)Star history chart for your README
[](https://hysenlabs.com/projects/welldone-software-why-did-you-render)Was this useful?