React Promise Suspense Hook

Common errors

• Error: A component suspended while rendering, but no fallback UI was specified.

  cause A component using `usePromise` rendered before its data was available, but it was not wrapped by a `Suspense` boundary.
  fix Ensure the component that calls `usePromise` (or an ancestor component) is rendered within a `<Suspense fallback={/* your loading UI */}>` component.

• TypeError: (0 , react_promise_suspense__WEBPACK_IMPORTED_MODULE_0__.default) is not a function

  cause Incorrect import statement for `usePromise`, or bundler misconfiguration handling default exports.
  fix Use the correct import syntax: `import usePromise from 'react-promise-suspense';`. Verify your bundler (Webpack, Rollup) is configured to correctly handle ESM default exports.

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

  cause The `usePromise` hook was called outside of a React function component or a custom hook.
  fix Ensure `usePromise` is only invoked directly within the top level of a React function component or another custom hook function.

Warnings

• gotcha The `react-promise-suspense` library has not been updated since March 2020. Its compatibility with newer React versions (e.g., React 18 and above) or contemporary Suspense features may be limited or lead to unexpected behavior. Use with caution in modern React projects.
  Fix: Thoroughly test the library's behavior with your target React version. Consider alternative, actively maintained solutions for Suspense data fetching if issues arise.
• gotcha As a 0.x.x version package, the API of `react-promise-suspense` was never officially considered stable. Although no explicit breaking changes are documented in its sparse release history, future compatibility or expected behavior cannot be guaranteed.
  Fix: Always pin exact versions (`"react-promise-suspense": "0.3.4"`) to avoid unexpected changes if any hypothetical future updates were to occur (unlikely given its abandoned status).
• gotcha When using `usePromise`, ensure that the component calling it is wrapped in a `React.Suspense` boundary. Failing to do so will result in a runtime error when the promise resolves.
  Fix: Wrap any component that uses `usePromise` (or any other Suspense-enabled data fetching) with `<Suspense fallback={/* loading UI */}>`.

Install

• npm install react-promise-suspense npm
• yarn add react-promise-suspense yarn
• pnpm add react-promise-suspense pnpm

Imports

• usePromise
  wrong:

  import { usePromise } from 'react-promise-suspense';

  correct:

  import usePromise from 'react-promise-suspense';

  The `usePromise` hook is exported as the default export of the package.
• Suspense

  import { Suspense } from 'react';

  Required to wrap components that use `usePromise` for fallback UI.
• usePromise (TypeScript Type)
  wrong:

  import { usePromise } from 'react-promise-suspense';

  correct:

  import type usePromise from 'react-promise-suspense';

  Imports the type definition for `usePromise` for type checking purposes.

Quickstart

This quickstart demonstrates fetching data for multiple Pokemon concurrently using `usePromise` within `Suspense` boundaries, showcasing loading states.

import React, { Suspense } from 'react';
import usePromise from 'react-promise-suspense';

const fetchData = async (id) => {
  const response = await fetch(`https://pokeapi.co/api/v2/pokemon/${id}/`);
  if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
  return response.json();
};

const PokemonDisplay = ({ pokemonId }) => {
  const data = usePromise(fetchData, [pokemonId]);
  return (
    <div className="pokemon-card">
      <h2>{data.name}</h2>
      <img src={data.sprites.front_default} alt={data.name} />
      <p>Height: {data.height}</p>
      <p>Weight: {data.weight}</p>
    </div>
  );
};

const App = () => {
  return (
    <div className="app-container">
      <h1>Pokemon Viewer</h1>
      <Suspense fallback={<div>Loading Pokemon...</div>}>
        <PokemonDisplay pokemonId={1} />
        <PokemonDisplay pokemonId={4} />
        <PokemonDisplay pokemonId={7} />
      </Suspense>
      <style>{`
        .app-container { font-family: sans-serif; text-align: center; }
        .pokemon-card { border: 1px solid #eee; margin: 10px; padding: 15px; border-radius: 8px; display: inline-block; width: 200px; vertical-align: top; }
        img { width: 100px; height: 100px; }
      `}</style>
    </div>
  );
};

export default App;