Introduction

In React 19 the use API is now stable, find the documentation here.

This post is a collection of notes about subtle problems you might face.

If you have been using Next.js you might already be familiar with Suspense, the code examples are independent of any React framework to illustrate that you can take advantage of React 19 without any framework magic.

Example code refactoring

What your existing code might look like:

import React, { useEffect, useState } from 'react'

type StarWarsResponse = {
  name: string
  birth_year: string
}

const StarWars = (props: { id: number }) => {
  const [pageData, setPageData] = useState<null | StarWarsResponse>(null)
  const [errorState, setErrorState] = useState<null | string>(null)

  useEffect(() => {
    const fetchData = async () => {
      try {
        const response = await fetch(`https://swapi.dev/api/people/${props.id}`)
        if (!response.ok) {
          throw new Error(`Error: ${response.status} ${response.statusText}`)
        }
        const data = await response.json()
        setPageData(data)
      } catch (error) {
        setErrorState(error.message)
      }
    }

    fetchData()
  }, [])

  if (!pageData) {
    return <div>Loading...</div>
  }
  if (errorState) {
    return <div>{errorState}</div>
  }
  return (
    <div>
      <ul>
        <li>Name: {pageData?.name}</li>
        <li>Birthday: {pageData?.birth_year}</li>
      </ul>
    </div>
  )
}

After refactoring to "Suspense"

import React, { use, Suspense } from 'react'
import { ErrorBoundary } from 'react-error-boundary'

type StarWarsResponse = {
  name: string
  birth_year: string
}

const fetchData = async (id: number): Promise<StarWarsResponse> => {
  const response = await fetch(`https://swapi.dev/api/people/${id}`)
  if (!response.ok) {
    throw new Error(`Error: ${response.status} ${response.statusText}`)
  }
  const data = await response.json()
  return data
}

const fetchDataPromise = (id) => fetchData(id)

const StarWars = (props: { id: number }) => {
  const pageData = use<StarWarsResponse>(fetchDataPromise(props.id))
  return (
    <div>
      <ul>
        <li>Name: {pageData?.name}</li>
        <li>Birthday: {pageData?.birth_year}</li>
      </ul>
    </div>
  )
}

const StarWarsMain = () => (
  <ErrorBoundary fallback={<p>Something went wrong</p>}>
    <Suspense fallback={<div>Loading...</div>}>
      <StarWars id={1} />
    </Suspense>
  </ErrorBoundary>
)

export default StarWarsMain

What did we change?

API call

const fetchData = async (id: number): Promise<StarWarsResponse> => {
  const response = await fetch(`https://swapi.dev/api/people/${id}`)
  if (!response.ok) {
    throw new Error(`Error: ${response.status} ${response.statusText}`)
  }
  const data = await response.json()
  return data
}

We moved the fetchData function out of our component, this is great because in most projects remote API calls should be managed in a separate module.

Component

const StarWars = (props: { id: number }) => {
  const pageData = use<StarWarsResponse>(fetchDataPromise(props.id))
  return (
    <div>
      <ul>
        <li>Name: {pageData?.name}</li>
        <li>Birthday: {pageData?.birth_year}</li>
      </ul>
    </div>
  )
}

The overall "display" component is now greatly simplified.

Error and Loading state management

const StarWarsMain = () => (
  <ErrorBoundary fallback={<p>Something went wrong</p>}>
    <Suspense fallback={<div>Loading...</div>}>
      <StarWars id={1} />
    </Suspense>
  </ErrorBoundary>
)

We can manage errors and loading state in jsx and we can optionally abstract the Suspense and ErrorBoundary into a separate component.

Promise call reference

const fetchDataPromise = (id) => fetchData(id)

Lastly we have created a reference variable to the fetchData function. Remember, the fetchData function returns a promise and by adding a reference to the promise we can avoid the error:

"A component was suspended by an uncached promise."

In my experience, this part of the React 19 API felt odd. In most JavaScript applications we often cache the return value of the promise but in the case of React, you need to cache the promise NOT the return value.

The difference is subtle.

Troubleshooting

Uncached Promise

"A component was suspended by an uncached promise."

To fix the problem, create a reference to the promise outside of the Suspense boundry for example:

const fetchDataPromise = (id) => fetchData(id)

//... Suspense/Component definition

Promise called continuously

In some cases your promise will be called continuously without stopping.

React did not manage to detect the uncached promise and is re-rendering, because every time your component is rendered a new Promise is returned to the use function which triggers the re-render.

The solution is the same as above, create a reference to the promise outside of your Suspense boundry:

const fetchDataPromise = (id) => fetchData(id)

//... Suspense/Component definition

It is also okay to pass down the promise as a prop for example:

const StarWars = (props: { fetchDataPromise: Promise<StarWarsResponse> }) => {
  const pageData = use<StarWarsResponse>(fetchDataPromise)
  return (
    <div>
      <ul>
        <li>Name: {pageData?.name}</li>
        <li>Birthday: {pageData?.birth_year}</li>
      </ul>
    </div>
  )
}

Promise called once

You might notice that your promise is called once and does not get called again until you refresh the page.

This is because the "cached" Promise reference is never invalidated so React does not know when to re-render the component.

In some cases your framework might take care of this for you but if you need to control the API call, see below for an example:

let cachedPromise: Promise<StarWarsResponse> | undefined = undefined
const fetchDataCall = (id: number) => {
  if (!cachedPromise) {
    cachedPromise = fetchData(id)
  }
  return cachedPromise
}

const StarWars = (props: { id: number }) => {
  const pageData = use<StarWarsResponse>(fetchDataCall(props.id))
  useEffect(() => {
    const navigationEvent = () => {
      cachedPromise = undefined
    }
    window.addEventListener('popstate', navigationEvent)

    return () => {
      window.removeEventListener('popstate', navigationEvent)
    }
  }, [])

  return (
    <div>
      <ul>
        <li>Name: {pageData?.name}</li>
        <li>Birthday: {pageData?.birth_year}</li>
      </ul>
    </div>
  )
}

Conclusion

React 19 has some exciting changes,Suspense and use are great features!

Why not take advantage of the cache API?

The documentation says cache is for use with React Server Components however the code I have shared can be used in async Server Components or regular Components.

The cache function uses memoization to speed up shared computation across function calls, this is a slightly different use case to the examples in this post.

Hopefully you can feel confident controlling how your Promise is cached in React.