{"id":11724,"library":"react-immutable-pure-component","title":"React Immutable Pure Component","description":"This library provides `ImmutablePureComponent`, an enhanced React PureComponent specifically designed to work efficiently with Immutable.js data structures. It addresses the limitation of React's built-in `PureComponent` which doesn't fully leverage Immutable.js's structural sharing for shallow comparisons. The core mechanism involves `updateOnProps` and `updateOnStates` properties, allowing developers to explicitly define which specific props or state paths should trigger re-renders, using `Immutable.is` for deep equality checks on specified paths. The current stable version is 2.2.2. Releases have been somewhat sporadic, but updates address typings, dependency changes, and new features like `immutableMemo`. Its key differentiator is providing granular control over `Immutable.js`-aware re-rendering logic within a class component context, offering an alternative to `React.memo` with Immutable.js. It supports both class and functional components (via `immutableMemo`) and ships with TypeScript types.","status":"active","version":"2.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/Monar/react-immutable-pure-component","tags":["javascript","react","memo","immutable","pure","component","PureComponent","typescript"],"install":[{"cmd":"npm install react-immutable-pure-component","lang":"bash","label":"npm"},{"cmd":"yarn add react-immutable-pure-component","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-immutable-pure-component","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core functionality relies on Immutable.js for data structures and comparison (`Immutable.is`).","package":"immutable","optional":false},{"reason":"Provides the base `React.Component` and `React.memo` functionality.","package":"react","optional":false},{"reason":"Standard peer dependency for React libraries.","package":"react-dom","optional":false}],"imports":[{"note":"The primary named export for the class component. Since v2.0.1, the package is a regular common-js and es6 module.","wrong":"const ImmutablePureComponent = require('react-immutable-pure-component').ImmutablePureComponent;","symbol":"ImmutablePureComponent","correct":"import { ImmutablePureComponent } from 'react-immutable-pure-component';"},{"note":"Introduced in v2.2.0, `immutableMemo` is a named export for a functional component wrapper, similar to `React.memo` but with Immutable.js `is` comparison and `updateOnProps` functionality. Do not import as default.","wrong":"import immutableMemo from 'react-immutable-pure-component';","symbol":"immutableMemo","correct":"import { immutableMemo } from 'react-immutable-pure-component';"},{"note":"The class component `ImmutablePureComponent` is also exported as the default export for convenience. Both named and default imports are available for it.","wrong":"const ImmutablePureComponent = require('react-immutable-pure-component');","symbol":"Default Export (ImmutablePureComponent)","correct":"import ImmutablePureComponent from 'react-immutable-pure-component';"}],"quickstart":{"code":"import React, { useState, useCallback } from 'react';\nimport { ImmutablePureComponent, immutableMemo } from 'react-immutable-pure-component';\nimport { Map, List } from 'immutable';\n\n// A class component using ImmutablePureComponent\nclass MyClassComponent extends ImmutablePureComponent<{ data: Map, label: string }, { count: number }> {\n // Specify props to check for updates using Immutable.is\n updateOnProps = ['data'];\n // Specify state keys to check for updates\n updateOnStates = ['count'];\n\n constructor(props: any) {\n super(props);\n this.state = { count: 0 };\n }\n\n componentDidMount() {\n // Example: Update internal state after some time\n setTimeout(() => {\n this.setState({ count: 1 });\n }, 1000);\n }\n\n render() {\n console.log(`MyClassComponent (${this.props.label}) rendered`);\n return (\n
\n

Class Component: {this.props.label}

\n

Data Version: {this.props.data.get('version')}

\n

Internal Count: {this.state.count}

\n
\n );\n }\n}\n\n// A functional component using immutableMemo\ninterface MyFuncProps {\n items: List;\n onClick: (item: string) => void;\n}\n\nconst MyFunctionalComponent = immutableMemo(({ items, onClick }) => {\n console.log('MyFunctionalComponent rendered');\n return (\n
\n

Functional Component

\n
    \n {items.map((item, index) => (\n
  • onClick(item)}>{item}
    • \n ))}\n
\n
\n );\n}, ['items']); // 'items' array specifies props to compare with Immutable.is\n\nconst App = () => {\n const [data, setData] = useState(Map({ version: 1 }));\n const [items, setItems] = useState(List(['Apple', 'Banana']));\n\n const updateData = () => {\n // Only updates if the new Map is structurally different on specified keys\n setData(data => data.set('version', data.get('version') + 1));\n };\n\n const handleItemClick = useCallback((item: string) => {\n console.log(`Clicked: ${item}`);\n }, []);\n\n return (\n
\n

React Immutable Pure Component Demo

\n \n \n {/* This component will only re-render if 'data' specifically changes (version increments) */}\n\n \n {/* This component will only re-render if 'items' List changes structurally */}\n
\n );\n};\n\nexport default App;\n","lang":"typescript","description":"This quickstart demonstrates both `ImmutablePureComponent` (class-based) and `immutableMemo` (functional) to optimize React re-renders with Immutable.js data. It shows how to define `updateOnProps` and `updateOnStates` to control component updates based on Immutable.js structural equality."},"warnings":[{"fix":"Update your import statements to use ES modules (`import`) or CommonJS `require` depending on your build environment. Ensure your bundler is configured to handle modern module formats.","message":"Starting with v2.0.1, the package is no longer built as a UMD module. It is now distributed as standard CommonJS and ES6 modules. Direct browser script tag usage or older bundler configurations might break.","severity":"breaking","affected_versions":">=2.0.1"},{"fix":"If stuck on v2.0.1, either upgrade your `Immutable.js` dependency to version 4 or higher, or downgrade `react-immutable-pure-component` to a `v1.x` release.","message":"Version 2.0.1 temporarily increased the minimal required `Immutable.js` version to `>= 4` due to its internal use of `getIn`. If you were using `Immutable.js` versions below 4 with `react-immutable-pure-component@1`, upgrading directly to 2.0.1 would cause issues.","severity":"breaking","affected_versions":"2.0.1"},{"fix":"To safely use complex paths (arrays of keys) in `updateOnProps` or `updateOnStates`, ensure your `Immutable.js` version is `>= 4`. For simple string-based key checks, older Immutable.js versions are compatible with `react-immutable-pure-component` >= 2.1.0.","message":"With `react-immutable-pure-component@2.1.0` onwards, the restriction of `Immutable.js v4+` was relaxed for basic usage. If `updateOnProps` and `updateOnStates` only contain `string` values (representing top-level keys), `Immutable.js` versions below 4 will work. However, using non-string values (e.g., path arrays for nested access) with `Immutable.js < 4` will result in a `TypeError`.","severity":"gotcha","affected_versions":">=2.1.0"},{"fix":"Always provide an array of strings for `updateOnProps` and `updateOnStates` if you want to specify keys. Ensure each element in the array is a `string`. If you need nested path checking, upgrade to `Immutable.js v4+` and `react-immutable-pure-component v2.0.1+` and provide string paths, or be aware of the limitations if using older versions.","message":"The `updateOnProps` and `updateOnStates` properties expect an array of strings representing the keys to check for changes, or `undefined` to check all keys. Passing a non-array or non-string value (for individual elements in the array) for `Immutable.js` versions below 4 when using complex paths will cause runtime errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to `react-immutable-pure-component` v2.2.0 or newer to benefit from the revised internal implementation that removes `getIn` and its associated limitations.","message":"Prior to v2.2.0, the library internally used `Immutable.js`'s `getIn` method, which had a known issue (immutable-js/immutable-js#1688) related to `path` functionality. This could lead to unexpected behavior or incorrect comparisons for deeply nested paths.","severity":"gotcha","affected_versions":"2.0.1 - 2.1.x"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade your `Immutable.js` dependency to `v4` or higher, or downgrade `react-immutable-pure-component` to `v1.x`.","cause":"Using `react-immutable-pure-component@2.0.1` with `Immutable.js` versions prior to `v4.0.0-rc`.","error":"TypeError: Cannot read properties of undefined (reading 'getIn')"},{"fix":"Ensure all elements in `updateOnProps` and `updateOnStates` arrays are `string` values for top-level keys. If you require nested path comparison, upgrade both `Immutable.js` to `v4+` and `react-immutable-pure-component` to `v2.0.1+`.","cause":"Attempting to use non-string values (e.g., arrays for nested paths) in `updateOnProps` or `updateOnStates` with `Immutable.js` versions below 4.0.0.","error":"TypeError: path.map is not a function"},{"fix":"Verify your import statement (`import { ImmutablePureComponent } from 'react-immutable-pure-component';`) and ensure your bundler (Webpack, Rollup, etc.) is correctly configured to handle ES Modules or CommonJS. Check that the package is properly installed (`npm install react-immutable-pure-component`).","cause":"Incorrect import path or failure to resolve the module due to changes in packaging (from UMD to CJS/ESM).","error":"Module not found: Can't resolve 'react-immutable-pure-component'"}],"ecosystem":"npm"}