React Suspense Utilities

Common errors

• 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.

  cause 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'

  cause 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

  cause 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';`

Warnings

• gotcha The 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.
• gotcha While 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`.
• gotcha When 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>`.

Install

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

Imports

• suspend
  wrong:

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

  correct:

  import { suspend } from 'suspend-react'

  suspend-react is an ESM-first package. Use named imports.
• preload
  wrong:

  import preload from 'suspend-react'

  correct:

  import { preload } from 'suspend-react'

  Named export for preloading data into the cache.
• clear
  wrong:

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

  correct:

  import { clear } from 'suspend-react'

  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.

Quickstart

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 />);