React - Suspense

1. Suspense Component 👩‍💻

Suspense 는 React 가 제공하는 Wrapper Component 로 children의 로딩이 끝날 때까지 렌더링 할 대체 컴포넌트를 fallback으로 제공하는 컴포넌트로 기본 Syntax 는 다음과 같다.

<Suspense fallback={<Loading />}>
  <SomeComponent />
</Suspense>

React 19 에서 추가될 예정인 기능들이 있기 때문에 19 버전 정식 출시 이전에는 canary 버전으로 설치해야 모든 기능을 사용할 수 있다.

# React 19 버전 미만일 경우 canary 를 설치한다.
npm i react@canary react-dom@canary --legacy-peer-deps

---

2. Usage 👩‍💻

1. Displaying a fallback while content is loading

Suspense 가 등장하기 전 Albums 컴포넌트의 로딩 fallback 을 제공하는 방법은 다음과 같았다.

• Albums.jsx

export default function Albums({ artistId }) {
  const [loading, setLoading] = useState(false);
  const [albums, setAlbums] = useState();

  const getAlbums = async () => {
    setLoading(true);
    const response = await fetchData(`/${artistId}/albums`);
    setAlbums(response);
    setLoading(false);
  };

  useEffect(() => {
    getAlbums();
  }, [getAlbums]);

  if (loading) {
    return <Loading />;
  }

  return (
      <ul>
        {albums?.map((album) => (
            <li key={album.id}>
              {album.title} ({album.year})
            </li>
        ))}
      </ul>
  );
}

Suspense 를 도입하면 위 컴포넌트는 비즈니스 로직과 fallback 을 분리할 수 있다.

• Albums.jsx

export default function Albums({ artistId }) {
  const albums = use(fetchData(`/${artistId}/albums`));
  return (
      <ul>
        {albums.map((album) => (
            <li key={album.id}>
              {album.title} ({album.year})
            </li>
        ))}
      </ul>
  );
}

<Suspense fallback={<Loading />}>
  <Albums />
</Suspense>

Albums가 로딩중일 때는 자동으로 Loading이 렌더링 되고, 로딩이 끝나면 Albums를 렌더링 해 교체한다. 이를 좀 더 정확하게 설명하면, Suspense 의 children 이 모두 로딩된 후 fallback 이 해제된다.

이때 Suspense Component 가 데이터 로딩을 감지할 수 있는 조건은 다음과 같다.

• Relay나 Next.js와 같은 Suspense-enabled frameworks 가 데이터를 fetching 할 때.
• lazy 키워드를 사용한 Lazy-loading Component 를 사용할 때.
• use로 wrapping 한 Promise 를 읽을 때.

여기서 use는 React 18 버전에는 존재하지 않는다. canary 버전에서 사용 가능한 신규 API 로 React 19 버전에 추가될 예정이다.

따라서 Suspense with axios on React 18 에서 use 역할을 하는 Wrapping 함수를 만들어 사용하는 방법을 구현할 것이다. 단, use와 다른 점은 use 는 Promise 뿐 아니라 Context 를 Wrapping 하는 데도 사용할 수 있는 반면 아래서 구현할 함수는 오직 Suspense 를 axios 와 함께 사용하기 위한 Wrapping 함수 다.

다음 코드를 보자.

<Suspense fallback={<Loading />}>
  <Biography />
  <Panel>
    <Albums />
  </Panel>
</Suspense>

이렇게 children 이 여러 개 있는 경우는 어떻게 작동할까? Suspense 의 children 이 모두 로딩된 후 fallback 이 해제된다고 했다. 특히 자식 컴포넌트 뿐 아니라 자손 컴포넌트까지 모두 다 로딩이 완료되어야 fallback 을 해제할 수 있다.

따라서 일부 컴포넌트의 로딩이 완료 되더라도 자손을 포함한 모든 하위 컴포넌트가 로딩될 때까지 계속 fallback 상태에 놓여 있게 되고, 사용자는 앱이 느리게 반응해 좋지 못한 사용자 경험을 하게 된다.

2. Revealing nested content as it loads

그런데 어떤 컴포넌트는 느리게 로딩이 되지만 어떤 컴포넌트는 빠르게 로딩이 될 수도 있다. 특히 API 응답이 느린 부분은 프론트엔드에서 어떻게 할 수 있는 부분이 아니기 때문에 빠르게 로딩 된 것들 먼저 보여주며 로딩이 완료됨에 따라 점진적으로 화면을 업데이트 하면 더 좋은 사용자 경험을 제공해 줄 수 있다.

Error Boundary와 마찬가지로 Suspense 역시 중첩이 가능하다. 그리고 중첩된 경우 가장 가까이 있는 Suspense 에 영향을 받으므로 모든 자손을 감시하지 않는다. 무슨 말인지 코드를 보자.

<Suspense fallback={<BigSpinner />}>
  <Biography />
  <Suspense fallback={<AlbumsGlimmer />}>
    <Panel>
      <Albums />
    </Panel>
  </Suspense>
</Suspense>

1. Biography가 로딩되지 않았다면 BigSpinner가 fallback 되어 전체 영역을 대신한다.
2. Biography가 로딩되면 BigSpinner fallback 이 해제되어 content 가 보여진다.
3. 만약 Albums가 아직 로딩되지 않았다면 AlbumGlimmer가 fallback 되어 children 의 로딩을 기다린다.
4. Albums가 로딩되면 AlbumGlimmer fallback 역시 해제되어 모든 content 가 보여진다.

3. useDeferredValue

데이터를 검색하는 동안 Loading fallback 이 대체하는 경우를 생각해보자.

export default function App() {
  const [query, setQuery] = useState('');
  return (
      <>
        <label>
          Search albums:
          <input value={query} onChange={e => setQuery(e.target.value)} />
        </label>
        <Suspense fallback={<h2>Loading...</h2>}>
          <SearchResults query={query} />
        </Suspense>
      </>
  );
}

이 컴포넌트는 이전과 달리 렌더링이 완료된 이후에도 계속해서 API 요청을 할 수 있다. 이 말은 검색을 할 때마다 Promise 를 생성하고, 매번 fallback 이 렌더링 된다는 것이다.

이미 렌더링 된 컴포넌트가 매번 지워지고 새롭게 그려지는 것은 성능에도 영향을 미치지만 무엇보다 UI 상 좋지 못하다는 문제점을 갖는다. 따라서 fallback 으로 대체되지 않고, 새 데이터가 로딩되어 update 될 때까지 UI 업데이트를 지연시키는 것이 좋다.

const deferredValue = useDeferredValue(value)

useDeferredValue 는 UI 업데이트를 지연시키는 Hooks 로 debounce 함수와 달리 비즈니스 로직은 지연시키지 않고 UI 업데이트만 지연시킨다.

export default function App() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);
  const isStale = query !== deferredQuery;
  return (
    <>
      <label>
        Search albums:
        <input value={query} onChange={e => setQuery(e.target.value)} />
      </label>
      <Suspense fallback={<h2>Loading...</h2>}>
        <div style=>
          <SearchResults query={deferredQuery} />
        </div>
      </Suspense>
    </>
  );
}

이제 더이상 fallback 으로 대체되지 않고 로딩이 완료될 때까지 UI 업데이트를 지연시킨다. 단 이 경우 이미 로딩된 컴포넌트일 때만 UI 업데이트를 지연시키는 것이 아니고 useDefereedValue에 의해 업데이트 되는 모든 UI 업데이트를 지연시키기 때문에 위 코드의 fallback 은 항상 대체가 되지 않는다. 만약 fallback 으로 대체가 되려면 useDefereedValue가 아닌 다른 state 에 의한 업데이트가 이루어져야한다.

4. startTransition

useState의 업데이트에 의한 UI 업데이트 지연은 useDeferredValue 훅을 사용해 해결할 수 있었다. 그런데 컴포넌트 트리 구조에서 특정 컴포넌트를 지연시키고자 할 때는 어떻게 해야할까? 아래 코드를 보자.

export default function App() {
  return (
    <Suspense fallback={<BigSpinner />}>
      <Router />
    </Suspense>
  );
}

function Router() {
  const [page, setPage] = useState('/');

  function navigate(url) {
    setPage(url);
  }

  let content;
  if (page === '/') {
    content = (
      <IndexPage navigate={navigate} />
    );
  } else if (page === '/the-beatles') {
    content = (
      <ArtistPage
        artist=
      />
    );
  }
  return (
    <Layout>
      {content}
    </Layout>
  );
}

function BigSpinner() {
  return <h2>🌀 Loading...</h2>;
}

위 코드를 보면 라우터를 Suspense 컴포넌트가 감싸고 있고 fallback 으로 BigSpinner를 제공하고 있다. 그리고 라우터는 언제나 매칭되는 컴포넌트를 Layout 컴포넌트로 감싸기 때문에 컴포넌트가 다시 렌더링 되더라도 Layuout은 변함 없이 공통으로 렌더링 되는 것을 알 수 있다.

하지만 children 을 통째로 fallback 으로 대체하기 때문에 Router 컴포넌트는 통째로 BigSpinner로 대체된다. 지워질 필요가 없는 레이아웃까지 모두 fallback 되어버리니 마치 SSR 을 사용하는 것과 같은 좋지 못한 사용자 경험을 하게 된다.

즉, 현재 상태는 Revealing nested content as it loads 와 같다고 할 수 있다.

Layout은 fallback 이 되지 않고 하위 컴포넌트만 fallback 되게 하려면 어떻게 해야 할까? 가장 간단한 방법은 Router를 Suspense로 감싸지 않는 것이다. 그러면 하위 컴포넌트가 갖고 있는 Suspense 의 fallback 만 작동할 것이다.

대신 이 경우 Layout은 fallback 이 되지 않기 때문에 첫 로딩시에도 fallback 대체가 불가능하다. 만약 첫 로딩시에는 fallback 을 사용하되, 이후 하위 컴포넌트 업데이트 시 이미 렌더링 된 content 를 유지한 채로 하위 fallback 만 대체하도록 하고 싶다면 어떻게 해야할까?

useDeferredValue와 Transitions 은 UI 업데이트를 지연시킨다.

여기서 우리에게 필요한 것은 Transition이다.

startTransition(scope)

startTransition 은 UI 블로킹 없이 state 를 업데이트 하도록 만드는 React API 다. Hooks 가 아니라 API 임에 유의하도록 하자.

useDefferedValue는 state를 parameter 로 받아 새 변수를 반환했다. startTransition은 setState를 closure 형태로 받으며 API 에 바로 등록되기 때문에 별도의 반환값은 없다.

startTransition(() => {
  // ✅ Setting state *during* startTransition call
  setPage('/about');
});

이미 렌더링 된 컴포넌트의 불필요한 fallback 대체가 발생하지 않도록 startTransition을 적용해보자.

export default function App() {
  return (
      <Suspense fallback={<BigSpinner />}>
        <Router />
      </Suspense>
  );
}

function Router() {
  const [page, setPage] = useState('/');

  function navigate(url) {
    startTransition(() => {
      setPage(url);      
    });
  }
  // ...
}

이제 Transitions 가 시작되며 UI 업데이트가 지연되어 BigSpinner fallback 은 대체되지 않고 하위 컴포넌트 ArtistPage에 있는 Albums를 감싸고 있는 Suspense 의 AlbumsGlimmer fallback 만 대체된다. 이때 주의해야 할 것이 Layout이 fallback 으로 대체되지 않았다고 아예 렌더 함수 호출 자체가 이루어지지 않는 것은 아니다!

렌더 함수의 호출은 정상적으로 이루어지지지만 fallback 으로 대체되는 대신 UI 업데이트를 지연시키는 것 뿐이다. 그리고 이것은 이미 그려진 UI 일 때만 지연되기 때문에 아직 UI 가 그려지지 않아 해당 Suspense 가 최초로 작동하는 시점에는 fallback 으로 대체가 된다. 즉, 해당 페이지 첫 방문 시에는 Layout 의 fallback 과 자식 컴포넌트의 fallback 이 모두 작동하지만, 이후에는 자식의 fallback 만 작동하는 것이다.

리액트로 앱을 만들 때 페이지 이동 시 Transitions 를 사용하는 것이 권장되는 데 두 가지 이유는 다음과 같다.

• 렌더링이 완료되기 전 사용자가 다른 것을 클릭하면 Transition 을 중단할 수 있다 (만약 Transition 을 사용하지 않는다면 사용자의 클릭 입력은 전달되지만 이전에 클릭한 UI 업데이트 지연이 중단되지 않아 기다린 후 순차적으로 업데이트된다).
• Transition 은 원치 않는 loading indicator 가 나타나지 않게 할 수 있다.

라우터에 Suspense 와 Transitions 를 적용하는 것을 Building a Suspense-enabled router 라 한다.

startTransition 사용시 유의점 두 가지는 다음과 같다.

1 ) startTransition is synchronous

이때 주의해야 할 것이 startTransition은 반드시 Synchronous 여야 한다. 따라서 다음은 허용되지 않는다.

startTransition(() => {
  // ❌ Setting state *after* startTransition call
  setTimeout(() => {
    setPage('/about');
  }, 1000);
});

만약, setTimeout 을 적용해야 한다면 순서를 바꿔 startTransition은 반드시 Synchronous 하도록 해야 한다.

setTimeout(() => {
  startTransition(() => {
    // ✅ Setting state *during* startTransition call
    setPage('/about');
  });
}, 1000);

마찬가지로 async/await 역시 Asynchronous 코드이기 때문에 허용되지 않는다.

startTransition(async () => {
  await someAsyncFunction();
  // ❌ Setting state *after* startTransition call
  setPage('/about');
});

이렇게 startTransition 밖으로 빼내 반드시 Synchronous 여야 한다.

await someAsyncFunction();
startTransition(() => {
  // ✅ Setting state *during* startTransition call
  setPage('/about');
});

그리고 startTransition을 사용할 때 주의해야 할 것이 이것은 브라우저 API 인 setTimeout과 달리 나중에 실행되지 않는다는 것이다. UI 업데이트를 지연시키기 때문에 혼동할 수 있지만 startTransition 역시 동기로 작동한다. 마치 context 전체를 async 로 감싸고 await 을 사용한 것과 유사하다.

console.log(1);
startTransition(() => {
  console.log(2);
  setPage('/about');
});
console.log(3);

1
2
3

동기적으로 작동하기 때문에 1, 3, 2 순서가 아닌 1, 2, 3 순서로 코드가 실행된다. 단지 UI 업데이트 지연이 끝난 이후에 다음 코드가 실행되도록 잠시 지연될 뿐이다.

2 ) Updating an input in a Transition doesn’t work

또 다른 주의점은 input 은 동기적으로 즉시 업데이트 되기 때문에 startTransition과 함께 사용할 수 없다. Transitions 가 non-blocking 이기 때문이다.

const [text, setText] = useState('');
// ...
function handleChange(e) {
  // ❌ Can't use Transitions for controlled input state
  startTransition(() => {
    setText(e.target.value);
  });
}
// ...
return <input value={text} onChange={handleChange} />;

이런 상황에서 해결 방법은 두 가지가 있다.

• 이 경우 두 개의 state를 만들어 하나는 값을 즉시 업데이트 하고, 다른 하나는 Transitions UI 렌더링 로직에 사용하도록 한다.
• 하나의 state를 사용하는 대신 useDeferredValue 를 추가해 실제 값을 감춘다.

5. useTransition

startTransition API 를 사용하면 Suspense의 fallback 을 제어할 수 있다. 하지만 여전히 아쉬움이 있는데 로딩 중이라는 시각적 indicator 가 없다 보니 UI 업데이트 지연으로 인해 앱의 반응이 느리거나 클릭에 반응이 없는 것으로 오해할 수 있다는 점이다.

이에 대한 대안으로 가장 좋은 방법은 useTransition Hooks 를 사용하는 것이다. startTransition은 React API 였으나 useTransition 은 Hooks 라는 것에 유의하자. useTransition은 startTransition을 반환하기 때문에 직접 import 할 필요가 없으며 사용 방법은 다음과 같다.

const [isPending, startTransition] = useTransition()

function Router() {
  const [page, setPage] = useState('/');
  const [isPending, startTransition] = useTransition();

  function navigate(url) {
    startTransition(() => {
      setPage(url);
    });
  }
  // ...
  return (
    <Layout isPending={isPending}>
      {content}
    </Layout>
  );
}

export default function Layout({ children, isPending }) {
  return (
    <div className="layout">
      <section className="header" style=>
        Music Browser
      </section>
      <main>
        {children}
      </main>
    </div>
  );
}

이제 Layout 의 헤더를 통해 Loading indicator 를 표현할 수 있게 되었다. 참고로 여기서 isPending이 true인 기간은 Layout 컴포넌트가 속한 Suspense 의 fallback 이 표시되어야 하는 기간 동안에 해당한다. 즉, BigSpinner로 대체되는 대신 isPending indicator 를 사용해 로딩중을 시각적으로 표현해주는 것이다. isPending은 하위 컴포넌트에 있는 Suspense 의 AlbumsGlimmer fallback 과는 무관하다.

useTransition 사용시 유의점 두 가지는 다음과 같다.

1 ) The useTransition should be called inside a component

useTransition은 Hooks 이기 때문에 반드시 컴포넌트 안에서만 호출되어야한다. 예를 들어 data library 와 같이 컴포넌트 밖에서 호출이 필요하다면 Hooks 대신 API 인 startTransition을 사용해야하며, 이 경우 isPending indicator 는 사용할 수 없다.

2 ) Suspense integrated router should wrap its updates into startTransition automatically

라우터가 Suspense 와 통합된 경우 라우터 업데이트를 startTransition으로 wrapping 해야 한다.

6. key props

Suspense와 Transitions를 사용하면 이미 렌더링 된 컴포넌트의 UI 업데이트를 지연시켜 fallback 대체가 작동하지 않도록 할 수 있다. 하지만 때로는 같은 UI 라 하더라도 다시 렌더링 되는 것이 더 좋은 UI 가 될 때가 있다. 예를 들어 어떤 사용자의 정보를 보는 ProfilePage 컴포넌트가 있다고 해보자. 동일 사용자의 여러 정보를 보는 동안 이 사용자의 공통적인 정보를 나타내는 상위 컴포넌트의 content 는 fallback 이 작동하지 않는 것이 좋다. 세부 정보의 업데이트만 fallback 이 발생하는 것이 좋은 UI 다.

하지만 다른 사용자로 변경될 경우는 어떨까? 동일한 UI 이기 때문에 오히려 fallback 이 없을 경우 변화가 크지 않다면 UI 업데이트를 인지하지 못 할 가능성이 있다. 이런 경우 의도적으로 fallback 대체를 작동시켜 UI 업데이트가 이루어졌음을 표현해주는 것이 확실히 UI 업데이트를 인지시켜 더 좋은 사용자 경험을 갖게 한다.

어떻게 구분할 수 있을까? 컴포넌트의 iterating 시 key props 를 사용해 컴포넌트를 구분할 수 있는 고유값을 제공한다. 이 경우도 동일하게 key props 를 사용하면 Suspense 는 Transition 을 사용하더라도 key가 변경되면 다른 컴포넌트로 인식해 fallback 대체를 수행한다.

<ProfilePage key={queryParams.id} />

이렇게 key props 만 제공하면 변경 여부를 리액트가 확인 후 fallback 대체 여부를 판단한다.

7. Error Boundary

useTransition을 위한 Error Boundary 는 리액트 19 에 추가될 예정으로 현재는 canary 버전에서만 사용이 가능하다.

npm i react-error-boundary

공식 문저에서도 클래스 컴포넌트로 직접 구현하기보다는 bvaughn / react-error-boundary 라이브러리를 사용했기에 여기서도 동일하게 진행하고자 한다. 혹시 ErrorBoundary cannot be used as a JSX component 에러가 발생하면 링크를 참조해 해결하도록 한다.

export function AddCommentContainer() {
  return (
    <ErrorBoundary fallback={<p>⚠️Something went wrong</p>}>
      <AddCommentButton />
    </ErrorBoundary>
  );
}

function addComment(comment) {
  if (comment == null) {
    throw new Error("Example Error: An error thrown to trigger error boundary");
  }
}

function AddCommentButton() {
  const [pending, startTransition] = useTransition();

  return (
    <button
      disabled={pending}
      onClick={() => {
        startTransition(() => {
          addComment();
        });
      }}
    >
      Add comment
    </button>
  );
}

---

3. Suspense with axios on React 18 👩‍💻

use는 현재 canary 에서만 사용이 가능하다. 하지만 기능을 아예 못 쓰는 건 아니고 React 가 공식적으로 제공하는 기능으로 Promise 뿐 아니라 Context 에도 사용 가능한 함수일 뿐 현재도 Suspense 에 Promise 를 컨트롤 하기 위해 Wrapping 함수 use를 만들어 사용할 수 있다. 공식 문서에서 샘플로 만들어 사용하는 함수는 다음과 같은 형태를 띄고 있다.

export function use(promise) {
  if (promise.status === "fulfilled") {
    return promise.value;
  } else if (promise.status === "rejected") {
    throw promise.reason;
  } else if (promise.status === "pending") {
    throw promise;
  } else {
    promise.status = "pending";
    promise.then(
      (result) => {
        promise.status = "fulfilled";
        promise.value = result;
      },
      (reason) => {
        promise.status = "rejected";
        promise.reason = reason;
      },
    );
    throw promise;
  }
}

TypeScript 환경이며 Axios 라이브러리를 사용한다면 다음과 같이 Wrapping 함수 use를 만들어 사용할 수 있다.

import { AxiosPromise } from "axios";

export const use = <T>(promise: AxiosPromise<T>) => {
  let status = "pending";
  let result: T;

  const suspender = promise
    .then((response) => {
      status = "success";
      result = response.data;
    })
    .catch((response) => {
      status = "error";
      result = response.error;
    });

  return () => {
    switch (status) {
      case "pending":
        throw suspender;
      case "success":
        return result;
      case "error":
        return result as any;
      default:
        throw new Error("Unknown status");
    }
  };
};

<Suspense fallback={<Loading />}>
  <Purchased />
  <button onClick={() => navigate("/")}>첫 페이지로</button>
</Suspense>

const Purchased: React.FC = () => {
  const [orderHistory, setOrderHistory] = useState<OrderInfo[]>();
  const { totals } = useContext(OrderContext);

  const getData = async () => {
    const promise = axios.post("/order", { price: totals.total });
    setOrderHistory(use(promise));
  };

  useEffect(() => {
    getData();
  }, []);

  return (
    <PurchasedWrapper>
      <h2>주문이 완료되었습니다</h2>
      <h3>주문 내역</h3>
      <div className="order-history">
        <h5>주문 번호</h5>
        <h5>주문 금액</h5>
        {orderHistory?.map((orderInfo) => (
          <Fragment key={orderInfo.orderNumber}>
            <div>{orderInfo.orderNumber}</div>
            <div>{orderInfo.price}</div>
          </Fragment>
        ))}
      </div>
    </PurchasedWrapper>
  );
};

---

Reference

1. “Suspense.” React.dev Docs. accessed Jun. 03, 2024, https://react.dev/reference/react/Suspense.
2. “useTransition.” React.dev Docs. accessed Jun. 03, 2024, https://react.dev/reference/react/useTransition.