create-subscription

create-subscription

create-subscription is a utility for subscribing to external data sources inside React components. It is officially supported and maintained by the React team.

When should you NOT use this?

This utility should be used for subscriptions to a single value that are typically only read in one place and may update frequently (e.g. a component that subscribes to a geolocation API to show a dot on a map).

Other cases have better long-term solutions:

• Redux/Flux stores should use the context API instead.
• I/O subscriptions (e.g. notifications) that update infrequently should use react-cache instead.
• Complex libraries like Relay/Apollo should manage subscriptions manually with the same techniques which this library uses under the hood (as referenced here) in a way that is most optimized for their library usage.

Limitations in async mode

The main motivation for create-subscription is to provide a way for library authors to ensure compatibility with React's upcoming asynchronous rendering mode. create-subscription guarantees correctness in async mode, accounting for the subtle bugs and edge cases that a library author might otherwise miss.

However, it achieves correctness by sometimes de-opting to synchronous mode, obviating the benefits of async rendering. This is an inherent limitation of storing state outside of React's managed state queue and rendering in response to a change event.

The effect of de-opting to sync mode is that the main thread may periodically be blocked (in the case of CPU-bound work), and placeholders may appear earlier than desired (in the case of IO-bound work).

For full compatibility with asynchronous rendering, including both time-slicing and React Suspense, the suggested longer-term solution is to move to one of the patterns described in the previous section.

What types of subscriptions can this support?

This abstraction can handle a variety of subscription types, including:

• Event dispatchers like HTMLInputElement.
• Custom pub/sub components like Relay's FragmentSpecResolver.
• Observable types like RxJS BehaviorSubject and ReplaySubject. (Types like RxJS Subject or Observable are not supported, because they provide no way to read the "current" value after it has been emitted.)
• Native Promises.

Installation

# Yarn
yarn add create-subscription

# NPM
npm install create-subscription

Usage

To configure a subscription, you must provide two methods: getCurrentValue and subscribe.

import { createSubscription } from "create-subscription";

const Subscription = createSubscription({
  getCurrentValue(source) {
    // Return the current value of the subscription (source),
    // or `undefined` if the value can't be read synchronously (e.g. native Promises).
  },
  subscribe(source, callback) {
    // Subscribe (e.g. add an event listener) to the subscription (source).
    // Call callback(newValue) whenever a subscription changes.
    // Return an unsubscribe method,
    // Or a no-op if unsubscribe is not supported (e.g. native Promises).
  }
});

To use the Subscription component, pass the subscribable property (e.g. an event dispatcher, observable) as the source property and use a render prop, children, to handle the subscribed value when it changes:

<Subscription source={eventDispatcher}>
  {value => <AnotherComponent value={value} />}
</Subscription>

Examples

This API can be used to subscribe to a variety of "subscribable" sources, from event dispatchers to RxJS observables. Below are a few examples of how to subscribe to common types.

Subscribing to event dispatchers

Below is an example showing how create-subscription can be used to subscribe to event dispatchers such as DOM elements.

import React from "react";
import { createSubscription } from "create-subscription";

// Start with a simple component.
// In this case, it's a function component, but it could have been a class.
function FollowerComponent({ followersCount }) {
  return <div>You have {followersCount} followers!</div>;
}

// Create a wrapper component to manage the subscription.
const EventHandlerSubscription = createSubscription({
  getCurrentValue: eventDispatcher => eventDispatcher.value,
  subscribe: (eventDispatcher, callback) => {
    const onChange = event => callback(eventDispatcher.value);
    eventDispatcher.addEventListener("change", onChange);
    return () => eventDispatcher.removeEventListener("change", onChange);
  }
});

// Your component can now be used as shown below.
// In this example, 'eventDispatcher' represents a generic event dispatcher.
<EventHandlerSubscription source={eventDispatcher}>
  {value => <FollowerComponent followersCount={value} />}
</EventHandlerSubscription>;

Subscribing to observables

Below are examples showing how create-subscription can be used to subscribe to certain types of observables (e.g. RxJS BehaviorSubject and ReplaySubject).

Note that it is not possible to support all observable types (e.g. RxJS Subject or Observable) because some provide no way to read the "current" value after it has been emitted.

BehaviorSubject

const BehaviorSubscription = createSubscription({
  getCurrentValue: behaviorSubject => behaviorSubject.getValue(),
  subscribe: (behaviorSubject, callback) => {
    const subscription = behaviorSubject.subscribe(callback);
    return () => subscription.unsubscribe();
  }
});

ReplaySubject

const ReplaySubscription = createSubscription({
  getCurrentValue: replaySubject => {
    let currentValue;
    // ReplaySubject does not have a sync data getter,
    // So we need to temporarily subscribe to retrieve the most recent value.
    replaySubject
      .subscribe(value => {
        currentValue = value;
      })
      .unsubscribe();
    return currentValue;
  },
  subscribe: (replaySubject, callback) => {
    const subscription = replaySubject.subscribe(callback);
    return () => subscription.unsubscribe();
  }
});

Subscribing to a Promise

Below is an example showing how create-subscription can be used with native Promises.

Note that an initial render value of undefined is unavoidable due to the fact that Promises provide no way to synchronously read their current value.

Note the lack of a way to "unsubscribe" from a Promise can result in memory leaks as long as something has a reference to the Promise. This should be taken into consideration when determining whether Promises are appropriate to use in this way within your application.

import React from "react";
import { createSubscription } from "create-subscription";

// Start with a simple component.
function LoadingComponent({ loadingStatus }) {
  if (loadingStatus === undefined) {
    // Loading
  } else if (loadingStatus === null) {
    // Error
  } else {
    // Success
  }
}

// Wrap the function component with a subscriber HOC.
// This HOC will manage subscriptions and pass values to the decorated component.
// It will add and remove subscriptions in an async-safe way when props change.
const PromiseSubscription = createSubscription({
  getCurrentValue: promise => {
    // There is no way to synchronously read a Promise's value,
    // So this method should return undefined.
    return undefined;
  },
  subscribe: (promise, callback) => {
    promise.then(
      // Success
      value => callback(value),
      // Failure
      () => callback(null)
    );

    // There is no way to "unsubscribe" from a Promise.
    // create-subscription will still prevent stale values from rendering.
    return () => {};
  }
});

// Your component can now be used as shown below.
<PromiseSubscription source={loadingPromise}>
  {loadingStatus => <LoadingComponent loadingStatus={loadingStatus} />}
</PromiseSubscription>

Changelog

18.0.0 (March 29, 2022)

Below is a list of all new features, APIs, deprecations, and breaking changes. Read React 18 release post and React 18 upgrade guide for more information.

New Features

React

• useId is a new hook for generating unique IDs on both the client and server, while avoiding hydration mismatches. It is primarily useful for component libraries integrating with accessibility APIs that require unique IDs. This solves an issue that already exists in React 17 and below, but it’s even more important in React 18 because of how the new streaming server renderer delivers HTML out-of-order.
• startTransition and useTransition let you mark some state updates as not urgent. Other state updates are considered urgent by default. React will allow urgent state updates (for example, updating a text input) to interrupt non-urgent state updates (for example, rendering a list of search results).
• useDeferredValue lets you defer re-rendering a non-urgent part of the tree. It is similar to debouncing, but has a few advantages compared to it. There is no fixed time delay, so React will attempt the deferred render right after the first render is reflected on the screen. The deferred render is interruptible and doesn't block user input.
• useSyncExternalStore is a new hook that allows external stores to support concurrent reads by forcing updates to the store to be synchronous. It removes the need for useEffect when implementing subscriptions to external data sources, and is recommended for any library that integrates with state external to React.
• useInsertionEffect is a new hook that allows CSS-in-JS libraries to address performance issues of injecting styles in render. Unless you’ve already built a CSS-in-JS library we don’t expect you to ever use this. This hook will run after the DOM is mutated, but before layout effects read the new layout. This solves an issue that already exists in React 17 and below, but is even more important in React 18 because React yields to the browser during concurrent rendering, giving it a chance to recalculate layout.

React DOM Client

These new APIs are now exported from react-dom/client:

• createRoot: New method to create a root to render or unmount. Use it instead of ReactDOM.render. New features in React 18 don't work without it.
• hydrateRoot: New method to hydrate a server rendered application. Use it instead of ReactDOM.hydrate in conjunction with the new React DOM Server APIs. New features in React 18 don't work without it.

Both createRoot and hydrateRoot accept a new option called onRecoverableError in case you want to be notified when React recovers from errors during rendering or hydration for logging. By default, React will use reportError, or console.error in the older browsers.

React DOM Server

These new APIs are now exported from react-dom/server and have full support for streaming Suspense on the server:

• renderToPipeableStream: for streaming in Node environments.
• renderToReadableStream: for modern edge runtime environments, such as Deno and Cloudflare workers.

The existing renderToString method keeps working but is discouraged.

Deprecations

• react-dom: ReactDOM.render has been deprecated. Using it will warn and run your app in React 17 mode.
• react-dom: ReactDOM.hydrate has been deprecated. Using it will warn and run your app in React 17 mode.
• react-dom: ReactDOM.unmountComponentAtNode has been deprecated.
• react-dom: ReactDOM.renderSubtreeIntoContainer has been deprecated.
• react-dom/server: ReactDOMServer.renderToNodeStream has been deprecated.

Breaking Changes

React

• Automatic batching: This release introduces a performance improvement that changes to the way React batches updates to do more batching automatically. See Automatic batching for fewer renders in React 18 for more info. In the rare case that you need to opt out, wrap the state update in flushSync.
• Stricter Strict Mode: In the future, React will provide a feature that lets components preserve state between unmounts. To prepare for it, React 18 introduces a new development-only check to Strict Mode. React will automatically unmount and remount every component, whenever a component mounts for the first time, restoring the previous state on the second mount. If this breaks your app, consider removing Strict Mode until you can fix the components to be resilient to remounting with existing state.
• Consistent useEffect timing: React now always synchronously flushes effect functions if the update was triggered during a discrete user input event such as a click or a keydown event. Previously, the behavior wasn't always predictable or consistent.
• Stricter hydration errors: Hydration mismatches due to missing or extra text content are now treated like errors instead of warnings. React will no longer attempt to "patch up" individual nodes by inserting or deleting a node on the client in an attempt to match the server markup, and will revert to client rendering up to the closest <Suspense> boundary in the tree. This ensures the hydrated tree is consistent and avoids potential privacy and security holes that can be caused by hydration mismatches.
• Suspense trees are always consistent: If a component suspends before it's fully added to the tree, React will not add it to the tree in an incomplete state or fire its effects. Instead, React will throw away the new tree completely, wait for the asynchronous operation to finish, and then retry rendering again from scratch. React will render the retry attempt concurrently, and without blocking the browser.
• Layout Effects with Suspense: When a tree re-suspends and reverts to a fallback, React will now clean up layout effects, and then re-create them when the content inside the boundary is shown again. This fixes an issue which prevented component libraries from correctly measuring layout when used with Suspense.
• New JS Environment Requirements: React now depends on modern browsers features including Promise, Symbol, and Object.assign. If you support older browsers and devices such as Internet Explorer which do not provide modern browser features natively or have non-compliant implementations, consider including a global polyfill in your bundled application.

Scheduler (Experimental)

• Remove unstable scheduler/tracing API

Notable Changes

React

• Components can now render undefined: React no longer throws if you return undefined from a component. This makes the allowed component return values consistent with values that are allowed in the middle of a component tree. We suggest to use a linter to prevent mistakes like forgetting a return statement before JSX.
• In tests, act warnings are now opt-in: If you're running end-to-end tests, the act warnings are unnecessary. We've introduced an opt-in mechanism so you can enable them only for unit tests where they are useful and beneficial.
• No warning about setState on unmounted components: Previously, React warned about memory leaks when you call setState on an unmounted component. This warning was added for subscriptions, but people primarily run into it in scenarios where setting state is fine, and workarounds make the code worse. We've removed this warning.
• No suppression of console logs: When you use Strict Mode, React renders each component twice to help you find unexpected side effects. In React 17, we've suppressed console logs for one of the two renders to make the logs easier to read. In response to community feedback about this being confusing, we've removed the suppression. Instead, if you have React DevTools installed, the second log's renders will be displayed in grey, and there will be an option (off by default) to suppress them completely.
• Improved memory usage: React now cleans up more internal fields on unmount, making the impact from unfixed memory leaks that may exist in your application code less severe.

React DOM Server

• renderToString: Will no longer error when suspending on the server. Instead, it will emit the fallback HTML for the closest <Suspense> boundary and then retry rendering the same content on the client. It is still recommended that you switch to a streaming API like renderToPipeableStream or renderToReadableStream instead.
• renderToStaticMarkup: Will no longer error when suspending on the server. Instead, it will emit the fallback HTML for the closest <Suspense> boundary and retry rendering on the client.

All Changes

React

• Add useTransition and useDeferredValue to separate urgent updates from transitions. (#10426, #10715, #15593, #15272, #15578, #15769, #17058, #18796, #19121, #19703, #19719, #19724, #20672, #20976 by @acdlite, @lunaruan, @rickhanlonii, and @sebmarkbage)
• Add useId for generating unique IDs. (#17322, #18576, #22644, #22672, #21260 by @acdlite, @lunaruan, and @sebmarkbage)
• Add useSyncExternalStore to help external store libraries integrate with React. (#15022, #18000, #18771, #22211, #22292, #22239, #22347, #23150 by @acdlite, @bvaughn, and @drarmstr)
• Add startTransition as a version of useTransition without pending feedback. (#19696 by @rickhanlonii)
• Add useInsertionEffect for CSS-in-JS libraries. (#21913 by @rickhanlonii)
• Make Suspense remount layout effects when content reappears. (#19322, #19374, #19523, #20625, #21079 by @acdlite, @bvaughn, and @lunaruan)
• Make <StrictMode> re-run effects to check for restorable state. (#19523 , #21418 by @bvaughn and @lunaruan)
• Assume Symbols are always available. (#23348 by @sebmarkbage)
• Remove object-assign polyfill. (#23351 by @sebmarkbage)
• Remove unsupported unstable_changedBits API. (#20953 by @acdlite)
• Allow components to render undefined. (#21869 by @rickhanlonii)
• Flush useEffect resulting from discrete events like clicks synchronously. (#21150 by @acdlite)
• Suspense fallback={undefined} now behaves the same as null and isn't ignored. (#21854 by @rickhanlonii)
• Consider all lazy() resolving to the same component equivalent. (#20357 by @sebmarkbage)
• Don't patch console during first render. (#22308 by @lunaruan)
• Improve memory usage. (#21039 by @bgirard)
• Improve messages if string coercion throws (Temporal.*, Symbol, etc.) (#22064 by @justingrant)
• Use setImmediate when available over MessageChannel. (#20834 by @gaearon)
• Fix context failing to propagate inside suspended trees. (#23095 by @gaearon)
• Fix useReducer observing incorrect props by removing the eager bailout mechanism. (#22445 by @josephsavona)
• Fix setState being ignored in Safari when appending iframes. (#23111 by @gaearon)
• Fix a crash when rendering ZonedDateTime in the tree. (#20617 by @dimaqq)
• Fix a crash when document is set to null in tests. (#22695 by @SimenB)
• Fix onLoad not triggering when concurrent features are on. (#23316 by @gnoff)
• Fix a warning when a selector returns NaN. (#23333 by @hachibeeDI)
• Fix the generated license header. (#23004 by @vitaliemiron)
• Add package.json as one of the entry points. (#22954 by @Jack)
• Allow suspending outside a Suspense boundary. (#23267 by @acdlite)
• Log a recoverable error whenever hydration fails. (#23319 by @acdlite)

React DOM

• Add createRoot and hydrateRoot. (#10239, #11225, #12117, #13732, #15502, #15532, #17035, #17165, #20669, #20748, #20888, #21072, #21417, #21652, #21687, #23207, #23385 by @acdlite, @bvaughn, @gaearon, @lunaruan, @rickhanlonii, @trueadm, and @sebmarkbage)
• Add selective hydration. (#14717, #14884, #16725, #16880, #17004, #22416, #22629, #22448, #22856, #23176 by @acdlite, @gaearon, @salazarm, and @sebmarkbage)
• Add aria-description to the list of known ARIA attributes. (#22142 by @mahyareb)
• Add onResize event to video elements. (#21973 by @rileyjshaw)
• Add imageSizes and imageSrcSet to known props. (#22550 by @eps1lon)
• Allow non-string <option> children if value is provided. (#21431 by @sebmarkbage)
• Fix aspectRatio style not being applied. (#21100 by @gaearon)
• Warn if renderSubtreeIntoContainer is called. (#23355 by @acdlite)

React DOM Server

• Add the new streaming renderer. (#14144, #20970, #21056, #21255, #21200, #21257, #21276, #22443, #22450, #23247, #24025, #24030 by @sebmarkbage)
• Fix context providers in SSR when handling multiple requests. (#23171 by @frandiox)
• Revert to client render on text mismatch. (#23354 by @acdlite)
• Deprecate renderToNodeStream. (#23359 by @sebmarkbage)
• Fix a spurious error log in the new server renderer. (#24043 by @eps1lon)
• Fix a bug in the new server renderer. (#22617 by @shuding)
• Ignore function and symbol values inside custom elements on the server. (#21157 by @sebmarkbage)

React DOM Test Utils

• Throw when act is used in production. (#21686 by @acdlite)
• Support disabling spurious act warnings with global.IS_REACT_ACT_ENVIRONMENT. (#22561 by @acdlite)
• Expand act warning to cover all APIs that might schedule React work. (#22607 by @acdlite)
• Make act batch updates. (#21797 by @acdlite)
• Remove warning for dangling passive effects. (#22609 by @acdlite)

React Refresh

• Track late-mounted roots in Fast Refresh. (#22740 by @anc95)
• Add exports field to package.json. (#23087 by @otakustay)

Server Components (Experimental)

• Add Server Context support. (#23244 by @salazarm)
• Add lazy support. (#24068 by @gnoff)
• Update webpack plugin for webpack 5 (#22739 by @michenly)
• Fix a mistake in the Node loader. (#22537 by @btea)
• Use globalThis instead of window for edge environments. (#22777 by @huozhi)

Scheduler (Experimental)

• Remove unstable scheduler/tracing API (#20037 by @bvaughn)