React-Rx: Hooks and Utilities for RxJS Integration

Common errors

• Error: Can't resolve 'rxjs' in 'your-project/node_modules/react-rx'

  cause The `rxjs` peer dependency is missing or an incompatible version is installed.
  fix Install `rxjs` explicitly: `npm install rxjs@^7` or `yarn add rxjs@^7`.

• TypeError: (0, _react_rx.useObservable) is not a function

  cause This usually indicates a CommonJS (`require`) attempt to load an ES Module (`react-rx`) or a bundler misconfiguration in an older project.
  fix Verify that your project and bundler (e.g., Webpack, Rollup) are configured to handle ES Modules (`import` statements). Ensure your `package.json` has `"type": "module"` if it's an ESM project, and use `import { useObservable } from 'react-rx';`.

• React Hook 'useObservable' cannot be called inside a class component. React Hooks can only be called from a function component or custom Hook.

  cause `useObservable` is a React Hook and adheres to React's Rules of Hooks.
  fix Convert your component to a functional component or refactor the logic to be used within a custom hook, or consider using `reactiveComponent` for class-like reactive patterns if a class component is strictly required.

Warnings

• breaking Older versions of `react-rx` (prior to v3) might have supported CommonJS (`require()`) imports. Since v3, the library is primarily designed for ES Modules, requiring `import` statements. Attempting to `require()` this package in a pure ESM context or misconfigured bundler can lead to runtime errors.
  Fix: Ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json`, `moduleResolution: "NodeNext"` in `tsconfig.json`) and use `import` syntax for `react-rx` and `rxjs`.
• gotcha Mixing `useObservable` hooks and `reactiveComponent` within the same React component is not recommended due to their fundamentally different programming styles and underlying implementations. Choose one paradigm for consistency and clarity.
  Fix: Decide on either a hook-based approach with `useObservable` for functional components or a higher-order component approach with `reactiveComponent`, and adhere to that style within a given component.
• gotcha Incorrect peer dependency versions for `react` or `rxjs` can lead to runtime issues or unexpected behavior. `react-rx` relies heavily on specific versions of these libraries.
  Fix: Ensure your project's `react` and `rxjs` versions match the peer dependency requirements: `rxjs: "^7"` and `react: "^18.3 || >=19.0.0-0"`. Use `npm install` or `yarn install` to resolve peer dependency warnings.
• gotcha When `useObservable` is provided with an `initialValue` and the observable emits synchronously at subscription time, the synchronously emitted value will be used, ignoring the `initialValue`. This can be unexpected if not aware of RxJS's synchronous emission capabilities.
  Fix: Be mindful of observables that emit synchronously (e.g., `of()`, `new BehaviorSubject()`). If you always want an initial placeholder, consider delaying the observable's first emission or ensuring it is truly asynchronous, or explicitly handle the initial synchronous emission.

Install

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

Imports

• useObservable
  wrong:

  const useObservable = require('react-rx').useObservable;

  correct:

  import { useObservable } from 'react-rx';

  The primary hook for consuming observables in functional components. Requires ESM imports since v3.
• useObservableCallback
  wrong:

  import useObservableCallback from 'react-rx/useObservableCallback';

  correct:

  import { useObservableCallback } from 'react-rx';

  A utility hook for creating an Observable from React callbacks. Used for event streams.
• reactiveComponent
  wrong:

  import reactiveComponent from 'react-rx/reactiveComponent';

  correct:

  import { reactiveComponent } from 'react-rx';

  A higher-order component (HOC) utility for creating reactive components. Not intended to be mixed with `useObservable` hooks in the same component.
• Observable
  wrong:

  import { Observable } from 'react-rx';

  correct:

  import { Observable } from 'rxjs';

  Observable is part of RxJS, not `react-rx`. Always import directly from 'rxjs'.

Quickstart

This quickstart demonstrates how to use the `useObservable` hook to subscribe to an RxJS `interval` observable and display its emitted values in a React functional component. It showcases two independent counters.

import React, { useMemo } from 'react';
import { useObservable } from 'react-rx';
import { interval, map, take } from 'rxjs';

interface CounterProps {
  startAt: number;
  intervalMs: number;
}

function ObservableCounter({ startAt, intervalMs }: CounterProps) {
  const counterObservable = useMemo(
    () => interval(intervalMs).pipe(
      map(i => startAt + i),
      take(10) // Stop after 10 emissions to prevent infinite updates
    ),
    [startAt, intervalMs]
  );

  const count = useObservable(counterObservable, startAt); // Initial value

  return (
    <div>
      <h2>Observable Counter</h2>
      <p>Current count: {count}</p>
      <p>Will count from {startAt} every {intervalMs}ms for 10 times.</p>
    </div>
  );
}

export default function App() {
  return (
    <div>
      <h1>React-Rx Demonstration</h1>
      <ObservableCounter startAt={0} intervalMs={1000} />
      <ObservableCounter startAt={100} intervalMs={500} />
    </div>
  );
}