Registry / web-framework / suspend-react

suspend-react

library0.1.3jsnpmunverified

suspend-react is a utility library for integrating asynchronous operations seamlessly with React Suspense. It allows developers to define functions that return promises, which then 'suspend' rendering until the promise resolves, effectively bringing an `async/await` like paradigm to React components. The library manages pending and error states at a higher level via React's `<Suspense>` and Error Boundaries, reducing boilerplate in individual components. It features a global, key-based caching mechanism, similar to `useMemo` but with application-wide scope, supporting configurable cache invalidation via `lifespan` and custom equality functions. Additionally, it offers preloading, cache busting, and direct cache peeking utilities. The current stable version is 0.1.3, with recent patch releases in June 2023, indicating a stable yet actively maintained project under the pmndrs umbrella. It simplifies data fetching and resource loading within Suspense-enabled React applications.

web-framework http-networking data

npm install suspend-react

github ↗package ↗

INSTALL

IMPORT

SIG · SUSPEND-REACT

suspend-react

web-frameworkjavascriptv0.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

suspend

✓ import { suspend } from 'suspend-react'

✗ const suspend = require('suspend-react').suspend

suspend-react is an ESM-first package. Use named imports.

preload

✓ import { preload } from 'suspend-react'

✗ import preload from 'suspend-react'

Named export for preloading data into the cache.

clear

✓ import { clear } from 'suspend-react'

✗ const clear = require('suspend-react').clear

Named export for clearing cached entries, globally or by specific keys.

peek

✓ import { peek } from 'suspend-react'

Named export to access cached values synchronously without suspending.

Demonstrates basic usage of `suspend` within a React component wrapped by `<Suspense>` to fetch and display data from an asynchronous source, handling loading states declaratively.

import { Suspense } from 'react'; import { suspend } from 'suspend-react'; function Post({ id, version }) { const data = suspend(async () => { // In a real app, use a more robust fetching mechanism and error handling const res = await fetch(`https://hacker-news.firebaseio.com/${version}/item/${id}.json`); if (!res.ok) { throw new Error(`Failed to fetch post ${id}: ${res.statusText}`); } return res.json(); }, [id, version]); return ( <div> <h3>{data.title}</h3> <p>by {data.by}</p> <p>Score: {data.score}</p> </div> ); } function App() { return ( <Suspense fallback={<div>Loading post...</div>}> <h1>Hacker News Post</h1> <Post id={8863} version="v0" /> {/* A classic HN post ID */} </Suspense> ); } // To run this in a simple environment, you might need a root component: // import ReactDOM from 'react-dom/client'; // const root = ReactDOM.createRoot(document.getElementById('root')); // root.render(<App />);

Debug

Known issues

gotchaThe caching mechanism in `suspend-react` operates on a global cache by default. While this simplifies usage, it requires developers to ensure their cache keys are sufficiently unique to prevent unintended conflicts or overwrites if the same keys could logically refer to different data across disparate parts of the application.

fix

Use a robust key generation strategy (e.g., combining IDs, types, and versions) to ensure uniqueness. Consider the scope of your keys when multiple components might use similar data patterns.

affects: >=0.1.0

gotchaWhile the README states compatibility with 'React versions >= 16.6', the declared peer dependency is `"react": ">=17.0"`. Installing with React versions 16.x (specifically 16.6-16.9 which introduced Suspense for data fetching) might result in peer dependency warnings or unexpected behavior if certain React 17+ APIs are implicitly relied upon. Always respect the peer dependency range for stable operations.

fix

Ensure your project uses React version 17.0 or higher to satisfy the peer dependency. Upgrade React if necessary: `npm install react@^17.0 react-dom@^17.0`.

affects: >=0.1.0

gotchaWhen using `suspend`, errors thrown by the promise-returning function will propagate up to the nearest React Error Boundary. If no Error Boundary is present in the component tree above the suspending component, the application will crash. This is standard React Suspense behavior but a common oversight.

fix

Always wrap components that use `suspend` (or their parents) in an Error Boundary component to gracefully handle potential runtime errors from asynchronous operations. Example: `<ErrorBoundary><Suspense fallback={...}><MySuspendingComponent /></Suspense></ErrorBoundary>`.

affects: >=0.1.0

Errors

Common errors & fixes

Error: A component suspended while rendering, but no fallback UI was specified. This means that a 'Suspense' component higher in the tree needs to provide a fallback prop.

A component using `suspend` rendered without being wrapped by a `<React.Suspense>` component, or the `fallback` prop on `<Suspense>` was omitted.

fix

Wrap the suspending component (or a common ancestor) with `<React.Suspense fallback={<div>Loading...</div>}>` and ensure the `fallback` prop is provided with a valid React element.

Module not found: Error: Can't resolve 'suspend-react' in '...' OR Cannot find module 'suspend-react'

The `suspend-react` package has not been installed or is not correctly linked in your project.

fix

Install the package using your package manager: `npm install suspend-react` or `yarn add suspend-react`.

TypeError: suspend is not a function OR suspend is not defined

The `suspend` function was either not imported correctly (e.g., attempting a default import or using CommonJS `require` syntax incorrectly) or was not imported at all.

fix

Ensure you are using a named import for `suspend`: `import { suspend } from 'suspend-react';`

Upgrade

Version history

0.1.3latest on npm

Audit

Dependencies

reactrequiredRequired peer dependency for React functionality.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/pmndrs/suspend-react ↗

packagehttps://www.npmjs.com/package/suspend-react ↗