Effector React Bindings

Common errors

• Error: Invalid hook call. Hooks can only be called inside of the body of a function component.

  cause Attempting to call an `effector-react` hook (like `useUnit`, `useStore`, `createGate`) outside of a React functional component or a custom hook.
  fix Ensure `effector-react` hooks are only invoked within the render function of a React functional component or at the top level of another custom hook. Check for conditional hook calls or calls within regular JavaScript functions.

• Unhandled Rejection (TypeError): Cannot read properties of undefined (reading 'sid')

  cause This error often indicates an issue with Effector units losing their identity or being incorrectly passed, frequently seen with old CommonJS `require()` imports or issues with the Babel/SWC plugin's SID generation.
  fix Verify that you are using ES module imports (`import ... from '...'`) throughout your Effector codebase. Ensure the `@effector/babel-plugin` (or SWC equivalent) is correctly installed and configured in your build setup, especially if using HMR or hot reloading. Update to the latest `effector` and `effector-react` versions.

• TypeError: (0 , effector_react__WEBPACK_IMPORTED_MODULE_1__.useUnit) is not a function

  cause This typically means `useUnit` was not correctly imported or the module resolution failed. This can happen with incorrect build configurations, version mismatches, or CJS/ESM interop issues.
  fix Check your import statement: `import { useUnit } from 'effector-react'`. Confirm `effector-react` is correctly installed. Ensure your build tool (Webpack, Babel, etc.) is configured to handle ES Modules from `node_modules` correctly, especially if you have custom aliases or transformations.

Warnings

• breaking Older CommonJS `require()` imports are no longer officially supported for `effector` and its ecosystem, including `effector-react`, in recent major versions. Modern applications should use ES module `import` syntax.
  Fix: Migrate your project to use ES modules (`import ... from '...'`) and configure your build system (Webpack, Rollup, Vite, etc.) to handle them correctly. Ensure your `package.json` has `"type": "module"` or uses `.mjs` extensions for ESM files.
• gotcha Effector's core library (and by extension `effector-react`) relies heavily on a Babel/SWC plugin for optimal development experience, including Hot Module Replacement (HMR), improved error messages, and better debugging. Without it, some advanced features or ergonomics might be limited.
  Fix: Install `@effector/babel-plugin` (or the equivalent SWC plugin) and configure it in your project's `babel.config.js` or `swc-config` file. Refer to the official Effector documentation for detailed setup instructions.
• gotcha Ensure `react` and `effector` peer dependency versions are compatible. `effector-react` 23.3.0 specifically requires `react` `>=16.8.0 <20.0.0` and `effector` `^23.0.0`. Mismatched versions can lead to runtime errors or unexpected behavior.
  Fix: Verify your `package.json` for `react` and `effector` and ensure they fall within the specified peer dependency ranges. Use `npm install` or `yarn add` to adjust versions if necessary. `npm ls react effector` can help diagnose issues.
• deprecated The `useStore` hook is largely superseded by `useUnit` for consuming effector units. While still functional for single stores, `useUnit` offers a more powerful and flexible API for combining multiple units and actions.
  Fix: Prefer `useUnit` when consuming effector stores, events, or effects. For example, instead of `const value = useStore($store);`, consider `const { value } = useUnit({ value: $store });`.

Install

• npm install effector-react npm
• yarn add effector-react yarn
• pnpm add effector-react pnpm

Imports

• useUnit
  wrong:

  const useUnit = require('effector-react')

  correct:

  import { useUnit } from 'effector-react'

  Primary hook for consuming effector units (stores, events, effects) in functional components. ESM-only in modern Effector versions.
• createGate
  wrong:

  const createGate = require('effector-react')

  correct:

  import { createGate } from 'effector-react'

  Creates a 'Gate' unit for managing component lifecycle and props, useful for server-side rendering or complex component interactions.
• useStore
  wrong:

  import useStore from 'effector-react'

  correct:

  import { useStore } from 'effector-react'

  Deprecated in favor of `useUnit` for most cases, but still available for consuming single stores directly. It is a named export, not default.

Quickstart

Demonstrates how to create an Effector store and event, then consume them in a React functional component using the `useUnit` hook to manage form input state and display its length.

import { createStore, createEvent } from 'effector';
import { useUnit } from 'effector-react';
import React from 'react'; // Assuming React is imported for JSX

const inputText = createEvent<string>();

const $text = createStore<string>('').on(inputText, (_, text) => text);

const $size = $text.map(text => text.length);

const Form = () => {
  const { text, size } = useUnit({
    text: $text,
    size: $size,
  });
  const handleTextChange = useUnit(inputText);

  return (
    <form>
      <label htmlFor="text-input">Enter text:</label>
      <input
        id="text-input"
        type="text"
        onChange={e => handleTextChange(e.currentTarget.value)}
        value={text}
        aria-label="Text input for form"
      />
      <p>Length: {size}</p>
    </form>
  );
};

// To render this component (e.g., in App.js or index.js):
// import ReactDOM from 'react-dom/client';
// const root = ReactDOM.createRoot(document.getElementById('root'));
// root.render(<Form />);