why-did-you-render

Because React 19 requires the automatic JSX transformation, you must set why-did-you-render as the importSource in your Babel configuration. Ensure @babel/preset-react is set to development mode.

['@babel/preset-react', {
  runtime: 'automatic',
  development: process.env.NODE_ENV === 'development',
  importSource: '@welldone-software/why-did-you-render',
}]

Install the library as a development dependency to avoid including it in your production bundle.

Note: This version is tested with React 19. For React 18, use version ^8. For React 17 and 16, use version ^7.

npm install @welldone-software/why-did-you-render --save-dev
# or
yarn add @welldone-software/why-did-you-render -D

In Expo managed projects, pass the jsxImportSource parameter through babel-preset-expo in your babel.config.js.

// babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: [
      [
        "babel-preset-expo",
        {
          jsxImportSource: "@welldone-software/why-did-you-render",
        },
      ],
    ],
  };
};

You can track specific components using the whyDidYouRender property.

1. All Pure Components: Enable trackAllPureComponents: true in the main config to track all React.PureComponent or React.memo components.
2. Ad-hoc tracking: Set Component.whyDidYouRender = true for specific components.
3. Advanced tracking: Pass an object to whyDidYouRender to configure specific behaviors like custom names or logging on different values.

// Class Component
class BigList extends React.Component {
  static whyDidYouRender = true
  render() { /* ... */ }
}

// Functional Component
const BigListPureComponent = props => <div />;
BigListPureComponent.whyDidYouRender = true;

// Advanced Configuration
EnhancedMenu.whyDidYouRender = {
  logOnDifferentValues: true,
  customName: 'Menu'
}

For React Native projects not using Expo, add the plugin to your Babel configuration within the development environment block.

module.exports = {
  presets: ['module:metro-react-native-babel-preset'],

  env: {
    development: {
      plugins: [['@babel/plugin-transform-react-jsx', {
        runtime: 'automatic',
        development: process.env.NODE_ENV === 'development',
        importSource: '@welldone-software/why-did-you-render',
      }]],
    },
  },
}

Create a wdyr.js (or wdyr.ts) file and import it as the very first import in your application entry point (e.g., index.js).

For TypeScript users: Add /// <reference types="@welldone-software/why-did-you-render" /> to the top of your wdyr.ts file to enable type support.

Caution: Never use this library in production as it significantly slows down React and monkey patches the core library.

// wdyr.js
import React from 'react';

if (process.env.NODE_ENV === 'development') {
  const whyDidYouRender = require('@welldone-software/why-did-you-render');
  whyDidYouRender(React, {
    trackAllPureComponents: true,
  });
}

// index.js
import './wdyr'; // <--- MUST BE FIRST
import React from 'react';
import ReactDOM from 'react-dom';
// ...

Because connect hoists statics, adding whyDidYouRender = true to an inner component also adds it to the HOC component where complex hooks run, causing noise.

Solution: Add the whyDidYouRender = true static property to the component after it has been wrapped by connect.

const SimpleComponent = ({a}) => <div data-testid="foo">{a.b}</div>

// Do NOT do this before connect:
// SimpleComponent.whyDidYouRender = true

const ConnectedSimpleComponent = connect(
  state => ({a: state.a})
)(SimpleComponent)

// DO this after connect:
SimpleComponent.whyDidYouRender = true

If you don't see any logs, check the following:

1. Production Environment: WDYR is likely disabled in production builds.
2. Component Tracking: Ensure components are actually being tracked. If you only use trackAllPureComponents: true, ensure your components are actually React.memo or React.PureComponent.
3. Manual Test: To force an issue and verify WDYR is working, try rendering your app twice in your entry point:

const HotApp = hot(App);
HotApp.whyDidYouRender = true;
ReactDOM.render(<HotApp/>, document.getElementById('root'));
ReactDOM.render(<HotApp/>, document.getElementById('root'));

To track custom hooks that are not part of the standard React library, use the trackExtraHooks option. This option accepts an array of arrays, where each inner array contains the module object and the string name of the exported hook.

Note: This feature works by rewriting exports of imported files. If you are using Webpack, you may encounter issues where trackExtraHooks cannot set properties. See Issue #85 for workarounds.

whyDidYouRender(React, {
  trackExtraHooks: [
    // notice that 'useSelector' is a named export
    [ReactRedux, 'useSelector'],
  ]
});

You can track specific hooks from external libraries (like useSelector from react-redux) by passing them to the trackExtraHooks option during initialization. The option accepts an array of [library, hookName] pairs.

import React from 'react';

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']
    ]
  });
}