Pitfall

renderToString은 스트리밍 또는 데이터 대기를 지원하지 않음.

• 참고: 대안

renderToString은 React 트리를 HTML 문자열로 렌더링함.

const html = renderToString(reactNode)

Reference

renderToString(reactNode)

서버에서 renderToString을 호출하여 앱을 HTML로 렌더링 할 수 있음.

import { renderToString } from 'react-dom/server';

const html = renderToString(<App />);

클라이언트에서 hydrateRoot를 호출하여 서버에서 생성된 HTML을 인터랙티브하게 만들 수 있음.

Parameters

• reactNode: HTML로 렌더링하려는 React 노드. 예를 들어, <App />과 같은 JSX 노드.
• options (optional): 서버 렌더링을 위한 객체.
  • identifierPrefix (optional): React가 useId에 의해 생성된 ID에 사용하는 문자열 접두사. 같은 페이지에서 여러 루트를 사용할 때 충돌을 피하는 데 유용함.

Returns

HTML 문자열을 반환함.

Caveats

• renderToString은 Suspense를 제한적으로 지원함. 컴포넌트가 일시 중단되면 renderToString은 즉시 폴백을 HTML로 보냄.

• renderToString은 브라우저에서 작동하지만, 클라이언트 코드에서 사용하는 것은 권장하지 않음.

Usage

Rendering a React tree as HTML to a string

renderToString을 호출하면 앱을 서버 응답과 함께 보낼 수 있는 HTML 문자열로 렌더링할 수 있음:

import { renderToString } from 'react-dom/server';

// The route handler syntax depends on your backend framework
app.use('/', (request, response) => {
  const html = renderToString(<App />);
  response.send(html);
});

이렇게 하면 React 컴포넌트의 초기 비대화형 HTML 출력이 생성됨. 클라이언트에서는 서버에서 생성된 HTML을 hydrate하고 인터랙티브하게 만들기 위해 hydrateRoot를 호출해야 함.

Pitfall

renderToString은 스트리밍 또는 데이터 대기를 지원하지 않음.

• 참고: 대안

Alternatives

Migrating from renderToString to a streaming method on the server

renderToString은 즉시 문자열을 반환하므로, 스트리밍이나 데이터 대기를 지원하지 않음.

가능하면 이러한 모든 기능을 갖춘 대체 방법을 사용하는 것이 좋음:

• Node.js를 사용하는 경우, renerToPipeableStream을 사용할 것.
• Web Stream과 함께 Deno 또는 최신 엣지 런타임을 사용하는 경우, renderToReadableStream을 사용할 것.

서버 환경이 스트림을 지원하지 않는 경우 renderToString을 계속 사용할 수 있음.

Removing renderToString from the client code

클라이언트에서 일부 컴포넌트를 HTML로 변환하기 위해 renderToString을 사용하는 경우도 있음.

// 🚩 Unnecessary: using renderToString on the client
import { renderToString } from 'react-dom/server';

const html = renderToString(<MyIcon />);
console.log(html); // For example, "<svg>...</svg>"

클라이언트에서 react-dom/server를 가져오면 번들 크기가 불필요하게 증가하므로 피해야 함. 브라우저에서 일부 컴포넌트를 HTML로 렌더링해야 하는 경우 createRoot를 사용하여 DOM에서 HTML을 읽어야 함:

import { createRoot } from 'react-dom/client';
import { flushSync } from 'react-dom';

const div = document.createElement('div');
const root = createRoot(div);
flushSync(() => {
  root.render(<MyIcon />);
});
console.log(div.innerHTML); // For example, "<svg>...</svg>"

flushSync 호출은 innerHTML 프로퍼티를 읽기 전에 DOM을 업데이트하기 위해 필요함.

Troubleshooting

When a component suspends, the HTML always contains a fallback

renderToString은 Suspense를 완전히 지원하지 않음.

일부 컴포넌트가 일시 중단되는 경우(예: lazy로 정의되었거나 데이터를 fetch하는 경우), renderToString은 해당 콘텐츠가 resolve될 때까지 기다리지 않음. 대신 renderToString은 상위에서 가장 가까운 <Suspense> boundary를 찾아 HTML에서 해당 fallback prop을 렌더링함. 콘텐츠는 클라이언트 코드가 로드될 때까지 표시되지 않음.

이 문제를 해결하려면 권장 스트리밍 솔루션 중 하나를 사용할 것. 이 솔루션은 서버에서 확인되는 대로 콘텐츠를 청크로 스트리밍하여 클라이언트 코드가 로드되기 전에 사용자가 페이지가 점진적으로 채워지는 것을 볼 수 있도록 함.

const stream = renderToStaticNodeStream(reactNode)

Reference

renderToStaticNodeStream(reactNode)

서버에서 renderToStaticNodeStream을 호출하여 Node.js Readable Stream로 렌더링할 수 있음.

import { renderToStaticNodeStream } from 'react-dom/server';

const stream = renderToStaticNodeStream(<Page />);
stream.pipe(response);

Stream은 React 컴포넌트의 비대화형 HTML 출력을 생성함.

Parameters

• reactNode: HTML로 렌더링하려는 React 노드. 예를 들어, <Page />와 같은 JSX 노드.
• options (optional): 서버 렌더링을 위한 객체.
  • identifierPrefix (optional): React가 useId에 의해 생성된 ID에 사용하는 문자열 접두사. 같은 페이지에서 여러 루트를 사용할 때 충돌을 피하는 데 유용함.

Returns

HTML 문자열을 출력하는 Node.js Readable Stream을 반환함. 결과 HTML은 클라이언트에서 hydrate 할 수 없음.

Caveats

• renderToStaticNodeStream 출력을 hydrate 할 수 없음.

• 이 메서드는 출력을 반환하기 전에 모든 Suspense boundary가 완료될 때까지 기다림.

• React 18부터 이 메서드는 모든 출력을 버퍼링하므로 실제로는 스트리밍 이점을 제공하지 않음.

• 반환되는 스트림은 utf-8로 인코딩된 바이트 스트림임. 다른 인코딩의 스트림이 필요한 경우, 텍스트 트랜스코딩을 위한 트랜스폼 스트림을 제공하는 iconv-lite와 같은 프로젝트를 살펴볼 것.

Usage

Rendering a React tree as static HTML to a Node.js Readable Stream

renderToStaticNodeStream을 호출하여 서버 응답으로 파이프할 수 있는 Node.js Readable Stream을 생성할 수 있음:

import { renderToStaticNodeStream } from 'react-dom/server';

// The route handler syntax depends on your backend framework
app.use('/', (request, response) => {
  const stream = renderToStaticNodeStream(<Page />);
  stream.pipe(response);
});

스트림은 React 컴포넌트의 초기 비대화형 HTML 출력을 생성함.

Pitfall

이 메서드는 hydrate될 수 없는 비대화형 HTML을 렌더링함. 이 메서드는 React를 간단한 정적 페이지 생성기로 사용하거나 이메일과 같이 완전히 정적인 콘텐츠를 렌더링할 때 유용함.

인터랙티브 앱은 서버에서 renderToString을 사용하고 클라이언트에서 hydrateRoot를 사용해야 함.

const html = renderToStaticMarkup(reactNode)

Reference

renderToStaticMarkup(reactNode)

서버에서 renderToStaticMarkup을 호출하여 앱을 HTML로 렌더링할 수 있음.

import { renderToStaticMarkup } from 'react-dom/server';

const html = renderToStaticMarkup(<Page />);

이는 React 컴포넌트의 비대화형 HTML 출력을 생성함.

Parameters

• reactNode: HTML로 렌더링하려는 React 노드. 예를 들어, <Page />와 같은 JSX 노드.
• options (optional): 서버 렌더링을 위한 객체.
  • identifierPrefix (optional): React가 useId에 의해 생성된 ID에 사용하는 문자열 접두사. 같은 페이지에서 여러 루트를 사용할 때 충돌을 피하는 데 유용함.

Returns

HTML 문자열을 반환함.

Caveats

• renderToStaticMarkup은 hydrate될 수 없음.

• renderToStaticMarkup은 Suspense를 제한적으로 지원함. 컴포넌트가 일시 중단되면 renderToStaticMarkup은 즉시 폴백을 HTML로 보냄.

• renderToStaticMarkup은 브라우저에서 작동하지만, 클라이언트 코드에서 사용하는 것은 권장하지 않음. 브라우저에서 컴포넌트를 HTML로 렌더링해야 하는 경우, DOM 노드로 렌더링하여 HTML을 가져올 것.

Usage

Rendering a non-interactive React tree as HTML to a string

renderToStaticMarkup을 호출하여 앱을 서버 응답과 함께 보낼 수 있는 HTML 문자열로 렌더링할 수 있음:

import { renderToStaticMarkup } from 'react-dom/server';

// The route handler syntax depends on your backend framework
app.use('/', (request, response) => {
  const html = renderToStaticMarkup(<Page />);
  response.send(html);
});

이렇게 하면 React 컴포넌트의 초기 비대화형 HTML 출력이 생성됨.

Pitfall

이 메서드는 hydrate될 수 없는 비대화형 HTML을 렌더링함. 이 메서드는 React를 간단한 정적 페이지 생성기로 사용하거나 이메일과 같이 완전히 정적인 콘텐츠를 렌더링할 때 유용함.

인터랙티브 앱은 서버에서 renderToString을 사용하고 클라이언트에서 hydrateRoot를 사용해야 함.

const stream = await renderToReadableStream(reactNode, options?)

Note

이 API는 Web Streams에 따라 달라짐. Node.js의 경우 renderToPipableStream을 사용할 것.

Reference

renderToReadableStream(reactNode, options?)

renderToReadableStream을 호출하여 React 트리를 HTML로 Readable Web Stream으로 렌더링할 수 있음.

import { renderToReadableStream } from 'react-dom/server';

async function handler(request) {
  const stream = await renderToReadableStream(<App />, {
    bootstrapScripts: ['/main.js']
  });
  return new Response(stream, {
    headers: { 'content-type': 'text/html' },
  });
}

클라이언트에서 hydrateRoot를 호출하여 서버에서 생성된 HTML을 상호작용이 가능하도록 할 수 있음.

Parameters

• reactNode: HTML로 렌더링하려는 React 노드. 예를 들어, <App />과 같은 JSX 요소. 이 요소는 전체 문서를 나타내야 하므로, App 컴포넌트는 <html> 태그를 렌더링해야 합니다.

• options (optional): 스트리밍 옵션이 있는 객체.

  • bootstrapScriptContent (optioanl): 지정하면 이 문자열이 인라인 <script> 태그에 배치됨.
  • bootstrapScripts (optioanl): 페이지에 표시할 <script> 태그의 문자열 URL 배열. hydrateRoot를 호출하는 <script>를 포함하려면 사용. 클라이언트에서 React를 전혀 실행하지 않으려면 생략.
  • bootstrapModules (optioanl): bootstrapScripts와 비슷하지만, 대신 <script type="module">을 내보냄.
  • identifierPrefix (optioanl): React가 useId에 의해 생성된 ID에 사용하는 문자열 접두사. 같은 페이지에서 여러 루트를 사용할 때 충돌을 피하는 데 유용함. hydrateRoot에 전달된 것과 동일해야 함.
  • namespaceURI (optioanl): 스트림의 루트 네임스페이스 URI가 포함된 문자열. 기본값은 일반 HTML. SVG의 경우 'http://www.w3.org/2000/svg', MathML의 경우 'http://www.w3.org/1998/Math/MathML'을 전달.
  • nonce (optioanl): script-src Content-Security-Policy에 대한 스크립트를 허용하는 nonce 문자열.
  • onError (optional): 복구가 가능하든 가능하지 않든, 서버 오류가 발생할 때마다 실행되는 callback. 기본적으로 console.error만 호출. 이 함수를 override 하여 크래시 리포트를 기록하는 경우, console.error를 계속 호출할 수 있어야 함. Shell이 실행되기 전에 state 코드를 조정하는 데 사용할 수도 있음.
  • progressiveChunkSize: 청크의 바이트 수.
    • 참고: 기본 휴리스틱
  • signal (optional): 서버 렌더링을 중단하고 나머지는 클라이언트에서 렌더링할 수 있는 중단 신호.

Returns

renderToReadableStream은 Promise를 반환함:

• Shell 렌더링에 성공하면, 해당 Promise는 Readable Web Stream으로 resolve 됨.
• 셸 렌더링에 실패하면, Promise는 reject 됨. 이를 사용하여 fallback shell을 출력함.

반환된 스트림에는 추가 property가 있음:

• allReady: Shell과 모든 추가 콘텐츠를 포함한 모든 렌더링이 완료될 때 resolve 되는 Promise. 크롤러 및 static generation을 위한 응답을 반환하기 전에 await stream.allReady 할 수 있음. 이렇게 하면 프로그레시브 로딩이 발생하지 않음. 스트림에는 최종 HTML이 포함됨.

Usage

Rendering a React tree as HTML to a Readable Web Stream

renderToReadableStream을 호출하여 React 트리를 HTML로 Readable Web Stream으로 렌더링할 수 있음:

import { renderToReadableStream } from 'react-dom/server';

async function handler(request) {
  const stream = await renderToReadableStream(<App />, {
    bootstrapScripts: ['/main.js']
  });
  return new Response(stream, {
    headers: { 'content-type': 'text/html' },
  });
}

루트 컴포넌트(위 코드에서는 <App />)와 함께 부트스트랩 <script> 경로 목록(위 코드에서는 ['/main.js'])을 제공해야 함. 루트 컴포넌트는 루트 <html> 태그를 포함한 전체 문서를 반환해야 함.

예를 들어:

export default function App() {
  return (
    <html>
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <link rel="stylesheet" href="/styles.css"></link>
        <title>My app</title>
      </head>
      <body>
        <Router />
      </body>
    </html>
  );
}

React는 doctype과 부트스트랩 <script> 태그를 결과 HTML 스트림에 삽입함:

<!DOCTYPE html>
<html>
  <!-- ... HTML from your components ... -->
</html>
<script src="/main.js" async=""></script>

클라이언트에서 부트스트랩 스크립트는 hydrateRoot를 호출하여 전체 document를 hydrate 해야 함:

import { hydrateRoot } from 'react-dom/client';
import App from './App.js';

hydrateRoot(document, <App />);

이렇게 하면 서버에서 생성된 HTML에 이벤트 리스너가 첨부되어 상호작용이 가능해짐.

DEEP DIVE: Reading CSS and JS asset paths from the build output

최종 에셋 URL(예: JavaScript 및 CSS 파일)은 빌드 후 해시 처리되는 경우가 많음. 예를 들어 styles.css 대신 최종적으로 styles.123456.css이 될 수 이씀. 정적 에셋 파일명을 해싱하면 동일한 에셋의 모든 개별 빌드에서 다른 파일명을 갖게 됨. 이렇게 하면 특정 이름의 파일은 콘텐츠를 변경하지 않으므로, 정적 에셋에 대한 장기 캐싱을 안전하게 활성화할 수 있어 유용함.

하지만 빌드가 끝날 때까지 에셋 URL을 모르는 경우 이를 소스 코드에 넣을 방법이 없음. 예를 들어, 앞서와 같이 JSX에 "/styles.css"를 하드코딩하면 작동하지 않음. 소스 코드에 포함되지 않도록 하려면 루트 컴포넌트가 prop으로 전달된 map에서 실제 파일명을 읽을 수 있음:

export default function App({ assetMap }) {
  return (
    <html>
      <head>
        ...
        <link rel="stylesheet" href={assetMap['styles.css']}></link>
        ...
      </head>
      ...
    </html>
  );
}

서버에서 <App assetMap={assetMap} />을 렌더링하고 에셋 URL과 함께 assetMap을 전달:

// You'd need to get this JSON from your build tooling, e.g. read it from the build output.
const assetMap = {
  'styles.css': '/styles.123456.css',
  'main.js': '/main.123456.js'
};
>
async function handler(request) {
  const stream = await renderToReadableStream(<App assetMap={assetMap} />, {
    bootstrapScripts: [assetMap['/main.js']]
  });
  return new Response(stream, {
    headers: { 'content-type': 'text/html' },
  });
}

서버에서 <App assetMap={assetMap} />를 렌더링하고 있으므로, 클라이언트에서도 assetMap을 사용하여 렌더링해야 hydration 오류를 방지할 수 있음. 다음과 같이 assetMap을 serialize하여 클라이언트에 전달할 수 있음:

// You'd need to get this JSON from your build tooling.
const assetMap = {
  'styles.css': '/styles.123456.css',
  'main.js': '/main.123456.js'
};
>
async function handler(request) {
  const stream = await renderToReadableStream(<App assetMap={assetMap} />, {
    // Careful: It's safe to stringify() this because this data isn't user-generated.
    bootstrapScriptContent: `window.assetMap = ${JSON.stringify(assetMap)};`,
    bootstrapScripts: [assetMap['/main.js']],
  });
  return new Response(stream, {
    headers: { 'content-type': 'text/html' },
  });
}

위의 예시에서 bootstrapScriptContent 옵션은 클라이언트에서 window.assetMap 변수를 설정하는 추가 인라인 <script> 태그를 추가함. 이렇게 하면 클라이언트 코드가 동일한 assetMap을 읽을 수 있음:

import { hydrateRoot } from 'react-dom/client';
import App from './App.js';
>
hydrateRoot(document, <App assetMap={window.assetMap} />);

클라이언트와 서버 모두 동일한 assetMap prop으로 App을 렌더링하므로 hydration 오류가 발생하지 않음.

Streaming more content as it loads

스트리밍을 사용하면 모든 데이터가 서버에 로드되기 전에도 사용자가 콘텐츠를 볼 수 있음. 예를 들어 표지, 친구 및 사진이 있는 사이드바, 게시물 목록이 표시되는 프로필 페이지가 있다면:

function ProfilePage() {
  return (
    <ProfileLayout>
      <ProfileCover />
      <Sidebar>
        <Friends />
        <Photos />
      </Sidebar>
      <Posts />
    </ProfileLayout>
  );
}

<Posts />에 대한 데이터를 로드하는 데 시간이 걸린다고 가정하면, 이상적으로는 게시물을 기다리지 않고 나머지 프로필 페이지 콘텐츠를 사용자에게 표시하고 싶을 것. 이렇게 하려면 Posts을 <Suspense> boundary로 감싸면 됨:

function ProfilePage() {
  return (
    <ProfileLayout>
      <ProfileCover />
      <Sidebar>
        <Friends />
        <Photos />
      </Sidebar>
      <Suspense fallback={<PostsGlimmer />}>
        <Posts />
      </Suspense>
    </ProfileLayout>
  );
}

이는 Posts가 데이터를 로드하기 전에 HTML 스트리밍을 시작하도록 React에게 지시함. React는 로딩 fallback(PostsGlimmer)을 위한 HTML을 먼저 전송한 다음, Posts가 데이터 로딩을 완료하면 로딩 fallback을 해당 HTML로 대체하는 인라인 <script> 태그와 함께 나머지 HTML을 전송함. 사용자 입장에서는 페이지가 먼저 PostsGlimmer로 표시되고 나중에 Posts가 대체됨.

<Suspense> boundary를 더 중첩하여 보다 세분화된 로딩 시퀀스를 만들 수 있음:

function ProfilePage() {
  return (
    <ProfileLayout>
      <ProfileCover />
      <Suspense fallback={<BigSpinner />}>
        <Sidebar>
          <Friends />
          <Photos />
        </Sidebar>
        <Suspense fallback={<PostsGlimmer />}>
          <Posts />
        </Suspense>
      </Suspense>
    </ProfileLayout>
  );
}

이 예시에서 React는 페이지 스트리밍을 더 일찍 시작할 수 있음. <Suspense> boundary로 감싸져 있지 않기 때문에 ProfileLayout과 ProfileCover는 먼저 렌더링을 완료해야 함. 그러나 Sidebar, Friends 또는 Photos에서 일부 데이터를 로드해야 하는 경우 React는 대신 BigSpinner fallback을 위한 HTML을 전송함. 그런 다음, 더 많은 데이터를 사용할 수 있게 될수록 모든 데이터가 표시될 때까지 더 많은 콘텐츠가 계속 표시됨.

스트리밍은 브라우저에서 React 자체가 로드되거나 앱이 상호작용이 가능해질 때까지 기다릴 필요가 없음. 서버의 HTML 콘텐츠는 <script> 태그가 로드되기 전에 점진적으로 표시됨.

Note

Suspense-enabled한 데이터 소스만 Suspense 컴포넌트를 활성화함. 여기에는 다음이 포함됨:

• Relay 및 Next.js와 같은 Suspense-enabled 프레임워크를 사용한 데이터 fetching
• lazy를 사용한 Lazy-loading 컴포넌트 코드
• use를 사용한 Prokise 값 읽기
  Suspense는 Effect 또는 이벤트 핸들러 내부에서 데이터를 가져오는 시점을 감지하지 못함.
  위의 Posts 컴포넌트에서 데이터를 로드하는 정확한 방법은 프레임워크에 따라 다름. Suspense-enabled 프레임워크를 사용하는 경우, 해당 프레임워크의 데이터 fetching 문서에서 자세한 내용을 확인할 수 있음.
  Suspense-enabled 프레임워크를 사용하지 않는 Suspense-enabled 데이터 fetching은 아직 지원되지 않음. Suspense-enabled 데이터 소스를 구현하기 위한 요구 사항은 불안정하고 문서화되어 있지 않음. 데이터 소스를 Suspense와 통합하기 위한 공식 API는 향후의 React 버전에서 출시될 예정임.

Specifying what goes into the shell

<Suspense> boundary를 벗어난 앱의 일부를 shell이라고 함:

function ProfilePage() {
  return (
    <ProfileLayout> // ✅
      <ProfileCover /> // ✅
      <Suspense fallback={<BigSpinner />}> // ✅
        <Sidebar>
          <Friends />
          <Photos />
        </Sidebar>
        <Suspense fallback={<PostsGlimmer />}>
          <Posts />
        </Suspense> // ✅
      </Suspense> // ✅
    </ProfileLayout>
  );
}

이는 사용자가 볼 수 있는 가장 빠른 로딩 상태를 결정함:

<ProfileLayout>
  <ProfileCover />
  <BigSpinner />
</ProfileLayout>

전체 앱을 <Suspense> boundary로 감싸면, shell에는 해당 스피너만 포함됨. 하지만 화면에 큰 스피너가 표시되는 것은 조금 더 기다려서 실제 레이아웃을 보는 것보다 느리고 성가시게 느껴질 수 있으므로 사용자 경험에 좋지 않음. 그렇기 때문에 일반적으로 shell이 최소한이지만 완성된 느낌을 주도록 (예: 전체 페이지 레이아웃의 skeleton) <Suspense> boundary를 배치하여 하는 것이 좋음.

renderToReadableStream에 대한 비동기 호출은 전체 shell이 렌더링되는 즉시 stream으로 resolve 됨. 보통은 해당 stream으로 응답을 생성하고 반환함으로써 스트리밍을 시작함:

async function handler(request) {
  const stream = await renderToReadableStream(<App />, {
    bootstrapScripts: ['/main.js']
  });
  return new Response(stream, {
    headers: { 'content-type': 'text/html' },
  });
}

stream이 반환될 때, 중첩된 <Suspense> boundary에 있는 컴포넌트가 여전히 데이터를 로드하고 있을 수 있음.

Logging crashes on the server

기본적으로 서버의 모든 오류는 콘솔에 기록됨. 이 동작을 재정의하여 크래시 보고서를 로그할 수 있음:

async function handler(request) {
  const stream = await renderToReadableStream(<App />, {
    bootstrapScripts: ['/main.js'],
    onError(error) {
      console.error(error);
      logServerCrashReport(error);
    }
  });
  return new Response(stream, {
    headers: { 'content-type': 'text/html' },
  });
}

사용자 정의 onError 구현을 제공하는 경우, 위와 같이 콘솔에 오류를 기록하는 것을 잊지 말 것.

Recovering from errors inside the shell

다음 예시에서는 shell에 ProfileLayout, ProfileCover 및 PostsGlimmer가 포함되어 있음:

function ProfilePage() {
  return (
    <ProfileLayout>
      <ProfileCover />
      <Suspense fallback={<PostsGlimmer />}>
        <Posts />
      </Suspense>
    </ProfileLayout>
  );
}

이러한 컴포넌트를 렌더링하는 동안 에러가 발생하면, React는 클라이언트에 보낼 의미 있는 HTML을 갖지 못함. 마지막 수단으로 서버 렌더링에 의존하지 않는 fallback HTML을 보내려면 renderToReadableStream 호출을 try...catch로 감쌀 것:

async function handler(request) {
  try {
    const stream = await renderToReadableStream(<App />, {
      bootstrapScripts: ['/main.js'],
      onError(error) {
        console.error(error);
        logServerCrashReport(error);
      }
    });
    return new Response(stream, {
      headers: { 'content-type': 'text/html' },
    });
  } catch (error) {
    return new Response('<h1>Something went wrong</h1>', {
      status: 500,
      headers: { 'content-type': 'text/html' },
    });
  }
}

Shell을 생성하는 동안 오류가 발생하면 onError와 catch 블록이 모두 실행됨. 오류를 보고하려면 onError를 사용하고, 대체 HTML 문서를 보내려면 catch 블록을 사용할 것. Fallback HTML이 오류 페이지일 필요는 없음. 대신 클라이언트에서만 앱을 렌더링하는 대체 shell을 포함할 수 있음.

Recovering from errors outside the shell

다음 예제에서 <Posts /> 컴포넌트는 <Suspense>로 감싸져 있으므로 shell의 일부가 아님:

function ProfilePage() {
  return (
    <ProfileLayout>
      <ProfileCover />
      <Suspense fallback={<PostsGlimmer />}>
        <Posts />
      </Suspense>
    </ProfileLayout>
  );
}

Posts 컴포넌트 또는 그 내부 어딘가에서 오류가 발생하면 React가 복구를 시도함:

1. 가장 가까운 <Suspense> boundary(PostsGlimmer)에 대한 로딩 fallback을 HTML에 내보냄.
2. 더 이상 서버에서 Posts 콘텐츠를 렌더링하는 시도를 "포기"함.
3. JavaScript 코드가 클라이언트에서 로드되면 React는 클라이언트에서 Posts 렌더링을 다시 시도함.

클라이언트에서도 Posts 렌더링에 실패하면, React는 클라이언트에서 오류를 발생시킴. 렌더링 중에 발생하는 모든 에러와 마찬가지로, 가장 가까운 상위 error boundary에 따라 사용자에게 에러를 표시하는 방법이 결정됨. 실제로는 오류를 복구할 수 없다는 것이 확실해질 때까지 사용자에게 로딩 indicator가 표시된다는 의미.

클라이언트에서 Posts 렌더링에 성공하면, 서버의 로딩 fallback이 클라이언트 렌더링 출력으로 대체됨. 사용자는 서버 오류가 발생했다는 사실을 알 수 없음. 그러나 서버의 onError callback 및 클라이언트의 onRecoverableError callback이 실행되어 오류에 대한 알림을 받을 수 있음.

Setting the status code

스트리밍에는 장단점이 있음. 사용자가 콘텐츠를 더 빨리 볼 수 있도록 가능한 한 빨리 페이지 스트리밍을 시작하고 싶을 수 있음. 하지만 스트리밍을 시작하면 더 이상 응답 상태 코드를 설정할 수 없음.

앱을 shell(모든 <Suspense> boundary 외부)과 나머지 콘텐츠로 나누면 이 문제의 일부를 이미 해결한 것. Shell에서 오류가 발생하면 오류 상태 코드를 설정할 수 있는 catch 블록이 실행됨. 그렇지 않으면 앱이 클라이언트에서 복구될 수 있으므로 "OK"를 보낼 수 있음.

async function handler(request) {
  try {
    const stream = await renderToReadableStream(<App />, {
      bootstrapScripts: ['/main.js'],
      onError(error) {
        console.error(error);
        logServerCrashReport(error);
      }
    });
    return new Response(stream, {
      status: 200,
      headers: { 'content-type': 'text/html' },
    });
  } catch (error) {
    return new Response('<h1>Something went wrong</h1>', {
      status: 500,
      headers: { 'content-type': 'text/html' },
    });
  }
}

Shell 외부의 컴포넌트(즉, <Suspense> boundary 내부)에서 에러가 발생해도 React는 렌더링을 멈추지 않음. 즉, onError 콜백이 실행되지만 코드는 catch 블록에 들어가지 않고 계속 실행됨. 이는 위에서 설명한 대로 React가 클라이언트에서 해당 오류를 복구하려고 시도하기 때문.

그러나 원하는 경우 오류가 발생했다는 사실을 사용하여 상태 코드를 설정할 수 있음:

async function handler(request) {
  try {
    let didError = false;
    const stream = await renderToReadableStream(<App />, {
      bootstrapScripts: ['/main.js'],
      onError(error) {
        didError = true;
        console.error(error);
        logServerCrashReport(error);
      }
    });
    return new Response(stream, {
      status: didError ? 500 : 200,
      headers: { 'content-type': 'text/html' },
    });
  } catch (error) {
    return new Response('<h1>Something went wrong</h1>', {
      status: 500,
      headers: { 'content-type': 'text/html' },
    });
  }
}

이 방법은 초기 shell 콘텐츠를 생성하는 동안 발생한 shell 외부의 오류만 포착하므로 완전한 것은 아님. 일부 콘텐츠에서 오류가 발생했는지 여부를 파악하는 것이 중요한 경우 해당 콘텐츠를 shell로 이동하면 됨.

Handling different errors in different ways

자신만의 Error 서브클래스를 생성하고 instanceof 연산자를 사용하여 어떤 에러가 발생하는지 확인할 수 있음. 예를 들어, 사용자 정의 NotFoundError를 정의하고 컴포넌트에서 이를 발생시킬 수 있음. 그런 다음 오류를 onError에 저장하고 오류 유형에 따라 응답을 반환하기 전에 다른 작업을 수행할 수 있음:

async function handler(request) {
  let didError = false;
  let caughtError = null;

  function getStatusCode() {
    if (didError) {
      if (caughtError instanceof NotFoundError) {
        return 404;
      } else {
        return 500;
      }
    } else {
      return 200;
    }
  }

  try {
    const stream = await renderToReadableStream(<App />, {
      bootstrapScripts: ['/main.js'],
      onError(error) {
        didError = true;
        caughtError = error;
        console.error(error);
        logServerCrashReport(error);
      }
    });
    return new Response(stream, {
      status: getStatusCode(),
      headers: { 'content-type': 'text/html' },
    });
  } catch (error) {
    return new Response('<h1>Something went wrong</h1>', {
      status: getStatusCode(),
      headers: { 'content-type': 'text/html' },
    });
  }
}

Shell을 내보내고 스트리밍을 시작하면 상태 코드를 변경할 수 없다는 점에 유의할 것.

Waiting for all content to load for crawlers and static generation

스트리밍은 콘텐츠가 제공될 때 바로 볼 수 있기 때문에 더 나은 사용자 경험을 제공함.

그러나 크롤러가 페이지를 방문하거나 빌드 시점에 페이지를 생성하는 경우, 모든 콘텐츠를 점진적으로 표시하는 대신 모든 콘텐츠를 먼저 로드한 다음 최종 HTML 출력을 생성하는 것이 좋음.

stream.allReady Promise를 awaiting 해서 모든 콘텐츠가 로드될 때까지 기다릴 수 있음:

async function handler(request) {
  try {
    let didError = false;
    const stream = await renderToReadableStream(<App />, {
      bootstrapScripts: ['/main.js'],
      onError(error) {
        didError = true;
        console.error(error);
        logServerCrashReport(error);
      }
    });
    let isCrawler = // ... depends on your bot detection strategy ...
    if (isCrawler) {
      await stream.allReady;
    }
    return new Response(stream, {
      status: didError ? 500 : 200,
      headers: { 'content-type': 'text/html' },
    });
  } catch (error) {
    return new Response('<h1>Something went wrong</h1>', {
      status: 500,
      headers: { 'content-type': 'text/html' },
    });
  }
}

일반 방문자는 점진적으로 로드되는 콘텐츠 스트림을 받게 됨. 크롤러는 모든 데이터가 로드된 후 최종 HTML 출력을 받게 됨. 그러나 이는 크롤러가 모든 데이터를 기다려야 한다는 것을 의미하며, 그 중 일부는 로드 속도가 느리거나 오류가 발생할 수 있음. 앱에 따라 크롤러에도 shell을 보내도록 선택할 수 있음.

Aborting server rendering

시간 초과 후 서버가 렌더링을 강제로 "포기"하도록 할 수도 있음:

async function handler(request) {
  try {
    const controller = new AbortController();
    setTimeout(() => {
      controller.abort();
    }, 10000);

    const stream = await renderToReadableStream(<App />, {
      signal: controller.signal,
      bootstrapScripts: ['/main.js'],
      onError(error) {
        didError = true;
        console.error(error);
        logServerCrashReport(error);
      }
    });
    // ...

React는 나머지 로딩 fallback을 HTML로 flush하고 나머지는 클라이언트에서 렌더링을 시도함.

const { pipe, abort } = renderToPipeableStream(reactNode, options?)

Note

이 API는 Node.js에만 해당됨. Deno 및 최신 엣지 런타임과 같은 웹 스트림이 있는 환경에서는 대신 renderToReadableStream을 사용해야 함.

Reference

renderToPipeableStream(reactNode, options?)

renderToPipeableStream을 호출하여 React 트리를 HTML로 Node.js 스트림으로 렌더링할 수 있음.

import { renderToPipeableStream } from 'react-dom/server';

const { pipe } = renderToPipeableStream(<App />, {
  bootstrapScripts: ['/main.js'],
  onShellReady() {
    response.setHeader('content-type', 'text/html');
    pipe(response);
  }
});

클라이언트에서 hydrateRoot를 호출하여 서버에서 생성된 HTML을 상호작용이 가능하도록 할 수 있음.

Parameters

• reactNode: HTML로 렌더링하려는 React 노드. 예를 들어, <App />과 같은 JSX 요소. 이 요소는 전체 문서를 나타내야 하므로, App 컴포넌트는 <html> 태그를 렌더링해야 합니다.

• options (optional): 스트리밍 옵션이 있는 객체.

  • bootstrapScriptContent (optioanl): 지정하면 이 문자열이 인라인 <script> 태그에 배치됨.
  • bootstrapScripts (optioanl): 페이지에 표시할 <script> 태그의 문자열 URL 배열. hydrateRoot를 호출하는 <script>를 포함하려면 사용. 클라이언트에서 React를 전혀 실행하지 않으려면 생략.
  • bootstrapModules (optioanl): bootstrapScripts와 비슷하지만, 대신 <script type="module">을 내보냄.
  • identifierPrefix (optioanl): React가 useId에 의해 생성된 ID에 사용하는 문자열 접두사. 같은 페이지에서 여러 루트를 사용할 때 충돌을 피하는 데 유용함. hydrateRoot에 전달된 것과 동일해야 함.
  • namespaceURI (optioanl): 스트림의 루트 네임스페이스 URI가 포함된 문자열. 기본값은 일반 HTML. SVG의 경우 'http://www.w3.org/2000/svg', MathML의 경우 'http://www.w3.org/1998/Math/MathML'을 전달.
  • nonce (optioanl): script-src Content-Security-Policy에 대한 스크립트를 허용하는 nonce 문자열.
  • onAllReady (optional): shell과 모든 추가 콘텐츠를 포함하여 모든 렌더링이 완료되면 실행되는 callback. 크롤러 및 static generation에 onShellReady 대신 사용할 수 있음. 여기서 스트리밍을 시작하면 프로그레시브 로딩이 발생하지 않음. 스트림에는 최종 HTML이 포함됨.
  • onError (optional): 복구가 가능하든 가능하지 않든, 서버 오류가 발생할 때마다 실행되는 callback. 기본적으로 console.error만 호출. 이 함수를 override 하여 크래시 리포트를 기록하는 경우, console.error를 계속 호출할 수 있어야 함. Shell이 실행되기 전에 state 코드를 조정하는 데 사용할 수도 있음.
  • onShellReady (optional): 초기 shell이 렌더링된 직후에 실행되는 callback. 여기에서 state 코드를 설정하고 pipe를 호출하여 스트리밍을 시작할 수 있음. React는 HTML 로딩 fallback을 콘텐츠로 대체하는 인라인 <script> 태그와 함께 shell 뒤에 추가 콘텐츠를 스트리밍함.
  • onShellError (optional): 초기 shell을 렌더링하는 데 오류가 발생하면 호출되는 callback. 오류를 argument로 받음. 스트림에서 아직 바이트가 전송되지 않았고, onShellReady나 onAllReady도 호출되지 않으므로, fallback HTML shell을 출력할 수 있음.
  • progressiveChunkSize (optional): 청크의 바이트 수.
    • 참고: 기본 휴리스틱

Returns

renderToPipeableStream 두 개의 메서드가 있는 객체를 반환함:

• pipe는 HTML을 제공된 쓰기 가능한 Node.js 스트림으로 출력함. 스트리밍을 사용하려면 onShellReady에서, 크롤러와 static generation을 사용하려면 onAllReady에서 pipe를 호출할 것.
• abort를 사용하면 서버 렌더링을 중단하고 나머지는 클라이언트에서 렌더링할 수 있음.

Usage

Rendering a React tree as HTML to a Node.js Stream

renderToPipeableStream을 호출하여 React 트리를 HTML로 Node.js 스트림으로 렌더링할 수 있음:

import { renderToPipeableStream } from 'react-dom/server';

// The route handler syntax depends on your backend framework
app.use('/', (request, response) => {
  const { pipe } = renderToPipeableStream(<App />, {
    bootstrapScripts: ['/main.js'],
    onShellReady() {
      response.setHeader('content-type', 'text/html');
      pipe(response);
    }
  });
});

루트 컴포넌트(위 코드에서는 <App />)와 함께 부트스트랩 <스크립트> 경로 목록(위 코드에서는 ['/main.js'])을 제공해야 함. 루트 컴포넌트는 루트 <html> 태그를 포함한 전체 문서를 반환해야 함.

예를 들어:

export default function App() {
  return (
    <html>
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <link rel="stylesheet" href="/styles.css"></link>
        <title>My app</title>
      </head>
      <body>
        <Router />
      </body>
    </html>
  );
}

React는 doctype과 부트스트랩 <script> 태그를 결과 HTML 스트림에 삽입함:

<!DOCTYPE html>
<html>
  <!-- ... HTML from your components ... -->
</html>
<script src="/main.js" async=""></script>

클라이언트에서 부트스트랩 스크립트는 hydrateRoot를 호출하여 전체 document를 hydrate 해야 함:

import { hydrateRoot } from 'react-dom/client';
import App from './App.js';

hydrateRoot(document, <App />);

이렇게 하면 서버에서 생성된 HTML에 이벤트 리스너가 첨부되어 상호작용이 가능해짐.

DEEP DIVE: Reading CSS and JS asset paths from the build output

최종 에셋 URL(예: JavaScript 및 CSS 파일)은 빌드 후 해시 처리되는 경우가 많음. 예를 들어 styles.css 대신 최종적으로 styles.123456.css이 될 수 이씀. 정적 에셋 파일명을 해싱하면 동일한 에셋의 모든 개별 빌드에서 다른 파일명을 갖게 됨. 이렇게 하면 특정 이름의 파일은 콘텐츠를 변경하지 않으므로, 정적 에셋에 대한 장기 캐싱을 안전하게 활성화할 수 있어 유용함.

하지만 빌드가 끝날 때까지 에셋 URL을 모르는 경우 이를 소스 코드에 넣을 방법이 없음. 예를 들어, 앞서와 같이 JSX에 "/styles.css"를 하드코딩하면 작동하지 않음. 소스 코드에 포함되지 않도록 하려면 루트 컴포넌트가 prop으로 전달된 map에서 실제 파일명을 읽을 수 있음:

export default function App({ assetMap }) {
  return (
    <html>
      <head>
        ...
        <link rel="stylesheet" href={assetMap['styles.css']}></link>
        ...
      </head>
      ...
    </html>
  );
}

서버에서 <App assetMap={assetMap} />을 렌더링하고 에셋 URL과 함께 assetMap을 전달:

// You'd need to get this JSON from your build tooling, e.g. read it from the build output.
const assetMap = {
  'styles.css': '/styles.123456.css',
  'main.js': '/main.123456.js'
};
>
app.use('/', (request, response) => {
  const { pipe } = renderToPipeableStream(<App assetMap={assetMap} />, {
    bootstrapScripts: [assetMap['main.js']],
    onShellReady() {
      response.setHeader('content-type', 'text/html');
      pipe(response);
    }
  });
});

서버에서 <App assetMap={assetMap} />를 렌더링하고 있으므로, 클라이언트에서도 assetMap을 사용하여 렌더링해야 hydration 오류를 방지할 수 있음. 다음과 같이 assetMap을 serialize하여 클라이언트에 전달할 수 있음:

// You'd need to get this JSON from your build tooling.
const assetMap = {
  'styles.css': '/styles.123456.css',
  'main.js': '/main.123456.js'
};
>
app.use('/', (request, response) => {
  const { pipe } = renderToPipeableStream(<App assetMap={assetMap} />, {
    // Careful: It's safe to stringify() this because this data isn't user-generated.
    bootstrapScriptContent: `window.assetMap = ${JSON.stringify(assetMap)};`,
    bootstrapScripts: [assetMap['main.js']],
    onShellReady() {
      response.setHeader('content-type', 'text/html');
      pipe(response);
    }
  });
});

위의 예시에서 bootstrapScriptContent 옵션은 클라이언트에서 window.assetMap 변수를 설정하는 추가 인라인 <script> 태그를 추가함. 이렇게 하면 클라이언트 코드가 동일한 assetMap을 읽을 수 있음:

import { hydrateRoot } from 'react-dom/client';
import App from './App.js';
>
hydrateRoot(document, <App assetMap={window.assetMap} />);

클라이언트와 서버 모두 동일한 assetMap prop으로 App을 렌더링하므로 hydration 오류가 발생하지 않음.

Streaming more content as it loads

스트리밍을 사용하면 모든 데이터가 서버에 로드되기 전에도 사용자가 콘텐츠를 볼 수 있음. 예를 들어 표지, 친구 및 사진이 있는 사이드바, 게시물 목록이 표시되는 프로필 페이지가 있다면:

function ProfilePage() {
  return (
    <ProfileLayout>
      <ProfileCover />
      <Sidebar>
        <Friends />
        <Photos />
      </Sidebar>
      <Posts />
    </ProfileLayout>
  );
}

<Posts />에 대한 데이터를 로드하는 데 시간이 걸린다고 가정하면, 이상적으로는 게시물을 기다리지 않고 나머지 프로필 페이지 콘텐츠를 사용자에게 표시하고 싶을 것. 이렇게 하려면 Posts을 <Suspense> boundary로 감싸면 됨:

function ProfilePage() {
  return (
    <ProfileLayout>
      <ProfileCover />
      <Sidebar>
        <Friends />
        <Photos />
      </Sidebar>
      <Suspense fallback={<PostsGlimmer />}>
        <Posts />
      </Suspense>
    </ProfileLayout>
  );
}

이는 Posts가 데이터를 로드하기 전에 HTML 스트리밍을 시작하도록 React에게 지시함. React는 로딩 fallback(PostsGlimmer)을 위한 HTML을 먼저 전송한 다음, Posts가 데이터 로딩을 완료하면 로딩 fallback을 해당 HTML로 대체하는 인라인 <script> 태그와 함께 나머지 HTML을 전송함. 사용자 입장에서는 페이지가 먼저 PostsGlimmer로 표시되고 나중에 Posts가 대체됨.

<Suspense> boundary를 더 중첩하여 보다 세분화된 로딩 시퀀스를 만들 수 있음:

function ProfilePage() {
  return (
    <ProfileLayout>
      <ProfileCover />
      <Suspense fallback={<BigSpinner />}>
        <Sidebar>
          <Friends />
          <Photos />
        </Sidebar>
        <Suspense fallback={<PostsGlimmer />}>
          <Posts />
        </Suspense>
      </Suspense>
    </ProfileLayout>
  );
}

이 예시에서 React는 페이지 스트리밍을 더 일찍 시작할 수 있음. <Suspense> boundary로 감싸져 있지 않기 때문에 ProfileLayout과 ProfileCover는 먼저 렌더링을 완료해야 함. 그러나 Sidebar, Friends 또는 Photos에서 일부 데이터를 로드해야 하는 경우 React는 대신 BigSpinner fallback을 위한 HTML을 전송함. 그런 다음, 더 많은 데이터를 사용할 수 있게 될수록 모든 데이터가 표시될 때까지 더 많은 콘텐츠가 계속 표시됨.

스트리밍은 브라우저에서 React 자체가 로드되거나 앱이 상호작용이 가능해질 때까지 기다릴 필요가 없음. 서버의 HTML 콘텐츠는 <script> 태그가 로드되기 전에 점진적으로 표시됨.

Note

Suspense-enabled한 데이터 소스만 Suspense 컴포넌트를 활성화함. 여기에는 다음이 포함됨:

• Relay 및 Next.js와 같은 Suspense-enabled 프레임워크를 사용한 데이터 fetching
• lazy를 사용한 Lazy-loading 컴포넌트 코드
• use를 사용한 Prokise 값 읽기
  Suspense는 Effect 또는 이벤트 핸들러 내부에서 데이터를 가져오는 시점을 감지하지 못함.
  위의 Posts 컴포넌트에서 데이터를 로드하는 정확한 방법은 프레임워크에 따라 다름. Suspense-enabled 프레임워크를 사용하는 경우, 해당 프레임워크의 데이터 fetching 문서에서 자세한 내용을 확인할 수 있음.
  Suspense-enabled 프레임워크를 사용하지 않는 Suspense-enabled 데이터 fetching은 아직 지원되지 않음. Suspense-enabled 데이터 소스를 구현하기 위한 요구 사항은 불안정하고 문서화되어 있지 않음. 데이터 소스를 Suspense와 통합하기 위한 공식 API는 향후의 React 버전에서 출시될 예정임.

Specifying what goes into the shell

<Suspense> boundary를 벗어난 앱의 일부를 shell이라고 함:

function ProfilePage() {
  return (
    <ProfileLayout> // ✅
      <ProfileCover /> // ✅
      <Suspense fallback={<BigSpinner />}> // ✅
        <Sidebar>
          <Friends />
          <Photos />
        </Sidebar>
        <Suspense fallback={<PostsGlimmer />}>
          <Posts />
        </Suspense> // ✅
      </Suspense> // ✅
    </ProfileLayout>
  );
}

이는 사용자가 볼 수 있는 가장 빠른 로딩 상태를 결정함:

<ProfileLayout>
  <ProfileCover />
  <BigSpinner />
</ProfileLayout>

전체 앱을 <Suspense> boundary로 감싸면, shell에는 해당 스피너만 포함됨. 하지만 화면에 큰 스피너가 표시되는 것은 조금 더 기다려서 실제 레이아웃을 보는 것보다 느리고 성가시게 느껴질 수 있으므로 사용자 경험에 좋지 않음. 그렇기 때문에 일반적으로 shell이 최소한이지만 완성된 느낌을 주도록 (예: 전체 페이지 레이아웃의 skeleton) <Suspense> boundary를 배치하여 하는 것이 좋음.

전체 shell이 렌더링되면 onShellReady callback이 실행됨. 보통 이때 스트리밍을 시작함:

const { pipe } = renderToPipeableStream(<App />, {
  bootstrapScripts: ['/main.js'],
  onShellReady() {
    response.setHeader('content-type', 'text/html');
    pipe(response);
  }
});

onShellReady가 실행될 때 중첩된 <Suspense> boundary에 있는 컴포넌트는 여전히 데이터를 로드하고 있을 수 있음.

Logging crashes on the server

기본적으로 서버의 모든 오류는 콘솔에 기됨. 이 동작을 재정의하여 크래시 보고서를 로그할 수 있음:

const { pipe } = renderToPipeableStream(<App />, {
  bootstrapScripts: ['/main.js'],
  onShellReady() {
    response.setHeader('content-type', 'text/html');
    pipe(response);
  },
  onError(error) {
    console.error(error);
    logServerCrashReport(error);
  }
});

사용자 정의 onError 구현을 제공하는 경우, 위와 같이 콘솔에 오류를 기록하는 것을 잊지 말 것.

Recovering from errors inside the shell

다음 예시에서는 shell에 ProfileLayout, ProfileCover 및 PostsGlimmer가 포함되어 있음:

function ProfilePage() {
  return (
    <ProfileLayout>
      <ProfileCover />
      <Suspense fallback={<PostsGlimmer />}>
        <Posts />
      </Suspense>
    </ProfileLayout>
  );
}

이러한 컴포넌트를 렌더링하는 동안 에러가 발생하면, React는 클라이언트에 보낼 의미 있는 HTML을 갖지 못함. 마지막 수단으로 서버 렌더링에 의존하지 않는 fallback HTML을 보내려면 onShellError를 override 할 것:

const { pipe } = renderToPipeableStream(<App />, {
  bootstrapScripts: ['/main.js'],
  onShellReady() {
    response.setHeader('content-type', 'text/html');
    pipe(response);
  },
  onShellError(error) {
    response.statusCode = 500;
    response.setHeader('content-type', 'text/html');
    response.send('<h1>Something went wrong</h1>'); 
  },
  onError(error) {
    console.error(error);
    logServerCrashReport(error);
  }
});

Shell을 생성하는 동안 오류가 발생하면 onError와 onShellError가 모두 실행됨. 오류 보고하려면 onError를 사용하고, 대체 HTML 문서를 보내려면 onShellError를 사용할 것. Fallback HTML이 오류 페이지일 필요는 없음. 대신 클라이언트에서만 앱을 렌더링하는 대체 shell을 포함할 수 있음.

Recovering from errors outside the shell

다음 예제에서 <Posts /> 컴포넌트는 <Suspense>로 감싸져 있으므로 shell의 일부가 아님:

function ProfilePage() {
  return (
    <ProfileLayout>
      <ProfileCover />
      <Suspense fallback={<PostsGlimmer />}>
        <Posts />
      </Suspense>
    </ProfileLayout>
  );
}

Posts 컴포넌트 또는 그 내부 어딘가에서 오류가 발생하면 React가 복구를 시도함:

1. 가장 가까운 <Suspense> boundary(PostsGlimmer)에 대한 로딩 fallback을 HTML에 내보냄.
2. 더 이상 서버에서 Posts 콘텐츠를 렌더링하는 시도를 "포기"함.
3. JavaScript 코드가 클라이언트에서 로드되면 React는 클라이언트에서 Posts 렌더링을 다시 시도함.

클라이언트에서도 Posts 렌더링에 실패하면, React는 클라이언트에서 오류를 발생시킴. 렌더링 중에 발생하는 모든 에러와 마찬가지로, 가장 가까운 상위 error boundary에 따라 사용자에게 에러를 표시하는 방법이 결정됨. 실제로는 오류를 복구할 수 없다는 것이 확실해질 때까지 사용자에게 로딩 indicator가 표시된다는 의미.

클라이언트에서 Posts 렌더링에 성공하면, 서버의 로딩 fallback이 클라이언트 렌더링 출력으로 대체됨. 사용자는 서버 오류가 발생했다는 사실을 알 수 없음. 그러나 서버의 onError callback 및 클라이언트의 onRecoverableError callback이 실행되어 오류에 대한 알림을 받을 수 있음.

Setting the status code

스트리밍에는 장단점이 있음. 사용자가 콘텐츠를 더 빨리 볼 수 있도록 가능한 한 빨리 페이지 스트리밍을 시작하고 싶을 수 있음. 하지만 스트리밍을 시작하면 더 이상 응답 상태 코드를 설정할 수 없음.

앱을 shell(모든 <Suspense> boundary 외부)과 나머지 콘텐츠로 나누면 이 문제의 일부를 이미 해결한 것. Shell에서 오류가 발생하면 오류 상태 코드를 설정할 수 있는 onShellError callback을 받게 됨. 그렇지 않으면 앱이 클라이언트에서 복구될 수 있으므로 "OK"를 보낼 수 있음.

const { pipe } = renderToPipeableStream(<App />, {
  bootstrapScripts: ['/main.js'],
  onShellReady() {
    response.statusCode = 200;
    response.setHeader('content-type', 'text/html');
    pipe(response);
  },
  onShellError(error) {
    response.statusCode = 500;
    response.setHeader('content-type', 'text/html');
    response.send('<h1>Something went wrong</h1>'); 
  },
  onError(error) {
    console.error(error);
    logServerCrashReport(error);
  }
});

Shell 외부의 컴포넌트(즉, <Suspense> boundary 내부)에서 에러가 발생해도 React는 렌더링을 멈추지 않음. 즉, onError 콜백이 실행되지만 여전히 onShellError 대신 onShellReady가 반환됨. 이는 위에서 설명한 대로 React가 클라이언트에서 해당 오류를 복구하려고 시도하기 때문.

그러나 원하는 경우 오류가 발생했다는 사실을 사용하여 상태 코드를 설정할 수 있음:

let didError = false;

const { pipe } = renderToPipeableStream(<App />, {
  bootstrapScripts: ['/main.js'],
  onShellReady() {
    response.statusCode = didError ? 500 : 200;
    response.setHeader('content-type', 'text/html');
    pipe(response);
  },
  onShellError(error) {
    response.statusCode = 500;
    response.setHeader('content-type', 'text/html');
    response.send('<h1>Something went wrong</h1>'); 
  },
  onError(error) {
    didError = true;
    console.error(error);
    logServerCrashReport(error);
  }
});

이 방법은 초기 shell 콘텐츠를 생성하는 동안 발생한 shell 외부의 오류만 포착하므로 완전한 것은 아님. 일부 콘텐츠에서 오류가 발생했는지 여부를 파악하는 것이 중요한 경우 해당 콘텐츠를 shell로 이동하면 됨.

Handling different errors in different ways

자신만의 Error 서브클래스를 생성하고 instanceof 연산자를 사용하여 어떤 에러가 발생하는지 확인할 수 있음. 예를 들어, 사용자 정의 NotFoundError를 정의하고 컴포넌트에서 이를 발생시킬 수 있음. 그러면 오류 유형에 따라 onError, onShellReady, onShellError callback이 다른 작업을 수행할 수 있음:

let didError = false;
let caughtError = null;

function getStatusCode() {
  if (didError) {
    if (caughtError instanceof NotFoundError) {
      return 404;
    } else {
      return 500;
    }
  } else {
    return 200;
  }
}

const { pipe } = renderToPipeableStream(<App />, {
  bootstrapScripts: ['/main.js'],
  onShellReady() {
    response.statusCode = getStatusCode();
    response.setHeader('content-type', 'text/html');
    pipe(response);
  },
  onShellError(error) {
   response.statusCode = getStatusCode();
   response.setHeader('content-type', 'text/html');
   response.send('<h1>Something went wrong</h1>'); 
  },
  onError(error) {
    didError = true;
    caughtError = error;
    console.error(error);
    logServerCrashReport(error);
  }
});

Shell을 내보내고 스트리밍을 시작하면 상태 코드를 변경할 수 없다는 점에 유의할 것.

Waiting for all content to load for crawlers and static generation

스트리밍은 콘텐츠가 제공될 때 바로 볼 수 있기 때문에 더 나은 사용자 경험을 제공함.

그러나 크롤러가 페이지를 방문하거나 빌드 시점에 페이지를 생성하는 경우, 모든 콘텐츠를 점진적으로 표시하는 대신 모든 콘텐츠를 먼저 로드한 다음 최종 HTML 출력을 생성하는 것이 좋음.

onAllReady callback을 사용하여 모든 콘텐츠가 로드될 때까지 기다릴 수 있음:

let didError = false;
let isCrawler = // ... depends on your bot detection strategy ...

const { pipe } = renderToPipeableStream(<App />, {
  bootstrapScripts: ['/main.js'],
  onShellReady() {
    if (!isCrawler) {
      response.statusCode = didError ? 500 : 200;
      response.setHeader('content-type', 'text/html');
      pipe(response);
    }
  },
  onShellError(error) {
    response.statusCode = 500;
    response.setHeader('content-type', 'text/html');
    response.send('<h1>Something went wrong</h1>'); 
  },
  onAllReady() {
    if (isCrawler) {
      response.statusCode = didError ? 500 : 200;
      response.setHeader('content-type', 'text/html');
      pipe(response);      
    }
  },
  onError(error) {
    didError = true;
    console.error(error);
    logServerCrashReport(error);
  }
});

일반 방문자는 점진적으로 로드되는 콘텐츠 스트림을 받게 됨. 크롤러는 모든 데이터가 로드된 후 최종 HTML 출력을 받게 됨. 그러나 이는 크롤러가 모든 데이터를 기다려야 한다는 것을 의미하며, 그 중 일부는 로드 속도가 느리거나 오류가 발생할 수 있음. 앱에 따라 크롤러에도 shell을 보내도록 선택할 수 있음.

Aborting server rendering

시간 초과 후 서버가 렌더링을 강제로 "포기"하도록 할 수도 있음:

const { pipe, abort } = renderToPipeableStream(<App />, {
  // ...
});

setTimeout(() => {
  abort();
}, 10000);

React는 나머지 로딩 fallback을 HTML로 flush하고 나머지는 클라이언트에서 렌더링을 시도함.

참고

• [Node.js][노드] stream(스트림) 이란??

const root = hydrateRoot(domNode, reactNode, options?)

Reference

hydrateRoot(domNode, reactNode, options?)

hydrateRoot를 호출해서 서버 환경에서 React가 이미 렌더링한 기존 HTML에 React를 "첨부"할 수 있음.

import { hydrateRoot } from 'react-dom/client';

const domNode = document.getElementById('root');
const root = hydrateRoot(domNode, reactNode);

React는 domNode 내부에 존재하는 HTML에 첨부되어 그 안에 있는 DOM을 관리함. React로 완전히 빌드된 앱에는 일반적으로 하나의 루트 컴포넌트와 함께 하나의 hydrateRoot 호출만 있음.

Parameters

• domNode: 서버에서 루트 요소로 렌더링된 DOM 요소.

• reactNode: 기존 HTML을 렌더링하는 데 사용된 "React 노드". 일반적으로 renderToPipeableStream(<App />)과 같은 ReactDOM Server 메서드로 렌더링된 <App />과 같은 JSX 조각임.

• options (optional): React 루트에 대한 옵션이 있는 객체.

  • onRecoverableError (optional): React가 오류로부터 자동으로 복구할 때 호출되는 callback.
  • identifierPrefix (optional): React가 useId에 의해 생성된 ID에 사용하는 문자열 접두사. 같은 페이지에서 여러 루트를 사용할 때 충돌을 피하는 데 유용함. 서버에서 사용하는 것과 동일한 접두사여야 함.

Returns

render와 unmount 두 가지 메서드가 있는 객체를 반환함.

Caveats

• hydrateRoot()는 렌더링된 콘텐츠가 서버에서 렌더링된 콘텐츠와 동일할 것으로 기대함. 불일치는 버그로 간주하고 수정해야 함.

• 개발 모드에서 React는 hydration 중 불일치에 대해 경고함. 불일치하는 경우 attribute 차이가 패치될 것이라는 보장이 없음. 이는 성능상의 이유로 중요한데, 대부분의 앱에서 불일치가 발생하는 경우는 드물므로 모든 마크업의 유효성을 검사하는 것은 엄청나게 많은 비용이 들기 때문임.

• 앱에 hydrateRoot 호출이 하나만 있을 가능성이 높음. 프레임워크를 사용하는 경우 프레임워크가 이 호출을 대신 수행할 수 있음.

• 앱이 이미 렌더링된 HTML 없이 클라이언트로 렌더링되는 경우, hydrateRoot() 사용은 지원되지 않음. 대신 createRoot()를 사용할 것.

root.render(reactNode)

root.render를 호출하여 브라우저 DOM 요소에 대해 hydration 된 React 루트 내부의 React 컴포넌트를 업데이트할 수 있음.

root.render(<App />);

위 코드에서 React는 hydration 된 root에서 <App />을 업데이트함.

Parameters

• reactNode: 업데이트할 React 노드. 일반적으로 <App />과 같은 JSX 조각이지만, createElement()로 생성된 React 엘리먼트, 문자열, 숫자, null 또는 undefined를 전달할 수도 있음.

Returns

undefined를 반환함.

Caveats

• 루트의 hydration이 완료되기 전에 root.render를 호출하면 React는 기존에 서버에서 렌더링된 HTML 콘텐츠를 지우고 전체 루트를 클라이언트 렌더링으로 전환함.

root.unmount()

root.unmount를 호출하여 React 루트 내부에서 렌더링된 트리를 파괴할 수 있음.

root.unmount();

완전히 React로만 빌드된 앱에는 일반적으로 root.unmount 호출이 없음.

이 함수는 React 루트의 DOM 노드(또는 그 조상 노드)가 다른 코드에 의해 DOM에서 제거될 수 있는 경우에 주로 유용함. 예를 들어, DOM에서 비활성 탭을 제거하는 jQuery 탭 패널이 있다면, 탭이 제거될 때 그 안에 있는 모든 것(내부의 React 루트를 포함)도 DOM에서 제거됨. 이 경우 root.unmount를 호출하여 제거된 루트의 콘텐츠 관리를 "중지"하도록 React에 지시해야 함. 그렇지 않으면 제거된 루트 내부의 컴포넌트가 구독과 같은 전역 리소스를 정리하고 확보해야 하는 것을 모름.

root.unmount를 호출하면 루트의 모든 컴포넌트가 unmount 되고, 트리의 이벤트 핸들러나 state를 제거하는 것을 포함하여 루트 DOM 노드에서 React가 "분리"됨.

Parameters

어떤 parameter도 허용하지 않음.

Returns

undefined를 반환함.

Caveats

• root.unmount를 호출하면 트리의 모든 컴포넌트가 unmount 되고 루트 DOM 노드에서 React가 "분리"됨.

• root.unmount를 호출하고 나면 같은 루트에서 root.render를 다시 호출할 수 없음. Unmount 된 루트에서 root.render를 호출하려고 하면 "Cannot update an unmounted root" 오류가 발생함.

Usage

Hydrating server-rendered HTML

앱의 HTML이 react-dom/server로 생성된 경우, 클라이언트에서 이를 hydrate 해야 함.

import { hydrateRoot } from 'react-dom/client';

hydrateRoot(document.getElementById('root'), <App />);

이렇게 하면 브라우저 DOM 노드 내부의 서버 HTML이 앱의 React 컴포넌트로 hydrate 됨. 일반적으로 이 작업은 시작 시 한 번 수행함. 프레임워크를 사용하는 경우 프레임워크가 백그라운드에서 이 작업을 수행할 수 있음.

앱을 hydrate 하기 위해 React는 서버에서 생성된 초기 HTML에 컴포넌트의 로직을 "첨부"함. Hydration은 서버의 초기 HTML 스냅샷을 브라우저에서 실행되는 완전한 인터랙티브 앱으로 전환함.

<!-- index.html -->

<!-- HTML content inside <div id="root">...</div> was generated from App by react-dom/server. -->
<div id="root"><h1>Hello, world!</h1><button>You clicked me <!-- -->0<!-- --> times</button></div>

import './styles.css';
import { hydrateRoot } from 'react-dom/client';
import App from './App.js';

hydrateRoot(
  document.getElementById('root'),
  <App />
);

hydrateRoot를 다시 호출하거나 더 많은 위치에서 호출할 필요가 없음. 이 시점부터 React는 애플리케이션의 DOM을 관리하게 됨. UI를 업데이트하기 위해 컴포넌트는 대신 state를 사용할 것.

Pitfall

hydrateRoot에 전달하는 React 트리는 서버에서와 동일한 출력을 생성해야 함.

이는 사용자 경험에 중요함. 사용자는 JavaScript 코드가 로드되기 전에 서버에서 생성된 HTML을 보는 데 시간을 소비하게 됨. 서버 렌더링은 출력의 HTML 스냅샷을 보여줌으로써 앱이 더 빨리 로드되는 착각을 불러일으킴. 갑자기 다른 콘텐츠를 표시하면 이러한 착각이 깨짐. 그렇기 때문에 서버 렌더링 출력은 클라이언트의 초기 렌더링 출력과 일치해야 함.

Hydration 오류를 유발하는 가장 일반적인 원인:

• 루트 노드 내부의, React가 생성한 HTML 주위에 여분의 공백(예: 개행)이 있는 경우.
• 렌더링 로직에서 typeof window !== 'undefined'와 같은 검사를 사용하는 경우.
• 렌더링 로직에 window.matchMedia와 같은 브라우저 전용 API를 사용하는 경우.
• 서버와 클라이언트에서 서로 다른 데이터를 렌더링하는 경우.
  React는 일부 hydration 오류에서 복구되지만, 다른 버그와 마찬가지로 수정해야 함. 가장 좋은 경우에는 속도 저하로 이어지지만, 최악의 경우에는 이벤트 핸들러가 잘못된 요소에 연결될 수 있음.

Hydrating an entire document

React로 완전히 빌드된 앱은 <html> 태그를 포함하여 전체 문서를 JSX로 렌더링할 수 있음:

function App() {
  return (
    <html>
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <link rel="stylesheet" href="/styles.css"></link>
        <title>My app</title>
      </head>
      <body>
        <Router />
      </body>
    </html>
  );
}

전체 문서를 hydrate 하려면 document 글로벌을 첫 번째 인수로 hydrateRoot에 전달할 것:

import { hydrateRoot } from 'react-dom/client';
import App from './App.js';

hydrateRoot(document, <App />);

Suppressing unavoidable hydration mismatch errors

단일 요소의 attribute 또는 텍스트 콘텐츠가 서버와 클라이언트 간에 불가피하게 다른 경우(예: 타임스탬프), hydration 불일치 경고를 무음으로 처리할 수 있음.

요소에서 hydration 경고를 무음으로 설정하려면, suppressHydrationWarning={true}를 추가할 것:

<!-- index.html -->

<!-- HTML content inside <div id="root">...</div> was generated from App by react-dom/server. -->
<div id="root"><h1>Current Date: <!-- -->01/01/2020</h1></div>

// index.js

import './styles.css';
import { hydrateRoot } from 'react-dom/client';
import App from './App.js';

hydrateRoot(document.getElementById('root'), <App />);

// App.js

export default function App() {
  return (
    <h1 suppressHydrationWarning={true}>
      Current Date: {new Date().toLocaleDateString()}
    </h1>
  );
}

이것은 한 층 깊이에서만 작동하며, 탈출구 역할을 함. 과도하게 사용하지 말 것. 텍스트 콘텐츠가 아니라면 React는 여전히 패치를 시도하지 않으므로 향후 업데이트가 있을 때까지 일관성이 유지될 수 있음.

Handling different client and server content

서버와 클라이언트에서 의도적으로 다른 것을 렌더링해야 하는 경우, two-pass 렌더링을 수행할 수 있음. 클라이언트에서 다른 것을 렌더링하는 컴포넌트는 isClient와 같은 state 변수를 읽을 수 있으며, 이 변수를 Effect에서 true로 설정할 수 있음:

// App.js

import { useState, useEffect } from "react";

export default function App() {
  const [isClient, setIsClient] = useState(false);

  useEffect(() => {
    setIsClient(true);
  }, []);

  return (
    <h1>
      {isClient ? 'Is Client' : 'Is Server'}
    </h1>
  );
}

이렇게 하면 초기 렌더링 패스는 서버와 동일한 콘텐츠를 렌더링하여 불일치를 방지하지만, 추가 패스는 hydration 직후에 동기적으로 발생함.

Pitfall

이 접근 방식은 컴포넌트를 두 번 렌더링해야 하므로 hydration 속도가 느려짐. 느린 연결 환경에서의 사용자 경험에 유의할 것. JavaScript 코드는 초기 HTML 렌더링보다 훨씬 늦게 로드될 수 있으므로, hydration 직후에 다른 UI를 렌더링하면 사용자에게 어색함을 줄 수 있음.

Updating a hydrated root component

루트의 hydrating 작업이 끝나면, root.render를 호출하여 루트 React 컴포넌트를 업데이트할 수 있음. createRoot와 달리, 초기 콘텐츠가 이미 HTML로 렌더링되었기 때문에 일반적으로는 이 작업을 수행할 필요가 없음.

Hydration 후 어느 시점에 root.render를 호출하고, 컴포넌트 트리 구조가 이전에 렌더링된 것과 일치하면, React는 sate를 유지함. 다음 예제에서 counter가 계속 증가하고 input에 타이핑한 내용이 계속 남아있는 것은, 매초마다 반복되는 render 호출로 인한 업데이트가 파괴적이지 않다는 것을 의미함:

// index.js

import { createRoot } from 'react-dom/client';
import './styles.css';
import App from './App.js';

const root = createRoot(document.getElementById('root'));

let i = 0;
setInterval(() => {
  root.render(<App counter={i} />);
  i++;
}, 1000);

export default function App({counter}) {
  return (
    <>
      <h1>Hello, world! {counter}</h1>
      <input placeholder="Type something here" />
    </>
  );
}

hydrate된 루트에서 root.render를 여러 번 호출하는 경우는 드뭄. 일반적으로 컴포넌트에서 대신 state를 업데이트함.

const root = createRoot(domNode, options?)

Reference

createRoot(domNode, options?)

createRoot를 호출하여 브라우저 DOM 요소 안에 콘텐츠를 표시하기 위한 React 루트를 생성할 수 있음.

import { createRoot } from 'react-dom/client';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

React는 domNode에 대한 루트를 생성하고 그 안에 있는 DOM을 관리함. 루트를 생성한 후에는 root.render를 호출하여 그 안에 React 컴포넌트를 표시해야 함:

root.render(<App />);

React로만 빌드된 앱에는 일반적으로 루트 컴포넌트에 대한 createRoot 호출이 하나만 있음. 일부에 React의 "스프링클"을 사용하는 페이지에는 필요한 만큼의 별도의 루트가 있을 수 있음.

Parameters

• domNode: DOM 요소. React는 이 DOM 요소에 대한 루트를 생성하고 렌더링된 React 콘텐츠를 표시하기 위한 render와 같은 함수를 루트에서 호출할 수 있도록 함.

• options (optional): React 루트에 대한 옵션이 있는 객체.

  • onRecoverableError (optional): React가 오류로부터 자동으로 복구할 때 호출되는 callback.
  • identifierPrefix (optional): React가 useId에 의해 생성된 ID에 사용하는 문자열 접두사. 같은 페이지에서 여러 루트를 사용할 때 충돌을 피하는 데 유용함.

Returns

render와 unmount 두 가지 메서드가 있는 객체를 반환함.

Caveats

• 앱이 서버 렌더링되는 경우 createRoot() 사용은 지원되지 않음. 대신 hydrateRoot()를 사용할 것.

• 앱에 createRoot 호출이 하나만 있을 수 있음. 프레임워크를 사용하는 경우 프레임워크가 이 호출을 대신 수행할 수 있음.

• 컴포넌트의 자식이 아닌 DOM 트리의 다른 부분(예: 모달 또는 툴팁)에 JSX 조각을 렌더링하려는 경우 createRoot 대신 createPortal을 사용할 것.

root.render(reactNode)

root.render를 호출하여 JSX 조각("React 노드")을 React 루트의 브라우저 DOM 노드에 표시할 수 있음.

root.render(<App />);

React는 루트에 <App />을 표시하고 그 안에 있는 DOM을 관리함.

Parameters

• reactNode: 표시할 React 노드. 일반적으로 <App />과 같은 JSX 조각이지만, createElement()로 생성된 React 엘리먼트, 문자열, 숫자, null 또는 undefined를 전달할 수도 있음.

Returns

undefined를 반환함.

Caveats

• root.render를 처음 호출하면 React는 React 컴포넌트를 렌더링하기 전에 React 루트 내부의 모든 기존 HTML 콘텐츠를 지움.

• 루트의 DOM 노드에 서버에서 또는 빌드 중에 React에 의해 생성된 HTML이 포함된 경우, 기존 HTML에 이벤트 핸들러를 붙여주는 hydrateRoot()를 사용할 것.

• 동일한 루트에서 render를 두 번 이상 호출하면 React는 전달한 최신 JSX를 반영하기 위해 필요에 따라 DOM을 업데이트함. React는 이전에 렌더링된 트리와 "비교"해서 재사용할 수 있는 부분과 다시 만들어야 하는 부분을 결정함. 동일한 루트에서 render를 다시 호출하는 것은 루트 컴포넌트에서 set 함수를 호출하는 것과 유사함: React는 불필요한 DOM 업데이트를 지양함.

root.unmount()

root.unmount를 호출하여 React 루트 내부에서 렌더링된 트리를 파괴할 수 있음.

root.unmount();

React로 완전히 빌드된 앱에는 일반적으로 root.unmount 호출이 없음.

이 함수는 React 루트의 DOM 노드(또는 그 조상 노드)가 다른 코드에 의해 DOM에서 제거될 수 있는 경우에 주로 유용함. 예를 들어, DOM에서 비활성 탭을 제거하는 jQuery 탭 패널이 있다면, 탭이 제거될 때 그 안에 있는 모든 것(내부의 React 루트를 포함)도 DOM에서 제거됨. 이 경우 root.unmount를 호출하여 제거된 루트의 콘텐츠 관리를 "중지"하도록 React에 지시해야 함. 그렇지 않으면 제거된 루트 내부의 컴포넌트가 구독과 같은 전역 리소스를 정리하고 확보해야 하는 것을 모름.

root.unmount를 호출하면 루트의 모든 컴포넌트가 unmount 되고, 트리의 이벤트 핸들러나 state를 제거하는 것을 포함하여 루트 DOM 노드에서 React가 "분리"됨.

Parameters

어떤 parameter도 허용하지 않음.

Returns

undefined를 반환함.

Caveats

• root.unmount를 호출하면 트리의 모든 컴포넌트가 unmount 되고 루트 DOM 노드에서 React가 "분리"됨.

• root.unmount를 호출하고 나면 같은 루트에서 root.render를 다시 호출할 수 없음. Unmount 된 루트에서 root.render를 호출하려고 하면 "Cannot update an unmounted root" 오류가 발생함. 그러나 해당 노드의 이전 루트가 unmount된 후 동일한 DOM 노드에 대한 새 루트를 만들 수 있음.

Usage

Rendering an app fully built with React

앱이 완전히 React로만 빌드된 경우, 전체 앱에 대해 단일 루트를 생성할 것.

import { createRoot } from 'react-dom/client';

const root = createRoot(document.getElementById('root'));
root.render(<App />);

일반적으로 이 코드는 시작할 때 한 번만 실행하면 됨. 이 코드는:

1. HTML에 정의된 브라우저 DOM 노드를 찾음.
2. 그 안에 앱의 React 컴포넌트를 표시함.

앱이 완전히 React로만 빌드된 경우, 루트를 더 만들거나 root.render를 다시 호출할 필요가 없음.

이 시점부터 React는 전체 앱의 DOM을 관리함. 컴포넌트를 더 추가하려면, App 컴포넌트 안에 중첩할 것. UI를 업데이트해야 할 때, 각 컴포넌트는 state를 사용하여 이를 수행할 수 있음. 모달이나 툴팁과 같은 추가 콘텐츠를 DOM 노드 외부에 표시해야 하는 경우, portal을 사용하여 렌더링할 것.

Note

HTML이 비어 있으면 앱의 JavaScript 코드가 로드되고 실행될 때까지 사용자에게 빈 페이지가 표시됨:

<div id="root"></div>

이는 매우 느리게 느껴질 수 있음! 이 문제를 해결하기 위해 서버에서, 또는 빌드 중에 컴포넌트로부터 초기 HTML을 생성할 수 음. 그러면 방문자는 JavaScript 코드가 로드되기 전에 텍스트를 읽고, 이미지를 보고, 링크를 클릭할 수 있음. 이 최적화를 기본적으로 수행하는 프레임워크를 사용하는 것이 좋음. 실행 시점에 따라 이를 server-side rendering(SSR) 또는 static site generation(SSG)이라고 함.

Pitfall

server rendering 또는 static generation을 사용하는 앱은 createRoot 대신 hydrateRoot를 호출해야 함. 그러면 React는 DOM 노드를 파괴하고 다시 생성하는 대신 HTML에서 hydrate(재사용)함.

Rendering a page partially built with React

페이지가 React로만 완전히 빌드되지 않은 경우, createRoot를 여러 번 호출하여 React가 관리하는 각 최상위 UI 조각에 대한 루트를 생성할 수 있음. root.render를 호출하여 각 루트에 다른 콘텐츠를 표시할 수 있음.

다음 예제에서는 두 개의 서로 다른 React 컴포넌트가 index.html 파일에 정의된 두 개의 DOM 노드에 렌더링됨:

// index.html

<!DOCTYPE html>
<html>
  <head><title>My app</title></head>
  <body>
    <nav id="navigation"></nav>
    <main>
      <p>This paragraph is not rendered by React (open index.html to verify).</p>
      <section id="comments"></section>
    </main>
  </body>
</html>

// index.js

import './styles.css';
import { createRoot } from 'react-dom/client';
import { Comments, Navigation } from './Components.js';

const navDomNode = document.getElementById('navigation');
const navRoot = createRoot(navDomNode); 
navRoot.render(<Navigation />);

const commentDomNode = document.getElementById('comments');
const commentRoot = createRoot(commentDomNode); 
commentRoot.render(<Comments />);

document.createElement()를 사용하여 새 DOM 노드를 생성하고 문서에 수동으로 추가할 수도 있음.

const domNode = document.createElement('div');
const root = createRoot(domNode); 
root.render(<Comment />);
document.body.appendChild(domNode); // You can add it anywhere in the document

DOM 노드에서 React 트리를 제거하고 이 트리가 사용하는 모든 리소스를 정리하려면 root.unmount를 호출할 것.

root.unmount();

이 기능은 주로 다른 프레임워크로 작성된 앱 내부에 React 컴포넌트가 있는 경우에 유용함.

Updating a root component

같은 루트에서 render를 두 번 이상 호출할 수 있음. 컴포넌트 트리 구조가 이전에 렌더링된 것과 일치하는 한, React는 state를 유지함. 다음 예제에서 counter가 계속 증가하고 input에 타이핑한 내용이 계속 남아있는 것은, 매초마다 반복되는 render 호출로 인한 업데이트가 파괴적이지 않다는 것을 의미함:

// index.js

import { createRoot } from 'react-dom/client';
import './styles.css';
import App from './App.js';

const root = createRoot(document.getElementById('root'));

let i = 0;
setInterval(() => {
  root.render(<App counter={i} />);
  i++;
}, 1000);

export default function App({counter}) {
  return (
    <>
      <h1>Hello, world! {counter}</h1>
      <input placeholder="Type something here" />
    </>
  );
}

render를 여러 번 호출하는 경우는 드뭄. 일반적으로 컴포넌트가 대신 state를 업데이트함.

Troubleshooting

I’ve created a root, but nothing is displayed

앱을 실제로 루트에 렌더링하는 것을 잊지 않았는지 확인할 것:

import { createRoot } from 'react-dom/client';
import App from './App.js';

const root = createRoot(document.getElementById('root'));
root.render(<App />); // ✅

그렇게 할 때까지는 아무것도 표시되지 않음.

I’m getting an error: “Target container is not a DOM element”

이 오류는 createRoot에 전달하는 것이 DOM 노드가 아님을 의미함.

무슨 일이 발생했는지 확실하지 않다면 로깅을 해볼 것:

const domNode = document.getElementById('root');
console.log(domNode); // ???
const root = createRoot(domNode);
root.render(<App />);

예를 들어, domNode가 null이면 getElementById가 null을 반환했다는 뜻임. 이는 호출 시점에 문서에 지정된 ID를 가진 노드가 없는 경우에 발생함. 가능한 몇 가지 원인이 있ㅇ음:

1. 찾고 있는 ID가 HTML 파일에서 사용한 ID와 다를 수 있음. 오타가 있는지 확인할 것!
2. 번들의 <script> 태그는 HTML에서 그 뒤에 나타나는 DOM 노드를 "볼" 수 없음.

이 오류가 발생하는 또 다른 일반적인 경우는 createRoot(domNode) 대신 createRoot(<App />)를 작성하는 경우.

I’m getting an error: “Functions are not valid as a React child.”

이 오류는 root.render에 전달하는 것이 React 컴포넌트가 아님을 의미함.

이 오류는 root.render를 <Component /> 대신 Component로 호출할 때 발생할 수 있음:

// 🚩 Wrong: App is a function, not a Component.
root.render(App);

// ✅ Correct: <App /> is a component.
root.render(<App />);

또는 root.render에 함수를 호출한 결과 대신 함수를 전달했을 때에도 발생할 수 있음:

// 🚩 Wrong: createApp is a function, not a component.
root.render(createApp);

// ✅ Correct: call createApp to return a component.
root.render(createApp());

My server-rendered HTML gets re-created from scratch

앱이 서버 렌더링되고 React로 생성된 초기 HTML을 포함하는 경우, 루트를 생성하고 root.render를 호출하면 해당 HTML이 모두 삭제되고 모든 DOM 노드가 처음부터 다시 생성되는 것을 알 수 있음. 이렇게 하면 속도가 느려지고 포커스와 스크롤 위치가 초기화되며 다른 사용자 입력이 손실될 수 있음.

서버에서 렌더링된 앱은 createRoot 대신 hydrateRoot를 사용해야 함:

import { hydrateRoot } from 'react-dom/client';
import App from './App.js';

hydrateRoot(
  document.getElementById('root'),
  <App />
);

API가 다르다는 점에 유의할 것. 특히, 일반적으로 더이상 root.render 호출이 없음.

<div>
  <SomeComponent />
  {createPortal(children, domNode, key?)}
</div>

Reference

createPortal(children, domNode, key?)

Portal을 만들려면 createPortal을 호출하여 JSX와 이를 렌더링할 DOM 노드를 전달하면 됨:

import { createPortal } from 'react-dom';

// ...

<div>
  <p>This child is placed in the parent div.</p>
  {createPortal(
    <p>This child is placed in the document body.</p>,
    document.body
  )}
</div>

Portal은 DOM 노드의 물리적 배치만 변경함. portal을 이용해 렌더링하는 JSX는 물리적 배치 외의 다른 모든 면에서 이를 렌더링하는 React 컴포넌트의 자식 노드 처럼 동작함. 예를 들어, 자식은 부모 트리에서 제공하는 context에 액세스할 수 있으며, 이벤트는 React 트리에 따라 자식에서 부모로 bubble up됨.

Parameters

• children: JSX 조각(예: <div /> 또는 <SomeComponent />), Fragment(<>...</>), 문자열 또는 숫자, 또는 이들의 배열 등 React로 렌더링할 수 있는 모든 것.

• domNode: document.getElementById()가 반환하는 것과 같은 DOM 노드. 노드가 이미 존재해야 함. 업데이트 중에 다른 DOM 노드를 전달하면 potal 콘텐츠가 다시 생성됨.

• key(optional): Portal의 key로 사용할 고유 문자열 또는 숫자.

Returns

createPortal은 JSX에 포함되거나 React 컴포넌트에서 반환할 수 있는 React 노드를 반환함. React가 렌더링 출력에서 이 노드를 발견하면, 제공된 children을 제공된 domNode 안에 배치함.

Caveats

Portal의 이벤트는 DOM 트리가 아닌 React 트리에 따라 전파됨. 예를 들어, <div onClick>으로 감싸진 portal 내부를 클릭할 경우, 해당 onClick 핸들러가 실행됨. 이로 인해 문제가 발생하면 portal 내부에서 이벤트 전파를 중지하거나 portal 자체를 React 트리에서 위로 이동할 것.

Usage

Rendering to a different part of the DOM

Portal을 사용하면 컴포넌트의 일부 자식을 DOM의 다른 위치에서 렌더링할 수 있음. 이를 통해 컴포넌트의 일부가 어떤 컨테이너에 있든 "escape"될 수 있음. 예를 들어, 컴포넌트는 모달 대화상자나 툴팁을 페이지의 나머지 부분의 위와 바깥쪽에 표시할 수 있음.

Portal을 만들려면 JSX와 DOM 노드가 있어야 할 곳을 전달한 createPortal을 렌더링할 것:

import { createPortal } from 'react-dom';

function MyComponent() {
  return (
    <div style={{ border: '2px solid black' }}>
      <p>This child is placed in the parent div.</p>
      {createPortal(
        <p>This child is placed in the document body.</p>,
        document.body
      )}
    </div>
  );
}

React는 사용자가 전달한 JSX의 DOM 노드를 사용자가 제공한 DOM 노드 안에 배치함.

포털이 없다면 두 번째 <p>는 부모 <div> 안에 배치되지만, 포털은 이를 document.body로 '텔레포트'함.

두 번째 단락이 테두리가 있는 부모 <div> 외부에 나타나는 것에 주목할 것. 개발자 도구로 DOM 구조를 검사하면 두 번째 <p>가 <body>에 바로 배치된 것을 확인할 수 있음:

// 개발자 도구로 검사한 DOM 구조

<body>
  <div id="root">
    ...
      <div style="border: 2px solid black">
        <p>This child is placed inside the parent div.</p>
      </div>
    ...
  </div>
  <p>This child is placed in the document body.</p>
</body>

Portal은 DOM 노드의 물리적 배치만 변경함. portal을 이용해 렌더링하는 JSX는 물리적 배치 외의 다른 모든 면에서 이를 렌더링하는 React 컴포넌트의 자식 노드 처럼 동작함. 예를 들어, 자식은 부모 트리에서 제공하는 context에 액세스할 수 있으며, 이벤트는 React 트리에 따라 자식에서 부모로 bubble up됨.

Rendering a modal dialog with a portal

모달 대화 상자를 불러오는 컴포넌트가 overflow: hidden 또는 대화 상자를 방해하는 다른 스타일이 있는 컨테이너 안에 있는 경우에도 portal을 사용하여 페이지의 나머지 부분 위에 떠 있는 모달 대화 상자를 만들 수 있음.

다음 예제에서는 두 컨테이너에 모달 대화 상자를 방해하는 스타일이 있지만, DOM에서 모달이 부모 JSX 요소에 포함되지 않기 때문에 portal에 렌더링된 것은 영향을 받지 않음.

// App.js

import NoPortalExample from './NoPortalExample';
import PortalExample from './PortalExample';

export default function App() {
  return (
    <>
      <div className="clipping-container">
        <NoPortalExample  />
      </div>
      <div className="clipping-container">
        <PortalExample />
      </div>
    </>
  );
}

// PortalExample.js

import { useState } from 'react';
import { createPortal } from 'react-dom';
import ModalContent from './ModalContent.js';

export default function PortalExample() {
  const [showModal, setShowModal] = useState(false);
  return (
    <>
      <button onClick={() => setShowModal(true)}>
        Show modal using a portal
      </button>
      {showModal && createPortal(
        <ModalContent onClose={() => setShowModal(false)} />,
        document.body
      )}
    </>
  );
}

Pitfall

Portal을 사용할 때 앱의 접근성을 확인하는 것이 중요함. 예를 들어, 사용자가 portal 안팎으로 자연스럽게 초점을 이동할 수 있도록 키보드 포커스를 관리해야 할 수 있음.

Portal을 만들 때는 WAI-ARIA 모달 제작 관행을 따를 것. 커뮤니티 패키지를 사용하는 경우에는 해당 패키지의 접근성을 확인하고 위 지침을 따르는지 확인할 것.

Rendering React components into non-React server markup

Portal은 React 루트가 React로 빌드되지 않은 정적 또는 서버 렌더링 페이지의 일부일 때 유용할 수 있음. 예를 들어 페이지가 Rails와 같은 서버 프레임워크로 빌드된 경우, 사이드바 같은 정적 영역 내에 인터랙티브 영역을 만들 수 있음. 여러 개의 개별 React 루트를 사용하는 것과 비교하여 portal을 사용하면 앱의 일부가 DOM의 다른 부분에 렌더링되더라도 앱을 공유 상태를 가진 단일 React 트리로 취급할 수 있음.

// index.html

<!DOCTYPE html>
<html>
  <head><title>My app</title></head>
  <body>
    <h1>Welcome to my hybrid app</h1>
    <div class="parent">
      <div class="sidebar">
        This is server non-React markup
        <div id="sidebar-content"></div>
      </div>
      <div id="root"></div>
    </div>
  </body>
</html>

// App.js

import { createPortal } from 'react-dom';

const sidebarContentEl = document.getElementById('sidebar-content');

export default function App() {
  return (
    <>
      <MainContent />
      {createPortal(
        <SidebarContent />,
        sidebarContentEl
      )}
    </>
  );
}

function MainContent() {
  return <p>This part is rendered by React</p>;
}

function SidebarContent() {
  return <p>This part is also rendered by React!</p>;
}

Rendering React components into non-React DOM nodes

Portal을 사용하여 React 외부에서 관리되는 DOM 노드의 콘텐츠를 관리할 수도 있음. 예를 들어, React가 아닌 맵 위젯과 통합할 때 팝업 안에 React 콘텐츠를 렌더링하고 싶다면, 렌더링할 DOM 노드를 저장하는 state 변수를 선언하면 됨:

const [popupContainer, setPopupContainer] = useState(null);

써드파티 위젯을 만들 때, 위젯이 반환하는 DOM 노드를 저장하여 렌더링할 수 있도록 함:

useEffect(() => {
  if (mapRef.current === null) {
    const map = createMapWidget(containerRef.current);
    mapRef.current = map;
    const popupDiv = addPopupToMapWidget(map);
    setPopupContainer(popupDiv);
  }
}, []);

React 콘텐츠를 사용할 수 있게 되면 createPortal을 사용하여 popupContainer로 렌더링할 수 있음:

return (
  <div style={{ width: 250, height: 250 }} ref={containerRef}>
    {popupContainer !== null && createPortal(
      <p>Hello from React!</p>,
      popupContainer
    )}
  </div>
);

<>
  <OneChild />
  <AnotherChild />
</>

Reference

<Fragment>

단일 요소가 필요한 상황에서 요소들을 <Fragment>로 묶어 그룹화할 수 있음. Fragment 안에서 요소들을 그룹화해도 최종 DOM에는 영향을 미치지 않으며, 요소들을 그룹화하지 않은 경우와 동일함. 대부분의 경우 빈 JSX 태그 <></>는 <Fragment></Fragment>의 축약어임.

Props

• key (optional): 명시적인 <Fragment> 구문으로 선언된 Fragment는 key를 가질 수 있음.

Caveats

• Fragment에 key를 전달하려면 <>...</> 구문을 사용할 수 없음. 명시적으로 'react'에서 Fragment를 import 해서 <Fragment key={yourKey}>...</Fragment>를 렌더링해야 함.

• React는 <><Child /></>를 [<Child />]로 변경하거나 그 반대의 경우에, 그리고 <><Child /></>를 <Child />로 변경하거나 그 반대의 경우에 state를 리셋하지 않음. 이는 한 단계 깊이에서만 작동함. 예를 들어 <><><Child /></></>를 <Child />로 변경하면 state가 리셋됨.

  • 참고: 리액트의 상태 유지

Usage

Returning multiple elements

여러 요소들을 그룹화하려면 Fragment 또는 이와 동등한 <>...</> 구문을 사용할 것. 이를 사용하면 단일 요소가 들어갈 수 있는 모든 위치에 여러 요소들을 넣을 수 있음. 예를 들어, 컴포넌트는 하나의 요소만 반환할 수 있지만 Fragment를 사용하면 여러 요소들을 그룹화해서 하나의 그룹으로 반환할 수 있음:

function Post() {
  return (
    <>
      <PostTitle />
      <PostBody />
    </>
  );
}

Fragment를 사용하여 요소들을 그룹화하는 것은 DOM 요소와 같은 다른 컨테이너로 요소를 감싸는 것과 달리 레이아웃이나 스타일에 영향을 주지 않기 때문에 유용함. 브라우저 도구로 다음 예시를 살펴보면 모든 <h1> 및 <article> DOM 노드가 wrapper가 없는 형제 노드로 표시되는 것을 확인할 수 있음:

export default function Blog() {
  return (
    <>
      <Post title="An update" body="It's been a while since I posted..." />
      <Post title="My new blog" body="I am starting a new blog!" />
    </>
  )
}

function Post({ title, body }) {
  return (
    <>
      <PostTitle title={title} />
      <PostBody body={body} />
    </>
  );
}

function PostTitle({ title }) {
  return <h1>{title}</h1>
}

function PostBody({ body }) {
  return (
    <article>
      <p>{body}</p>
    </article>
  );
}

DEEP DIVE: How to write a Fragment without the special syntax?

위의 예제는 React에서 Fragment를 import 하는 것과 같음:

import { Fragment } from 'react';
>
function Post() {
  return (
    <Fragment>
      <PostTitle />
      <PostBody />
    </Fragment>
  );
}

Fragment에 key를 전달해야 하는 경우가 아니라면 보통은 필요하지 않음.

Assigning multiple elements to a variable

다른 요소와 마찬가지로, Fragment 요소를 변수에 할당하거나 props로 전달하는 등의 작업을 수행할 수 있음:

function CloseDialog() {
  const buttons = (
    <>
      <OKButton />
      <CancelButton />
    </>
  );
  return (
    <AlertDialog buttons={buttons}>
      Are you sure you want to leave this page?
    </AlertDialog>
  );
}

Grouping elements with text

Fragment를 사용하여 텍스트를 컴포넌트와 함께 그룹화할 수 있음:

function DateRangePicker({ start, end }) {
  return (
    <>
      From
      <DatePicker date={start} />
      to
      <DatePicker date={end} />
    </>
  );
}

Rendering a list of Fragments

다음은 <></> 구문을 사용하는 대신 Fragment를 명시적으로 작성해야 하는 상황. 루프에서 여러 요소를 렌더링할 때는 각 요소에 key를 할당해야 함. 루프 내의 요소가 Fragment인 경우 key attribute를 제공하려면 일반 JSX 요소 구문을 사용해야 함:

function Blog() {
  return posts.map(post =>
    <Fragment key={post.id}>
      <PostTitle title={post.title} />
      <PostBody body={post.body} />
    </Fragment>
  );
}

DOM을 검사하면 Fragment 자식 주변에 wrapper 요소가 없는 것을 확인할 수 있음.

<Profiler id="App" onRender={onRender}>
  <App />
</Profiler>

Reference

<Profiler>

컴포넌트 트리를 <Profiler>로 감싸면 렌더링 성능을 측정할 수 있음.

<Profiler id="App" onRender={onRender}>
  <App />
</Profiler>

Props

• id: 측정하려는 UI 부분을 식별하는 문자열.
• onRender: 프로파일링된 트리 내의 컴포넌트가 업데이트될 때마다 React가 호출하는 onRender callback. 이 callback은 렌더링된 내용과 소요 시간에 대한 정보를 받음.

Caveats

• 프로파일링은 약간의 오버헤드가 추가되므로 프로덕션 빌드에서는 기본적으로 비활성화되어 있음. 프로덕션 프로파일링을 사용하려면 프로파일링이 활성화된 특수 프로덕션 빌드를 사용하도록 설정해야 함.

onRender callback

React는 렌더링된 내용에 대한 정보와 함께 onRender callback을 호출함.

function onRender(id, phase, actualDuration, baseDuration, startTime, commitTime) {
  // Aggregate or log render timings...
}

Parameters

• id: 방금 커밋한 <Profiler> 트리의 문자열 id 프로퍼티. 이를 통해 여러 프로파일러를 사용하는 경우 트리의 어느 부분이 커밋되었는지 식별할 수 있음.
• phase: "mount", "update" 또는 "nested-update". 이를 통해 트리가 방금 처음 mount 되었는지 또는 props, state 또는 hooks의 변경으로 인해 다시 렌더링되었는지 알 수 있음.
• actualDuration: 현재 업데이트에 대해 <Profiler>와 그 자손을 렌더링하는 데 소요된 시간(밀리초). 이 값은 서브트리가 memoization(예: memo 및 useMemo)을 얼마나 잘 사용하는지를 나타냄. 대부분의 자손은 특정 props가 변경되는 경우에만 다시 렌더링하면 되므로 초기 mount 후에는 이 값이 크게 줄어드는 것이 이상적임.
• baseDuration: 최적화 없이 전체 <Profiler> 서브트리를 다시 렌더링하는 데 소요되는 시간의 추정값(밀리초). 트리에 있는 각 컴포넌트의 가장 최근 렌더링 시간을 합산하여 계산됨. 이 값은 최악의 렌더링 비용(예: 초기 mount 또는 memoization이 없는 트리)을 추정합니다. actualDuration과 비교하여 memoization가 작동하는지 확인할 수 있음.
• startTime: React가 현재 업데이트 렌더링을 시작한 시점에 대한 숫자 타임스탬프.
• commitTime: React가 현재 업데이트를 커밋한 시점의 숫자 타임스탬프. 이 값은 커밋의 모든 프로파일러 간에 공유되므로 원하는 경우 그룹화할 수 있음.

Usage

Measuring rendering performance programmatically

React 트리를 <Profiler> 컴포넌트로 감싸서 렌더링 성능을 측정할 수 있음.

<App>
  <Profiler id="Sidebar" onRender={onRender}>
    <Sidebar />
  </Profiler>
  <PageContent />
</App>

두 가지 props가 필요함: id(문자열), 트리 내의 컴포넌트가 업데이트를 "커밋"할 때마다 React가 호출하는 onRender callback(함수)

Pitfall

프로파일링은 약간의 오버헤드가 추가되므로 프로덕션 빌드에서는 기본적으로 비활성화되어 있음. 프로덕션 프로파일링을 사용하려면 프로파일링이 활성화된 특수 프로덕션 빌드를 사용하도록 설정해야 함.

Note

<Profiler>를 사용하면 프로그래밍적으로 측정값을 수집할 수 있음. 상호작용이 가능한 프로파일러를 찾고 있다면 브라우저 확장 프로그램과 유사한 기능을 제공하는 React 개발자 도구의 Profiler 탭을 사용할 것.

Measuring different parts of the application

여러 <Profiler> 컴포넌트를 사용하여 애플리케이션의 여러 부분을 측정할 수 있음:

<App>
  <Profiler id="Sidebar" onRender={onRender}>
    <Sidebar />
  </Profiler>
  <Profiler id="Content" onRender={onRender}>
    <Content />
  </Profiler>
</App>

<Profiler> 컴포넌트를 중첩할 수도 있음:

<App>
  <Profiler id="Sidebar" onRender={onRender}>
    <Sidebar />
  </Profiler>
  <Profiler id="Content" onRender={onRender}>
    <Content>
      <Profiler id="Editor" onRender={onRender}>
        <Editor />
      </Profiler>
      <Preview />
    </Content>
  </Profiler>
</App>

<Profiler>는 경량 컴포넌트이지만, 사용할 때마다 애플리케이션에 약간의 CPU 및 메모리 오버헤드가 추가되기 때문에 꼭 필요한 경우에만 사용해야 함.

<StrictMode>
  <App />
</StrictMode>

Reference

<StrictMode>

내부 컴포넌트 트리에 대한 추가 개발 동작 및 경고를 활성화하려면 StrictMode를 사용할 것:

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';

const root = createRoot(document.getElementById('root'));
root.render(
  <StrictMode>
    <App />
  </StrictMode>
);

Strict Mode는 다음과 같은 개발 전용 동작을 활성화함:

• 불완전한 렌더링으로 인한 버그를 찾기 위해 컴포넌트가 한 번 더 재렌더링함.
• Effect cleanup이 누락되어 발생한 버그를 찾기 위해 컴포넌트가 Effects를 한 번 더 재실행함.
• 컴포넌트가 더 이상 사용되지 않는 API를 사용하는지 확인함.

Props

props를 받지 않음.

Caveats

<StrictMode>로 래핑된 트리 내부에서는 Strict Mode를 해제할 방법이 없음. 이 때문에 <StrictMode> 내의 모든 컴포넌트가 검사된다는 확신을 가질 수 있음. 제품을 작업하는 두 팀이 검사의 가치에 대해 의견이 다를 경우, 합의를 도출하거나 <StrictMode>를 트리에서 아래로 이동해야 함.

Usage

Enabling Strict Mode for entire app

Strict Mode를 사용하면 <StrictMode> 컴포넌트 내부의 전체 컴포넌트 트리에 대해 개발 전용 검사를 추가로 수행할 수 있음. 이러한 검사를 통해 개발 프로세스 초기에 컴포넌트에서 흔히 발생하는 버그를 발견할 수 있음.

전체 앱에서 Strict Mode를 사용하려면 루트 컴포넌트를 렌더링할 때 <StrictMode>로 감싸면 됨:

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';

const root = createRoot(document.getElementById('root'));
root.render(
  <StrictMode>
    <App />
  </StrictMode>
);

특히 새로 만든 앱의 경우 전체 앱을 Strict Mode로 감싸는 것이 좋음. createRoot를 대신 호출하는 프레임워크를 사용하는 경우, 해당 프레임워크의 문서를 참조하여 Strict Mode를 활성화하는 방법을 확인할 것.

Strict Mode 검사는 개발 중에만 실행되지만, 코드에 이미 존재하지만 프로덕션 환경에서 안정적으로 재현하기 어려운 버그를 찾는 데 도움이 됨. Strict Mode를 사용하면 사용자가 버그를 신고하기 전에 버그를 수정할 수 있음.

Note

Strict Mode에서는 개발 단계에서 다음과 같은 검사가 가능함:

• 불완전한 렌더링으로 인한 버그를 찾기 위해 컴포넌트가 한 번 더 재렌더링함.
• Effect cleanup이 누락되어 발생한 버그를 찾기 위해 컴포넌트가 Effects를 한 번 더 재실행함.
• 컴포넌트가 더 이상 사용되지 않는 API를 사용하는지 확인함.
  이러한 모든 검사는 개발 전용이며 프로덕션 빌드에는 영향을 미치지 않음.

Enabling Strict Mode for a part of the app

애플리케이션의 모든 부분에 대해 Strict Mode를 활성화할 수 있음:

import { StrictMode } from 'react';

function App() {
  return (
    <>
      <Header />
      <StrictMode>
        <main>
          <Sidebar />
          <Content />
        </main>
      </StrictMode>
      <Footer />
    </>
  );
}

이 예제에서는 Header 및 Footer 컴포넌트에 대해 Strict Mode 검사가 실행되지 않음. 그러나 Sidebar 및 Content는 물론 그 안에 있는 모든 컴포넌트에는 아무리 깊어도 Strict Mode 검사가 실행됨.

Fixing bugs found by double rendering in development

React는 모든 컴포넌트가 순수한 함수라고 가정함. 즉, React 컴포넌트는 동일한 입력(props, state, context)이 주어지면 항상 동일한 JSX를 반환해야 함.

이 규칙을 위반하는 컴포넌트는 예측할 수 없게 동작하며 버그를 유발함. 의도치 않게 비순수한 코드를 찾을 수 있도록 Strict Mode는 개발 과정에서 일부 함수(순수해야 하는 함수만)를 두 번 호출함. 예를 들면:

• 컴포넌트 함수 본문(최상위 로직만 포함하므로 이벤트 핸들러 내부의 코드는 포함되지 않음)
• useState, set functions, useMemo 또는 useReducer에 전달하는 함수
• constructor, render, shouldComponentUpdate와 같은 일부 클래스 컴포넌트 메서드 (참고: 전체 목록)

순수한 함수는 매번 동일한 결과를 생성하기 때문에 함수를 두 번 실행해도 동작이 변경되지 않음. 그러나 함수가 비순수한 경우(예: 받은 데이터를 변경하는 경우) 두 번 실행하면 눈에 띄는 차이가 있으므로(그래서 비순수한 것!) 버그를 조기에 발견하고 수정하는 데 도움이 됨.

다음은 Strict Mode에서 이중 렌더링이 버그를 조기에 발견하는 데 어떻게 도움이 되는지 설명하는 예시임.

이 StoryTray 컴포넌트는 여러 개의 stories 배열을 가져와 "Create Story" 항목을 배열의 끝에 추가함:

// StoryTray.js

export default function StoryTray({ stories }) {
  const items = stories;
  items.push({ id: 'create', label: 'Create Story' });
  return (
    <ul>
      {items.map(story => (
        <li key={story.id}>
          {story.label}
        </li>
      ))}
    </ul>
  );
}

위 코드에는 실수가 있음. 그러나 초기 출력은 올바르게 보이기 때문에 놓치기 쉬움.

이 실수는 StoryTray 컴포넌트가 여러 번 다시 렌더링하면 더욱 눈에 띄게 됨. 예를 들어 StoryTray를 마우스로 가리킬 때마다 다른 배경색으로 다시 렌더링하면:

// StoryTray.js

import { useState } from 'react';

export default function StoryTray({ stories }) {
  const [isHover, setIsHover] = useState(false);
  const items = stories;
  items.push({ id: 'create', label: 'Create Story' });
  return (
    <ul
      onPointerEnter={() => setIsHover(true)}
      onPointerLeave={() => setIsHover(false)}
      style={{
        backgroundColor: isHover ? '#ddd' : '#fff'
      }}
    >
      {items.map(story => (
        <li key={story.id}>
          {story.label}
        </li>
      ))}
    </ul>
  );
}

StoryTray 컴포넌트 위로 마우스를 가져갈 때마다 'Create Story'가 목록에 다시 추가되는 것을 볼 수 있음. 코드의 의도는 마지막에 한 번만 추가하는 것이었지만, StoryTray는 props의 stories 배열을 직접 수정함. StoryTray는 렌더링할 때마다 동일한 배열의 끝에 "Create Story"를 다시 추가함. 즉, StoryTray는 순수한 함수가 아니기 때문에 여러 번 실행하면 다른 결과가 생성됨.

이 문제를 해결하려면 배열의 복사본을 만든 다음 원본이 아닌 복사본을 수정하면 됨:

export default function StoryTray({ stories }) {
  const items = stories.slice(); // Clone the array
  // ✅ Good: Pushing into a new array
  items.push({ id: 'create', label: 'Create Story' });

이렇게 하면 StoryTray 함수가 순수해짐. 이 함수가 호출될 때마다 배열의 새 복사본만 수정하고 외부 객체나 변수에 영향을 주지 않음. 이렇게 하면 버그가 해결되지만, 컴포넌트의 동작에 문제가 있다는 것이 명백해지기 전에 컴포넌트를 더 자주 재렌더링해야 했음.

원래 예제에서는 버그가 명백하지 않았음. 원래의 (버그가 있는) 코드를 <StrictMode>로 감싸면?

Strict Mode에서는 항상 렌더링 함수를 두 번 호출하므로 실수를 바로 확인할 수 있음("Create Story"가 두 번 표시됨). 따라서 프로세스 초기에 이러한 실수를 발견할 수 있음. 컴포넌트를 Strict Mode에서 렌더링하도록 수정하면, 이전의 호버 기능과 같이 향후 발생할 수 있는 많은 프로덕션 버그도 수정할 수 있음.

Strict Mode가 없으면 리렌더를 더 추가하기 전까지는 버그를 놓치기 쉬웠음. Strict Mode를 사용하면 동일한 버그를 바로 발견할 수 있음. Strict Mode를 사용하면 팀과 사용자에게 푸시하기 전에 버그를 발견할 수 있음.

참고: 컴포넌트를 순수하게 유지하는 방법

Note

React 개발자 도구를 설치한 경우 두 번째 렌더링 호출 중의 모든 console.log 호출이 약간 흐리게 표시됨. React 개발자 도구는 이를 완전히 막는 설정(기본값은 off)도 제공함.

Fixing bugs found by re-running Effects in development

Strict Mode는 Effects의 버그를 찾는 데도 도움이 될 수 있음.

모든 Effect에는 setup 코드가 있고 cleanup 코드가 있을 수 있음. 일반적으로 React는 컴포넌트가 mount될 때(화면에 추가될 때) setup을 호출하고 컴포넌트가 unmount될 때(화면에서 제거될 때) cleanup을 호출함. 그런 다음 React는 마지막 렌더링 이후 dependencies가 변경된 경우 cleanup과 setup을 다시 호출함.

Strict Mode가 켜져 있으면 React는 모든 Effect에 대해 개발 단계에서 setup + cleanup 사이클을 한 번 더 실행함. 이는 의외로 느껴질 수 있지만 수동으로 잡기 어려운 미묘한 버그를 발견하는 데 도움이 됨.

컴포넌트를 채팅에 연결하는 다음 예시는 Strict Mode에서 Effects를 다시 실행하는 것이 버그를 조기에 발견하는 데 어떻게 도움이 되는지 보여줌:

// App.js

import { useState, useEffect } from 'react';
import { createConnection } from './chat.js';

const serverUrl = 'https://localhost:1234';
const roomId = 'general';

export default function ChatRoom() {
  useEffect(() => {
    const connection = createConnection(serverUrl, roomId);
    connection.connect();
  }, []);
  return <h1>Welcome to the {roomId} room!</h1>;
}

// chat.js

let connections = 0;

export function createConnection(serverUrl, roomId) {
  // A real implementation would actually connect to the server
  return {
    connect() {
      console.log('✅ Connecting to "' + roomId + '" room at ' + serverUrl + '...');
      connections++;
      console.log('Active connections: ' + connections);
    },
    disconnect() {
      console.log('❌ Disconnected from "' + roomId + '" room at ' + serverUrl);
      connections--;
      console.log('Active connections: ' + connections);
    }
  };
}

이 코드에는 문제가 있지만 즉시 알아차리기 어려움.

문제를 더 명확하게 파악하기 위해 기능을 구현할 것. 아래 예제에서는 roomId가 하드코딩되어 있지 않은 대신, 사용자가 드롭다운에서 연결하려는 roomId를 선택할 수 있음. 'Open chat'를 클릭한 다음 다른 채팅방을 하나씩 선택하면 콘솔에서 활성화된 커넥션의 개수를 추적함:

// App.js

import { useState, useEffect } from 'react';
import { createConnection } from './chat.js';

const serverUrl = 'https://localhost:1234';

function ChatRoom({ roomId }) {
  useEffect(() => {
    const connection = createConnection(serverUrl, roomId);
    connection.connect();
  }, [roomId]);

  return <h1>Welcome to the {roomId} room!</h1>;
}

export default function App() {
  const [roomId, setRoomId] = useState('general');
  const [show, setShow] = useState(false);
  return (
    <>
      <label>
        Choose the chat room:{' '}
        <select
          value={roomId}
          onChange={e => setRoomId(e.target.value)}
        >
          <option value="general">general</option>
          <option value="travel">travel</option>
          <option value="music">music</option>
        </select>
      </label>
      <button onClick={() => setShow(!show)}>
        {show ? 'Close chat' : 'Open chat'}
      </button>
      {show && <hr />}
      {show && <ChatRoom roomId={roomId} />}
    </>
  );
}

열려있는 커넥션의 개수가 계속 증가하는 것을 알 수 있음. 실제 앱에서는 성능 및 네트워크 문제가 발생할 수 있음. 문제는 Effect에 cleanup 함수가 없다는 것:

useEffect(() => {
  const connection = createConnection(serverUrl, roomId);
  connection.connect();
  return () => connection.disconnect();
}, [roomId]);

이제 Effect가 스스로 "clean up"하고 오래된 커넥션을 삭제하므로 누수 문제가 해결되었음. 하지만 더 많은 기능(드롭다운)을 추가하기 전까지는 문제가 보이지 않았음.

원래 예제에서는 버그가 명백하지 않았음. 원래의 (버그가 있는) 코드를 <StrictMode>로 감싸면?

Strict Mode를 사용하면 문제가 있음을 즉시 알 수 있음(활성화된 커넥션 수가 2로 증가하므로). Strict Mode는 모든 Effects에 대해 추가 setup+cleanup 사이클을 실행함. 이 Effects에는 cleanup 로직이 없으므로 추가 커넥션을 생성하지만 파괴하지는 않음. 이것은 cleanup 함수가 누락되었다는 힌트임.

Strict Mode를 사용하면 이러한 실수를 프로세스 초기에 발견할 수 있음. Strict Mode에서 cleanup 함수를 추가하여 Effects를 수정하면 향후 발생할 수 있는 많은 프로덕션 버그도 수정할 수 있음.

Strict Mode가 없으면 Effects에 cleanup이 필요하다는 사실을 놓치기 쉬웠음. 개발 단계에서 Effects를 setup 대신 setup → cleanup → setup을 실행하면 누락된 cleanup 로직이 더 눈에 띄게 됨.

참고: Effect의 cleanup 구현하기

Fixing deprecation warnings enabled by Strict Mode

React는 <StrictMode> 트리 내의 일부 컴포넌트가 더 이상 사용되지 않는 다음 API 중 하나를 사용하는 경우 경고를 표시함:

• findDOMNode (참고: 대안)
• UNSAFE_componentWillMount와 같은 UNSAFE_ 클래스 생명주기 메서드 (참고: 대안)
• 레거시 컨텍스트(childContextTypes, contextTypes 및 getChildContext). (참고: 대안)
• 레거시 문자열 refs(this.refs). (참고: 대안)

이러한 API는 주로 과거의 클래스 컴포넌트에서 사용되므로 최신 앱에서는 거의 나타나지 않음.

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

Reference

<Suspense>

Props

• children: 렌더링하려는 실제 UI. 렌더링하는 동안 children이 일시 중단되면 Suspense boundary가 렌더링 fallback으로 전환됨.

• fallback: 로딩이 완료되지 않은 경우 실제 UI 대신 렌더링할 대체 UI. 유효한 모든 React 노드를 사용할 수 있지만, 실제로 fallback은 로딩 스피너나 스켈레톤과 같은 경량 placeholder 뷰임. Suspense는 children이 일시 중단되면 자동으로 fallback으로 전환되고, 데이터가 준비되면 다시 children으로 전환됨. 렌더링 중에 fallback이 일시 중단되면 가장 가까운 상위 Suspense boundary가 활성화됨.

Caveats

• ?React는 처음으로 mount가 가능하기 전에 일시 중단된 렌더링의 state를 보존하지 않음.? 컴포넌트가 로드되면 React는 일시 중단된 트리의 렌더링을 처음부터 다시 시도함.

• Suspense가 트리의 콘텐츠를 표시하다가 다시 일시 중단된 경우, 그 원인이 startTransition 또는 useDeferredValue로 인한 업데이트가 아닌 한 fallback이 다시 표시됨.

• React가 다시 일시 중단되어 이미 표시된 콘텐츠를 숨겨야 하는 경우, 콘텐츠 트리에서 layout Effects를 cleanup 함. 콘텐츠가 다시 표시될 준비가 되면 React는 layout Effects를 다시 실행함. 이렇게 하면 콘텐츠가 숨겨져 있는 동안 DOM 레이아웃을 측정하는 Effects가 이 작업을 시도하지 않음.

• React에는 스트리밍 서버 렌더링 및 선택적 Hydration과 같은 내부 최적화가 포함되어 있으며, 이는 Suspense와 통합되어 있음.

  • 참고: React 18의 새로운 Suspense SSR 아키텍처
  • 참고: Suspense를 사용한 스트리밍 서버 렌더링

Usage

Displaying a fallback while content is loading

애플리케이션의 어느 부분이든 Suspense boundary로 감쌀 수 있음:

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

React는 자식에게 필요한 모든 코드와 데이터가 로드될 때까지 loading fallback을 표시함.

아래 예시에서는 앨범 목록을 가져오는 동안 Albums 컴포넌트가 일시 중단됨. 렌더링할 준비가 될 때까지 React는 가장 가까운 상위 Suspense boundary를 전환하여 fallback, 즉 Loading 컴포넌트를 표시함. 그런 다음 데이터가 로드되면, React는 Loading fallback을 숨기고 데이터와 함께 Albums 컴포넌트를 렌더링함.

import { Suspense } from 'react';
import Albums from './Albums.js';

export default function ArtistPage({ artist }) {
  return (
    <>
      <h1>{artist.name}</h1>
      <Suspense fallback={<Loading />}>
        <Albums artistId={artist.id} />
      </Suspense>
    </>
  );
}

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

Note

Suspense-enabled한 데이터 소스만 Suspense 컴포넌트를 활성화함. 여기에는 다음이 포함됨:

• Relay 및 Next.js와 같은 Suspense-enabled 프레임워크를 사용한 데이터 fetching
• lazy를 사용한 Lazy-loading 컴포넌트 코드
• use를 사용한 Prokise 값 읽기
  Suspense는 Effect 또는 이벤트 핸들러 내부에서 데이터를 가져오는 시점을 감지하지 못함.
  위의 Albums 컴포넌트에서 데이터를 로드하는 정확한 방법은 프레임워크에 따라 다름. Suspense-enabled 프레임워크를 사용하는 경우, 해당 프레임워크의 데이터 fetching 문서에서 자세한 내용을 확인할 수 있음.
  Suspense-enabled 프레임워크를 사용하지 않는 Suspense-enabled 데이터 fetching은 아직 지원되지 않음. Suspense-enabled 데이터 소스를 구현하기 위한 요구 사항은 불안정하고 문서화되어 있지 않음. 데이터 소스를 Suspense와 통합하기 위한 공식 API는 향후의 React 버전에서 출시될 예정임.

Revealing content together at once

기본적으로 Suspense 내부의 전체 트리는 하나의 단위로 취급됨. 예를 들어, Suspense 내부의 하나의 컴포넌트가 데이터를 기다리느라 일시 중단되더라도 Suspense 내부의 모든 컴포넌트가 함께 loading indicator로 대체됨:

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

그런 다음, Suspense 내부의 모든 컴포넌트가 표시될 준비가 되면 한 번에 모두 함께 표시됨.

위의 코드에서 Biography와 Albums가 각각 데이터를 fetch 하더라도, 이 두 컴포넌트는 하나의 Suspense boundary 아래에 그룹화되어 있기 때문에 항상 동시에 함께 'pop in' 됨.

데이터를 로드하는 컴포넌트가 Suspense boundary의 직접적인 자식일 필요는 없음. 예를 들어, 아래 코드처럼 Biography 및 Albums를 새로운 Details 컴포넌트 안으로 이동할 수 있음. 이렇게 해도 동작은 변경되지 않음. Biography와 Albums는 가장 가까운 상위 Suspense boundary를 공유하므로 표시 여부가 함께 조정됨.

<Suspense fallback={<Loading />}>
  <Details artistId={artist.id} />
</Suspense>

function Details({ artistId }) {
  return (
    <>
      <Biography artistId={artistId} />
      <Panel>
        <Albums artistId={artistId} />
      </Panel>
    </>
  );
}

Revealing nested content as it loads

컴포넌트가 일시 중단되면, 가장 가까운 상위 Suspense 컴포넌트가 fallback을 표시함. 이를 통해 여러 Suspense 컴포넌트를 중첩하여 로딩 시퀀스를 만들 수 있음. 각 Suspense boundary의 fallback은 다음 단계의 콘텐츠를 사용할 수 있게 되면 채워짐. 예를 들어, 앨범 목록에 자체 fallback을 지정할 수 있음:

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

이렇게 하면 Biography를 표시할 때 Albums가 로드될 때까지 "기다릴" 필요가 없음.

시퀀스는 다음과 같음:

1. Biography가 아직 로드되지 않은 경우, 전체 콘텐츠 영역 대신 BigSpinner가 표시됨.
2. Biography 로드가 완료되면, BigSpinner가 콘텐츠로 대체됨.
3. Albums가 아직 로드되지 않은 경우, Albums와 그 부모인 Panel 대신 AlbumsGlimmer가 표시됨.
4. 마지막으로 Albums 로딩이 완료되면, AlbumsGlimmer가 Albums와 그 부모인 Panel로 대체됨.

Suspense boundaries를 사용하면 UI의 어느 부분이 항상 동시에 "pop in" 되어야 하는지, 어느 부분이 로딩 상태 시퀀스에서 점진적으로 더 많은 콘텐츠를 표시해야 하는지를 조정할 수 있음. 앱의 나머지 동작에 영향을 주지 않고 트리의 어느 위치에서나 Suspense boundaries를 추가, 이동 또는 삭제할 수 있음.

모든 컴포넌트 주위에 Suspense boundaries를 두지 말 것. Suspense boundaries는 사용자가 경험하게 될 로딩 시퀀스보다 더 세분화되어서는 안 됨. 디자이너와 함께 작업하는 경우, 로딩 상태를 어디에 배치해야 하는지 디자이너에게 물어볼 것. 디자이너가 이미 디자인 와이어프레임에 포함시켰을 가능성이 높음.

Showing stale content while fresh content is loading

다음 예에서는 검색 결과를 가져오는 동안 SearchResults 컴포넌트가 일시 중단됨. "a"를 입력하고 결과를 기다린 다음 "ab"로 수정하면, "a"에 대한 결과는 loading fallback으로 대체됨.

import { Suspense, useState } from 'react';
import SearchResults from './SearchResults.js';

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

일반적인 대체 UI 패턴은 목록 업데이트를 지연하고 새 결과가 준비될 때까지 이전 결과를 계속 표시하는 것. useDeferredValue Hook을 사용하면 쿼리의 지연된 버전을 전달할 수 있음:

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

쿼리가 즉시 업데이트되므로 input에는 새 값이 표시됨. 하지만 데이터가 로드될 때까지 deferredQuery는 이전 값을 유지하므로 SearchResults는 잠시 동안 이전 결과를 표시함.

사용자에게 더 명확하게 알리기 위해, 이전 결과 목록이 표시될 때 시각적 indication을 추가할 수 있음:

<div style={{
  opacity: query !== deferredQuery ? 0.5 : 1 
}}>
  <SearchResults query={deferredQuery} />
</div>

이제 "a"를 입력하고 결과가 로드될 때까지 기다린 다음 입력을 "ab"로 수정하면 새 결과가 로드될 때까지 Suspense fallback 대신 희미한 이전 결과 목록이 표시됨.

Note

지연된 값과 transition 모두 인라인 indicator를 위해 Suspense fallback을 표시하지 않도록 함. Transition은 전체 업데이트를 긴급하지 않은 것으로 표시하므로 일반적으로 프레임워크와 라우터 라이브러리에서 navigation을 위해 사용함. 반면 지연 값은 UI의 일부를 긴급하지 않은 것으로 표시하고 나머지 UI보다 '지연'시키려는 애플리케이션 코드에서 주로 유용함.

Preventing already revealed content from hiding

컴포넌트가 일시 중단되면 가장 가까운 상위 Suspense boundary가 fallback을 표시하도록 전환됨. 이로 인해 이미 일부 콘텐츠가 표시되고 있는 경우 사용자 경험이 불안정해질 수 있음:

// App.js

import { Suspense, useState } from 'react';
import IndexPage from './IndexPage.js';
import ArtistPage from './ArtistPage.js';
import Layout from './Layout.js';

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={{
          id: 'the-beatles',
          name: 'The Beatles',
        }}
      />
    );
  }
  return (
    <Layout>
      {content}
    </Layout>
  );
}

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

버튼을 누르면 Router 컴포넌트는 IndexPage 대신 ArtistPage를 렌더링함. ArtistPage 내부의 컴포넌트가 일시 중단되었기 때문에 가장 가까운 Suspense boundary가 fallback을 표시하기 시작함. 가장 가까운 Suspense boundary가 루트 근처에 있었기 때문에 전체 사이트 레이아웃이 BigSpinner로 대체됨.

이를 방지하기 위해 startTransition을 사용하여 navigation state 업데이트를 transition으로 표시할 수 있음:

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

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

  // ...

이는 state transiton이 긴급하지 않으며, 이미 공개된 콘텐츠를 숨기는 대신 이전 페이지를 계속 표시하는 것이 낫다는 것을 React에게 알려줌. 이제 버튼을 클릭하면 Biography가 로드될 때까지 "대기"함.

Transition은 모든 콘텐츠가 로드될 때까지 기다리지 않음. 이미 표시된 콘텐츠를 숨기지 않을 만큼만 기다림. 예를 들어 웹사이트 Layout이 이미 공개되었으므로 로딩 스피너 뒤에 숨기는 것은 좋지 않음. 그러나 Albums를 둘러싼 중첩된 Suspense boundary는 새로운 것이므로 transition이 기다리지 않음.

Note

Suspense-enabled 라우터는 기본적으로 navigation 업데이트를 transition으로 감쌀 것으로 예상됨.

Indicating that a transition is happening

위의 예에서는 버튼을 클릭해도 navigation이 진행 중이라는 시각적 indication이 없었음. Indicator를 추가하려면 startTransiton을 useTransition으로 대체하여 boolean 값인 isPending을 반환하면 됨. 아래 예에서는 transition이 진행되는 동안 웹사이트 헤더 스타일을 변경하는 데 사용됨:

// App.js

import { Suspense, useState, useTransition } from 'react';
import IndexPage from './IndexPage.js';
import ArtistPage from './ArtistPage.js';
import Layout from './Layout.js';

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

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

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

  let content;
  if (page === '/') {
    content = (
      <IndexPage navigate={navigate} />
    );
  } else if (page === '/the-beatles') {
    content = (
      <ArtistPage
        artist={{
          id: 'the-beatles',
          name: 'The Beatles',
        }}
      />
    );
  }
  return (
    <Layout isPending={isPending}>
      {content}
    </Layout>
  );
}

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

// Layout.js

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

Resetting Suspense boundaries on navigation

Transition 중에 React는 이미 노출된 콘텐츠를 숨기지 않음. 그러나 다른 parameters가 있는 경로로 이동하는 경우, React에게 다른 콘텐츠임을 알려주고 싶을 수 있음. 이를 key로 표현할 수 있음:

<ProfilePage key={queryParams.id} />

사용자의 프로필 페이지 내에서 탐색 중에 무언가가 일시 중단된 경우, 해당 업데이트가 transition으로 감싸지면 이미 표시된 콘텐츠에 대한 fallback이 트리거되지 않음. 이것은 예상되는 동작임.

하지만 서로 다른 두 개의 사용자 프로필 사이를 탐색한다고 가정하면, 이 경우 fallback을 표시하는 것이 좋음. 예를 들어 한 사용자의 타임라인은 다른 사용자의 타임라인과 다른 콘텐츠임. key를 지정하면 React가 서로 다른 사용자의 프로필을 서로 다른 컴포넌트로 취급하고 탐색 중에 Suspense boundaries를 재설정하도록 할 수 있음. Suspense-integrated 라우터는 이 작업을 자동으로 수행해야 함.

Providing a fallback for server errors and client-only content

스트리밍 서버 렌더링 API 중 하나(또는 이에 의존하는 프레임워크)를 사용하는 경우, React는 서버에서 발생하는 오류를 처리하기 위해 Suspense boundaries도 사용함. 컴포넌트가 서버에서 에러를 발생시키면 React는 서버 렌더링을 중단하지 않음. 대신, 가장 가까운 상위 <Suspense> 컴포넌트를 찾아서 생성된 서버 HTML에 그 fallback(예: 스피너)을 포함시킴. 사용자는 처음에는 스피너를 보게 됨.

클라이언트에서 React는 동일한 컴포넌트를 다시 렌더링하려고 시도함. 클라이언트에서도 에러가 발생하면 React는 에러를 던지고 가장 가까운 error boundary를 표시함. 그러나 클라이언트에서 에러가 발생하지 않는다면 콘텐츠가 결국 성공적으로 표시되었기 때문에 React는 사용자에게 에러를 표시하지 않음.

이를 사용하여 일부 컴포넌트를 서버에서 렌더링하지 않도록 선택할 수 있음. 이렇게 하려면 서버 환경에서 에러를 발생시킨 다음 Suspense boundary로 감싸서 해당 HTML을 fallback으로 대체하면 됨:

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

function Chat() {
  if (typeof window === 'undefined') {
    throw Error('Chat should only render on the client.');
  }

  // ...
}

서버 HTML에는 indicator가 포함됨. 이 indicator는 클라이언트의 Chat 컴포넌트로 대체됨.

Troubleshooting

How do I prevent the UI from being replaced by a fallback during an update?

표시되는 UI를 fallback으로 대체하면 사용자 경험이 불안정해짐. 이는 업데이트로 인해 컴포넌트가 일시 중단되고 가장 가까운 Suspense boundary가 이미 사용자에게 콘텐츠를 표시하고 있을 때 발생할 수 있음.

이런 일이 발생하지 않도록 하려면 startTransition을 사용하여 업데이트를 긴급하지 않은 것으로 표시할 것. Transition이 진행되는 동안 React는 원치 않는 fallback이 나타나지 않도록 충분한 데이터가 로드될 때까지 기다림:

function handleNextPageClick() {
  // If this update suspends, don't hide the already displayed content
  startTransition(() => {
    setCurrentPage(currentPage + 1);
  });
}

이렇게 하면 기존 콘텐츠가 숨겨지지 않음. 그러나 새로 렌더링된 Suspense boundaries는 여전히 즉시 fallback을 표시하여 UI를 가리지 않고 사용자가 콘텐츠를 사용할 수 있게 되면 볼 수 있도록 함.

React는 긴급하지 않은 업데이트 중에만 원치 않는 fallback을 방지함. 긴급한 업데이트의 결과인 경우 렌더링을 지연시키지 않음. startTransition이나 useDeferredValue와 같은 API로 opt in 해야 함.

라우터가 Suspense와 통합된 경우, 라우터는 자동으로 업데이트를 startTransition으로 감싸야 함.

const id = useId()

Reference

useId()

컴포넌트의 최상위 수준에서 useId를 호출하여 고유 ID를 생성할 수 있음:

import { useId } from 'react';

function PasswordField() {
  const passwordHintId = useId();

  // ...

Parameters

parameters를 받지 않음.

Returns

이 특정 컴포넌트에서 이 특정 useId 호출과 관련된 고유 ID 문자열을 반환함.

Caveats

• useId는 Hook이므로 컴포넌트의 최상위 수준이나 자체 Hook에서만 호출할 수 있음. 루프나 조건 내부에서는 호출할 수 없음. 필요한 경우 새 컴포넌트를 추출하고 state를 그 안으로 옮길 것.

• useId는 목록에서 key를 생성하는 데 사용해서는 안됨. 키는 데이터로부터 생성해야 함.

Usage

Pitfall

목록에서 key를 생성하기 위해 useId를 호출하지 말 것! 키는 데이터로부터 생성해야 함.

Generating unique IDs for accessibility attributes

컴포넌트의 최상위 수준에서 useId를 호출하여 고유 ID를 생성:

import { useId } from 'react';

function PasswordField() {
  const passwordHintId = useId();

  // ...

그런 다음 생성된 ID를 다른 attribute에 전달할 수 있음:

<>
  <input type="password" aria-describedby={passwordHintId} />
  <p id={passwordHintId}>
</>

이 기능은 언제 유용한가?

aria-describedby와 같은 HTML 접근성 attribute를 사용하면 두 태그가 서로 관련되어 있음을 지정할 수 있음. 예를 들어, input과 같은 요소가 paragraph와 같은 다른 요소에 의해 설명되도록 지정할 수 있음.

일반 HTML에서는 다음과 같이 작성함:

<label>
  Password:
  <input
    type="password"
    aria-describedby="password-hint"
  />
</label>
<p id="password-hint">
  The password should contain at least 18 characters
</p>

그러나 이와 같이 ID를 하드코딩하는 것은 React에서 좋은 방법이 아님. 컴포넌트는 페이지에서 두 번 이상 렌더링될 수 있지만 ID는 고유해야 함! ID를 하드코딩하는 대신 useId로 고유한 ID를 생성할 것:

import { useId } from 'react';

function PasswordField() {
  const passwordHintId = useId();
  return (
    <>
      <label>
        Password:
        <input
          type="password"
          aria-describedby={passwordHintId}
        />
      </label>
      <p id={passwordHintId}>
        The password should contain at least 18 characters
      </p>
    </>
  );
}

이제 PasswordField가 화면에 여러 번 표시되더라도 생성된 ID가 충돌하지 않음.

• 참고: 보조 기술을 통한 사용자 경험의 차이

Pitfall

서버 렌더링의 경우 useId를 사용하려면 서버와 클라이언트에서 동일한 컴포넌트 트리가 필요ㅎ함. 서버와 클라이언트에서 렌더링하는 트리가 정확히 일치하지 않으면 생성된 ID가 일치하지 않음.

DEEP DIVE: Why is useId better than an incrementing counter?

useId가 nextId++와 같이 전역 변수를 증가시키는 것보다 나은 이유는?

useId의 가장 큰 장점은 React가 서버 렌더링에서도 작동하도록 보장한다는 것. 서버 렌더링 중에 컴포넌트는 HTML 출력을 생성함. 나중에 클라이언트에서 hydration을 통해 생성된 HTML에 이벤트 핸들러를 첨부함. Hydration 작동하려면 클라이언트 출력이 서버 HTML과 일치해야 함.

클라이언트 컴포넌트가 hydration되는 순서가 서버 HTML이 출력되는 순서와 일치하지 않을 수 있기 때문에 증분 카운터로는 이를 보장하기가 매우 어려움. useId를 호출하면 hydration이 작동하고 서버와 클라이언트 간에 출력이 일치하는지 확인할 수 있음.

React 내부에서 useId는 호출하는 컴포넌트의 "부모 경로"에서 생성됨. 그렇기 때문에 클라이언트와 서버 트리가 동일하면 렌더링 순서에 관계없이 "부모 경로"가 일치함.

Generating IDs for several related elements

관련된 여러 요소에 ID를 부여해야 하는 경우 useId를 호출하여 해당 요소들의 공통 접두사를 생성할 수 있음:

import { useId } from 'react';

export default function Form() {
  const id = useId();
  return (
    <form>
      <label htmlFor={id + '-firstName'}>First Name:</label>
      <input id={id + '-firstName'} type="text" />
      <hr />
      <label htmlFor={id + '-lastName'}>Last Name:</label>
      <input id={id + '-lastName'} type="text" />
    </form>
  );
}

이렇게 하면 고유 ID가 필요한 모든 요소에 대해 useId를 호출하지 않아도 됨.

Specifying a shared prefix for all generated IDs

단일 페이지에서 여러 개의 독립적인 React 애플리케이션을 렌더링하는 경우, createRoot 또는 hydrateRoot 호출에 identifierPrefix를 옵션으로 전달할 것. 이렇게 하면 useId로 생성된 모든 식별자가 지정한 고유한 접두사로 시작하므로 서로 다른 두 앱에서 생성된 ID가 충돌하지 않음.

// index.js
import { createRoot } from 'react-dom/client';
import App from './App.js';
import './styles.css';

const root1 = createRoot(document.getElementById('root1'), {
  identifierPrefix: 'my-first-app-'
});
root1.render(<App />);

const root2 = createRoot(document.getElementById('root2'), {
  identifierPrefix: 'my-second-app-'
});
root2.render(<App />);

Using the same ID prefix on the client and the server

동일한 페이지에 여러 개의 독립적인 React 앱을 렌더링하고 이러한 앱 중 일부가 서버에서 렌더링되는 경우, 클라이언트 측에서 hydrateRoot 호출에 전달하는 identifierPrefix가 renderToPipeableStream과 같은 서버 API에 전달하는 identifierPrefix와 동일한지 확인할 것.

// Server
import { renderToPipeableStream } from 'react-dom/server';

const { pipe } = renderToPipeableStream(
  <App />,
  { identifierPrefix: 'react-app1' }
);

// Client
import { hydrateRoot } from 'react-dom/client';

const domNode = document.getElementById('root');
const root = hydrateRoot(
  domNode,
  reactNode,
  { identifierPrefix: 'react-app1' }
);

페이지에 React 앱이 하나만 있는 경우 identifierPrefix를 전달할 필요가 없음.

const SomeComponent = lazy(load)

Reference

lazy(load)

컴포넌트 외부에서 lazy를 호출하여 lazy-loaded React 컴포넌트를 선언할 수 있음:

import { lazy } from 'react';

const MarkdownPreview = lazy(() => import('./MarkdownPreview.js'));

Parameters

• load: Promise 또는 다른 thenable(then 메서드가 있는 Promise와 유사한 객체)을 반환하는 함수. React는 반환된 컴포넌트를 처음 렌더링하려고 시도할 때까지 load를 호출하지 않음. React가 load를 처음 호출한 후, resolve될 때까지 기다린 다음, resolved 값의 .default를 React 컴포넌트로 렌더링함. 반환된 Promise와 Promise의 resolved 값은 모두 캐시되므로 React는 load를 두 번 이상 호출하지 않음. Promise가 reject되면 React는 가장 가까운 Error Boundary에 rejection 이유를 throw함.

Returns

lazy는 트리에서 렌더링할 수 있는 React 컴포넌트를 반환함. lazy 컴포넌트의 코드가 로딩되는 동안에는 렌더링을 시도하면 일시 중단됨. 로딩하는 동안 loading indicator를 표시하려면 <Suspense>를 사용할 것.

load function

Parameters

parameters를 받지 않음.

Returns

Promise 또는 다른 thenable(then 메서드가 있는 Promise와 유사한 객체)을 반환해야함. 최종적으로 .default 프로퍼티는 함수, memo 또는 forwardRef 컴포넌트와 같은 유효한 React 컴포넌트 유형인 객체로 resolve되어야 함.

Usage

Lazy-loading components with Suspense

일반적으로 정적 import 선언을 사용하여 컴포넌트를 가져옴:

import MarkdownPreview from './MarkdownPreview.js';

이 컴포넌트의 코드가 처음 렌더링될 때까지 로딩을 지연시키려면 이 import를 다음으로 대체:

import { lazy } from 'react';

const MarkdownPreview = lazy(() => import('./MarkdownPreview.js'));

이 코드는 동적 import()에 의존하므로 번들러 또는 프레임워크의 지원이 필요할 수 있음. 이 패턴을 사용하려면 가져오려는 lazy 컴포넌트를 default export로 내보내야 함.

이제 컴포넌트의 코드는 필요할 때 로드되므로 로드하는 동안 표시할 내용도 지정해야 함. Lazy 컴포넌트나 그 부모 컴포넌트를 <Suspense> 바운더리로 감싸면 됨:

<Suspense fallback={<Loading />}>
  <h2>Preview</h2>
  <MarkdownPreview />
 </Suspense>

다음 예제에서는 렌더링을 시도하기 전까지 MarkdownPreview의 코드가 로드되지 않음. MarkdownPreview가 아직 로드되지 않은 경우, 그 자리에 <Loading />이 표시됨:

import { useState, Suspense, lazy } from 'react';
import Loading from './Loading.js';

const MarkdownPreview = lazy(() => delayForDemo(import('./MarkdownPreview.js')));

export default function MarkdownEditor() {
  const [showPreview, setShowPreview] = useState(false);
  const [markdown, setMarkdown] = useState('Hello, **world**!');
  return (
    <>
      <textarea value={markdown} onChange={e => setMarkdown(e.target.value)} />
      <label>
        <input type="checkbox" checked={showPreview} onChange={e => setShowPreview(e.target.checked)} />
        Show preview
      </label>
      <hr />
      {showPreview && (
        <Suspense fallback={<Loading />}>
          <h2>Preview</h2>
          <MarkdownPreview markdown={markdown} />
        </Suspense>
      )}
    </>
  );
}

// Add a fixed delay so you can see the loading state
function delayForDemo(promise) {
  return new Promise(resolve => {
    setTimeout(resolve, 2000);
  }).then(() => promise);
}

체크박스를 선택한 후 선택 해제했다가 다시 선택하면 Preview가 캐시되므로 로딩 상태가 표시되지 않음.

참고: Suspense로 로딩 상태를 관리하는 방법

Troubleshooting

My lazy component’s state gets reset unexpectedly

다른 컴포넌트 안에 지연 컴포넌트를 선언하지 말 것:

import { lazy } from 'react';

function Editor() {
  // 🔴 Bad: This will cause all state to be reset on re-renders
  const MarkdownPreview = lazy(() => import('./MarkdownPreview.js'));

  // ...
}

대신 항상 모듈의 최상위 레벨에서 선언할 것:

import { lazy } from 'react';

// ✅ Good: Declare lazy components outside of your components
const MarkdownPreview = lazy(() => import('./MarkdownPreview.js'));

function Editor() {

  // ...
}

• https://saengmotmi.netlify.app/react/react-lazy/
• https://velog.io/@adguy/React.lazy-%EC%99%9C-%EC%93%B0%EB%8A%94%EA%B0%80

useDebugValue(value, format?)

Reference

useDebugValue(value, format?)

사용자 정의 Hook의 최상위 수준에서 useDebugValue를 호출하여 읽을 수 있는 debug 값을 표시함:

import { useDebugValue } from 'react';

function useOnlineStatus() {
  // ...

  useDebugValue(isOnline ? 'Online' : 'Offline');

  // ...
}

Parameters

• value: React 개발자 도구에 표시할 값. 모든 타입을 가질 수 있음.

• format(optional): formatting 함수. 컴포넌트를 검사할 때 React 개발자 도구는 value를 인수로 formatting 함수를 호출한 다음 포맷팅된 반환값(모든 타입을 가질 수 있음)을 표시함. Formatting 함수를 지정하지 않으면 원래 value 자체가 표시됨.

Returns

아무것도 반환하지 않음.

Usage

Adding a label to a custom Hook

사용자 정의 Hook의 최상위 수준에서 useDebugValue를 호출하여 React 개발자 도구에서 읽을 수 있는 debug 값을 표시함.

import { useSyncExternalStore, useDebugValue } from 'react';

export function useOnlineStatus() {
  const isOnline = useSyncExternalStore(subscribe, () => navigator.onLine, () => true);
  useDebugValue(isOnline ? 'Online' : 'Offline');
  return isOnline;
}

이렇게 하면 useOnlineStatus를 호출하는 컴포넌트를 검사할 때 OnlineStatus: "Online"과 같은 레이블이 지정됨:

useDebugValue 호출이 없으면 기본 데이터(이 예제에서는 true)만 표시됨.

Note

모든 사용자 정의 Hook에 debug 값을 추가하지 말 것. 이 기능은 공유 라이브러리의 일부이면서 검사하기 어려운 복잡한 내부 데이터 구조를 가진 사용자 정의 Hook에 가장 유용함.

Deferring formatting of a debug value

또한 useDebugValue의 두 번째 인수로 formatting 함수를 전달할 수도 있음:

useDebugValue(date, date => date.toDateString());

Formatting 함수는 debug 값을 매개변수로 받고 포맷팅된 display 값을 반환해야 함. 컴포넌트가 검사되면 React 개발자 도구는 이 함수를 호출하고 그 결과를 표시함.

이렇게 하면 컴포넌트가 실제로 검사되지 않는 한 잠재적으로 비용이 많이 드는 포맷팅 로직을 실행하지 않아도 됨. 예를 들어 날짜가 Date 값인 경우, 렌더링할 때마다 toDateString()을 호출하지 않아도 됨.

const deferredValue = useDeferredValue(value)

Reference

useDeferredValue(value)

컴포넌트의 최상위 수준에서 useDeferredValue를 호출하여 해당 값의 지연된 버전을 가져올 수 있음:

import { useState, useDeferredValue } from 'react';

function SearchPage() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);
  // ...
}

Parameters

• value: 지연하려는 값. 모든 타입을 가질 수 있음.

Returns

초기 렌더링 중에 반환되는 지연된 값은 사용자가 제공한 값과 동일함. 업데이트하는 동안 React는 먼저 이전 값으로 리렌더링을 시도하고(따라서 이전 값을 반환함), 새로운 값으로 백그라운드에서 리렌더링을 시도함(따라서 업데이트된 값을 반환함).

Caveats

• useDeferredValue에 전달하는 값은 문자열과 숫자 같은 원시값이거나 렌더링 외부에서 생성된 객체여야함. 렌더링 중에 새 객체를 생성하고 즉시 useDeferredValue에 전달하면 렌더링할 때마다 값이 달라져 불필요한 백그라운드 리렌더링이 발생할 수 있음.

• useDeferredValue가 다른 값(Object.is로 비교)을 받으면, 현재 렌더링(여전히 이전 값을 사용)에 더해서 새 값으로 백그라운드에서 리렌더링하도록 예약함. 백그라운드 리렌더링은 중단할 수 있음(interruptible). value에 대한 다른 업데이트가 있으면 React는 백그라운드 리렌더링을 처음부터 다시 시작함. 예를 들어, 지연된 값을 받는 chart가 리렌더링되는 속도보다 사용자가 더 빠르게 입력값을 타이핑하는 경우, chart는 사용자가 타이핑을 멈춘 후에만 다시 렌더링됨

• useDeferredValue는 <Suspense>와 통합됨. 새 값으로 인한 백그라운드 업데이트로 인해 UI가 일시 중단되어도 사용자에게 fallback이 표시되지 않음. 데이터가 로드될 때까지 이전 지연된 값이 표시됨.

• useDeferredValue는 그 자체로 추가 네트워크 요청을 방지하지 않음.

• useDeferredValue 자체로 인한 고정된 지연은 없음. React는 원래의 리렌더링을 완료하자마자, 새로운 지연된 값으로 백그라운드 리렌더링 작업을 즉시 시작함. 타이핑과 같은 이벤트로 인한 모든 업데이트는 백그라운드 리렌더링을 중단하고 우선순위를 부여받음.

• useDeferredValue으로 인한 백그라운드 리렌더는 화면에 커밋될 때까지 Effects를 실행하지 않음. 백그라운드 리렌더링이 일시 중단되면 데이터가 로드되고 UI가 업데이트된 후에 해당 Effects가 실행됨.

Usage

Showing stale content while fresh content is loading

컴포넌트의 최상위 레벨에서 useDeferredValue를 호출하여 UI의 일부 업데이트를 지연할 수 있음:

import { useState, useDeferredValue } from 'react';

function SearchPage() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);

  // ...
}

초기 렌더링 중에 지연된 값은 사용자가 제공한 값과 동일함.

업데이트하는 동안 지연된 값은 최신 값보다 "뒤처지게" 됨. 특히 React는 지연된 값을 업데이트하지 않고 리렌더링한 다음, 새로 받은 값으로 백그라운드에서 리렌더링을 시도함.

이 기능이 유용한 경우는?

Note

이 예에서는 Suspense를 지원하는 데이터 소스을 사용한다고 가정함:

• Relay 및 Next.js와 같은 Suspense 지원 프레임워크를 사용한 데이터 fetch
• lazy을 사용한 lazy-loading 컴포넌트
• use로 프로미스의 값 읽기
  참고: Suspense와 그 한계

다음 예에서는 검색 결과를 가져오는 동안 SearchResults 컴포넌트가 일시 중단됨. "a"를 입력하고 결과를 기다린 다음 "ab"로 수정하면, "a"에 대한 결과는 loading fallback으로 대체됨.

import { Suspense, useState } from 'react';
import SearchResults from './SearchResults.js';

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

이를 대체할 수 있는 일반적인 UI 패턴은 결과 목록 업데이트를 지연하고 새 결과가 준비될 때까지 이전 결과를 계속 표시하는 것. useDeferredValue를 호출하여 query의 지연된 버전을 전달하면 됨:

import { Suspense, useState, useDeferredValue } from 'react';
import SearchResults from './SearchResults.js';

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

query는 즉시 업데이트되므로 input에 새 값이 표시되지만, 데이터가 로드될 때까지 deferredQuery는 이전 값을 유지하므로 SearchResults는 잠시 동안 이전 결과를 표시함.

"a"를 입력하고 결과가 로드될 때까지 기다린 다음 입력을 "ab"로 수정하면, 이제 Suspense fallback 대신 새 결과가 로드될 때까지 이전 결과 목록이 표시되는 것을 볼 수 있음.

DEEP DIVE: How does deferring a value work under the hood?

두 단계로 나누어 생각할 수 있음:

1. 먼저, React는 새로운 query("ab")로 리렌더링하지만, 이전 deferredQuery(여전히 "a")를 사용함. 결과 목록에 전달하는 deferredQuery 값은 지연되어 query 값보다 "뒤처지게" 됨.

2. 백그라운드에서 React는 query와 deferredQuery를 모두 "ab"로 업데이트하여 리렌더링하려고 시도함. 이 리렌더링이 완료되면 React는 이를 화면에 표시함. 그러나 일시 중단되면("ab"에 대한 결과가 아직 로드되지 않은 경우) React는 이 렌더링 시도를 포기하고 데이터가 로드된 후 이 리렌더링을 다시 시도함. 사용자는 데이터가 준비될 때까지 계속 지연된 이전 값을 보게 됨.
   지연된 '백그라운드' 렌더링은 중단할 수 있음(interruptible). 예를 들어, 사용자가 input에 다시 타이핑하면 React는 진행중이던 백그라운드 렌더링을 포기하고 새 값으로 다시 백그라운드 렌더링을 시작함. React는 항상 제공받은 최신 값을 사용함.
   키 입력마다 여전히 네트워크 요청이 있다는 점에 유의할 것. 여기서 지연되는 것은 네트워크 요청 자체가 아니라 결과가 준비될 때까지 결과를 표시하는 것. 사용자가 계속 타이핑하더라도 각 키 입력에 대한 응답은 캐시되므로 백스페이스 키를 누르더라도 데이터를 다시 가져오지 않음.

Indicating that the content is stale

위의 예에서는 최신 쿼리에 대한 결과 목록이 아직 로드 중이라는 표시가 없음. 새 결과를 로드하는 데 시간이 오래 걸리는 경우 사용자가 혼란스러워할 수 있음. 결과 목록이 최신 쿼리와 일치하지 않는다는 것을 사용자에게 더 명확하게 알리기 위해 이전 결과 목록이 표시되는 동안 visual indication을 추가할 수 있음:

<div style={{
  opacity: query !== deferredQuery ? 0.5 : 1,
}}>
  <SearchResults query={deferredQuery} />
</div>

이렇게 하면 타이핑을 시작하자마자 새 결과 목록이 로드될 때까지 이전 결과 목록이 약간 어두워짐. 아래 예시처럼 CSS transition을 추가하여 흐리게 표시되는 시간을 지연시켜 점진적으로 느껴지도록 할 수도 있음:

import { Suspense, useState, useDeferredValue } from 'react';
import SearchResults from './SearchResults.js';

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={{
          opacity: isStale ? 0.5 : 1,
          transition: isStale ? 'opacity 0.2s 0.2s linear' : 'opacity 0s 0s linear'
        }}>
          <SearchResults query={deferredQuery} />
        </div>
      </Suspense>
    </>
  );
}

Deferring re-rendering for a part of the UI

성능 최적화를 위해 useDeferredValue를 적용할 수도 있음. UI의 일부가 리렌더링되는 속도가 느리고, 이를 최적화할 쉬운 방법이 없으며, 이것이 나머지 UI를 blocking하지 않도록 하려는 경우에 유용함.

키 입력 시마다 다시 렌더링되는 text field와, chart 또는 긴 목록과 같은 컴포넌트가 있다고 가정하면:

function App() {
  const [text, setText] = useState('');
  return (
    <>
      <input value={text} onChange={e => setText(e.target.value)} />
      <SlowList text={text} />
    </>
  );
}

먼저, props가 동일한 경우 리렌더링하지 않도록 SlowList를 memo로 감싸서 optimize함:

const SlowList = memo(function SlowList({ text }) {
  // ...
});

하지만 이 방법은 이전 렌더링 때와 SlowList의 props가 동일한 경우에만 도움이 됨. 지금 직면하고 있는 문제는 이전 렌더링과 현재 렌더링의 props가 서로 다를 때, 그리고 실제로 다른 시각적 출력을 표시해야 할 때 속도가 느리다는 것.

구체적으로, 주요한 성능 문제는 사용자가 input에 타이핑할 때마다 SlowList가 새로운 props를 받아서 전체 트리를 리렌더링하기 때문에 타이핑이 끊기는 느낌이 든다는 것. 이 경우, useDeferredValue를 사용하면 결과 목록 업데이트(느려도 됨)보다 입력 업데이트(빨라야 함)의 우선순위를 높일 수 있음:

function App() {
  const [text, setText] = useState('');
  const deferredText = useDeferredValue(text);
  return (
    <>
      <input value={text} onChange={e => setText(e.target.value)} />
      <SlowList text={deferredText} />
    </>
  );
}

이렇게 한다고 해서 SlowList의 리렌더링 속도가 빨라지지는 않음. 하지만 키 입력을 차단하지 않도록 목록 리렌더링의 우선순위를 낮출 수 있다는 것을 React에 알려줌. 목록은 input보다 "지연"되었다가 input을 "따라잡음". 이전과 마찬가지로 React는 가능한 한 빨리 목록을 업데이트하려고 시도하지만 사용자가 입력하는 것을 차단하지는 않음.

Pitfall

이 최적화를 위해서는 SlowList를 memo로 감싸는 것이 필요함. text가 변경될 때마다 React가 부모 컴포넌트를 빠르게 리렌더링할 수 있어야 하기 때문. 리렌더링하는 동안 deferredText는 여전히 이전 값을 가지므로 SlowList는 리렌더링을 건너뛸 수 있음(props가 변경되지 않았기 때문). memo가 없다면 어쨌든 리렌더링해야 하므로 최적화의 의미가 무색해짐.

DEEP DIVE: How is deferring a value different from debouncing and throttling?

이 시나리오에서 이전에 사용했을 수 있는 두 가지 일반적인 최적화 기술:

• Debouncing은 사용자가 입력을 멈출 때까지(예: 1초 동안) 기다렸다가 목록을 업데이트하는 것
• Throttling은 목록을 가끔씩(예: 최대 1초에 한 번) 업데이트하는 것
  이러한 기법들은 경우에 따라 유용하지만, 렌더링을 최적화하는 데는 React 자체와 긴밀하게 통합되어 있고 사용자의 기기에 맞게 조정되는 useDeferredValue가 더 적합함.
  Debouncing이나 throttling과 달리, useDeferredValue는 고정 지연을 선택할 필요가 없음. 사용자의 디바이스가 빠른 경우(예: 고성능 노트북), 지연된 리렌더링은 거의 즉시 발생하며 눈에 띄지 않을 것. 사용자의 디바이스가 느리면 디바이스가 느린 정도에 비례하여 목록이 input보다 '뒤쳐짐'.
  또한 debouncing이나 throttling과 달리, useDeferredValue로 수행되는 지연된 리렌더링은 기본적으로 중단할 수 있음. 즉, React가 큰 목록을 리렌더링하는 도중에 사용자가 다른 키를 입력하면 React는 해당 리렌더링을 중단하고 키 입력을 처리한 다음 백그라운드에서 리렌더링을 시작함. 반면, debouncing과 throttling은 렌더링이 키 입력을 차단하는 순간을 지연할 뿐이므로 여전히 불규칙한 경험을 제공함.
  최적화하려는 작업이 렌더링 중에 발생하지 않는 경우에도 debouncing과 throttling은 여전히 유용함. 예를 들어, debouncing과 throttling을 사용하면 네트워크 요청을 더 적게 실행할 수 있음. 이러한 기술을 함께 사용할 수도 있음.

Pitfall

useInsertionEffect는 CSS-in-JS 라이브러리 작성자를 위한 것. CSS-in-JS 라이브러리에서 작업하고 스타일을 삽입할 위치가 필요한 경우가 아니라면 useEffect 또는 useLayoutEffect를 대신 사용할 수 있음.

useInsertionEffect를 사용하면 레이아웃 효과가 실행되기 전에 요소를 DOM에 삽입할 수 있음.

useInsertionEffect(setup, dependencies?)

Reference

useInsertionEffect(setup, dependencies?)

레이아웃을 읽어야하는 effect가 실행되기 전에 스타일을 삽입하려면 useInsertionEffect를 호출:

import { useInsertionEffect } from 'react';

// Inside your CSS-in-JS library
function useCSS(rule) {
  useInsertionEffect(() => {
    // ... inject <style> tags here ...
  });
  return rule;
}

Parameters

• setup: Effect의 로직이 포함된 함수. Setup 함수는 선택적으로 cleanup 함수를 반환할 수도 있음. 컴포넌트가 DOM에 추가되었지만 레이아웃 effect가 실행되기 전에 React는 setup 함수를 실행함. 변경된 dependencies로 다시 렌더링할 때마다 React는 먼저 (사용자가 제공한 경우) 이전 값으로 cleanup 함수를 실행한 다음 새 값으로 setup 함수를 실행함. 컴포넌트가 DOM에서 제거되면 React는 cleanup 함수를 실행함.

• dependencies (optional): setup 코드 내에서 참조된 모든 반응형 값의 목록. 반응형 값에는 props, state, 컴포넌트 본문 내부에서 직접 선언된 모든 변수와 함수가 포함됨. Linter가 React에 대해 구성된 경우, 모든 반응형 값이 dependency로 올바르게 지정되었는지 확인함. Dependencies 목록에는 일정한 수의 항목이 있어야 하며 [dep1, dep2, dep3]와 같이 인라인으로 작성해야 함. React는 Object.is 비교 알고리즘을 사용하여 각 dependency를 이전 값과 비교함. Dependencies를 전혀 지정하지 않으면 컴포넌트를 다시 렌더링할 때마다 Effect가 다시 실행됨.

Returns

undefined를 반환함.

Caveats

• Effect는 클라이언트에서만 실행됨. 서버 렌더링 중에는 실행되지 않음.
• useInsertionEffect 내부에서는 state를 업데이트할 수 없음.
• useInsertionEffect가 실행될 때까지 참조는 아직 첨부되지 않음.
• useInsertionEffect는 DOM이 업데이트되기 전이나 후에 실행될 수 있음. 특정 시점에 DOM이 업데이트되는 것에 의존해서는 안됨.
• 모든 Effect에 대해 cleanup을 실행한 다음 모든 Effect에 대해 setup을 실행하는 다른 유형의 Effect와 달리, useInsertionEffect는 한 번에 하나의 컴포넌트에 대해 cleanup과 setup을 모두 실행함. 그 결과 cleanup과 setup 함수가 "interleaving"됨.

Usage

Injecting dynamic styles from CSS-in-JS libraries

기존에는 일반 CSS를 사용하여 React 컴포넌트의 스타일을 지정했음.

// In your JS file:
<button className="success" />

// In your CSS file:
.success { color: green; }

일부 팀은 CSS 파일을 작성하는 대신 JavaScript 코드에서 직접 스타일을 작성하는 것을 선호함. 이를 위해서는 일반적으로 CSS-in-JS 라이브러리 또는 도구를 사용해야 함. CSS-in-JS에는 세 가지 일반적인 접근 방식이 있음:

1. 컴파일러를 사용하여 CSS 파일로 정적 추출하기
2. 인라인 스타일(예: <div style={{ opacity: 1 }}>)
3. <style> 태그의 런타임 삽입

CSS-in-JS를 사용하는 경우 처음 두 가지 접근 방식(정적 스타일의 경우 CSS 파일, 동적 스타일의 경우 인라인 스타일)을 조합하여 사용하는 것이 좋음. 런타임 <style> 태그 삽입은 두 가지 이유로 권장하지 않음:

1. 런타임 삽입으로 인해 브라우저가 스타일을 훨씬 더 자주 다시 계산해야 함.
2. 런타임 삽입이 React 라이프사이클에서 잘못된 시점에 발생하면 속도가 매우 느려질 수 있음.

첫 번째 문제는 해결할 수 없지만, useInsertionEffect는 두 번째 문제를 해결하는 데 도움이 됨.

레이아웃 effect가 실행되기 전에 스타일을 삽입하려면 useInsertionEffect를 호출:

// Inside your CSS-in-JS library
let isInserted = new Set();
function useCSS(rule) {
  useInsertionEffect(() => {
    // As explained earlier, we don't recommend runtime injection of <style> tags.
    // But if you have to do it, then it's important to do in useInsertionEffect.
    if (!isInserted.has(rule)) {
      isInserted.add(rule);
      document.head.appendChild(getStyleForRule(rule));
    }
  });
  return rule;
}

function Button() {
  const className = useCSS('...');
  return <div className={className} />;
}

useEffect와 마찬가지로 useInsertionEffect는 서버에서 실행되지 않음. 서버에서 어떤 CSS 규칙이 사용되었는지 수집해야 하는 경우 렌더링 중에 수집할 수 있음:

let collectedRulesSet = new Set();

function useCSS(rule) {
  if (typeof window === 'undefined') {
    collectedRulesSet.add(rule);
  }
  useInsertionEffect(() => {
    // ...
  });
  return rule;
}

DEEP DIVE: How is this better than injecting styles during rendering or useLayoutEffect?

렌더링 중에 스타일을 삽입하고 React가 non-blocking 업데이트를 처리하는 경우 브라우저는 컴포넌트 트리를 렌더링하는 동안 매 프레임마다 스타일을 다시 계산하므로 속도가 매우 느려질 수 있음.

useInsertionEffect는 컴포넌트에서 다른 Effect가 실행될 때쯤 이미 <style> 태그가 삽입되어 있을 것을 보장하기 때문에, useLayoutEffect나 useEffect중에 스타일을 삽입하는 것보다 나음. 그렇지 않으면 오래된 스타일로 인해 일반 Effect의 레이아웃 계산이 잘못될 수 있음.

Pitfall

useLayoutEffect는 성능을 저하시킬 수 있음. 가능하면 useEffect를 사용하는 것이 좋음.

브라우저가 화면을 다시 그리기 전에 실행되는 useEffect의 한 버전

useLayoutEffect(setup, dependencies?)

Reference

useLayoutEffect(setup, dependencies?)

브라우저가 화면을 다시 그리기 전에 useLayoutEffect를 호출하여 레이아웃 측정을 수행:

import { useState, useRef, useLayoutEffect } from 'react';

function Tooltip() {
  const ref = useRef(null);
  const [tooltipHeight, setTooltipHeight] = useState(0);

  useLayoutEffect(() => {
    const { height } = ref.current.getBoundingClientRect();
    setTooltipHeight(height);
  }, []);

  // ...

Parameters

• setup: Effect의 로직이 포함된 함수. Setup 함수는 선택적으로 'cleanup' 함수를 반환할 수도 있음. 컴포넌트가 DOM에 추가되기 전에 React는 setup 함수를 실행함. 변경된 dependencies로 다시 렌더링할 때마다 React는 먼저 이전 값으로 cleanup 함수(제공한 경우)를 실행한 다음 새 값으로 setup 함수를 실행함. 컴포넌트가 DOM에서 제거되기 전에 React는 cleanup 함수를 실행함.

• dependencies (optional): setup 코드 내에서 참조된 모든 반응형 값의 목록. 반응형 값에는 props, state, 컴포넌트 본문에서 직접 선언된 모든 변수와 함수가 포함됨. Linter가 React에 대해 구성된 경우, 모든 반응형 값이 dependency로 올바르게 지정되었는지 확인함. Dependencies 목록에는 일정한 수의 항목이 있어야 하며 [dep1, dep2, dep3]와 같이 인라인으로 작성해야함. React는 Object.is 비교를 사용하여 각 dependency를 이전 값과 비교함. 이 인수를 생략하면 컴포넌트를 다시 렌더링할 때마다 Effect가 다시 실행됨.

Returns

undefined를 반환함.

Caveats

• useLayoutEffect는 Hook이므로 컴포넌트의 최상위 레벨 또는 자체 Hook에서만 호출할 수 있음. 루프나 조건 안에서는 호출할 수 없음. 필요하다면 컴포넌트를 추출하고 Effect를 그곳으로 이동할 것.

• Strict Mode가 켜져 있으면 React는 첫 번째 실제 setup 전에 개발 전용 setup + cleanup 사이클을 한 번 더 실행함. 이는 cleanup 로직이 setup 로직을 "미러링"하고 setup이 수행 중인 모든 작업을 중지하거나 취소하는지 확인하는 스트레스 테스트임. 문제가 발생하면 cleanup 기능을 구현할 것.

• Dependencies 중 일부가 컴포넌트 내부에 정의된 객체 또는 함수인 경우, 이로 인해 Effect가 필요 이상으로 자주 다시 실행될 위험이 있음. 이 문제를 해결하려면 불필요한 객체 및 함수 dependency를 제거할 것. 또한 state 업데이트와 비반응성 로직을 Effect 외부로 추출할 수도 있음.

• Effect는 클라이언트에서만 실행됨. 서버 렌더링 중에는 실행되지 않음.

• useLayoutEffect 내부의 코드와 여기서 예약된 모든 state 업데이트는 브라우저가 화면을 다시 그리는 것을 차단하므로 과도하게 사용하면 앱이 느려짐. 가능하면 useEffect를 사용하는 것이 좋음.

Usage

Measuring layout before the browser repaints the screen

대부분의 컴포넌트는 무엇을 렌더링할지 결정하기 위해 화면에서 자신의 위치와 크기를 알 필요 없이, 그저 JSX만 반환함. 그러면 브라우저는 레이아웃(위치 및 크기)을 계산하고 화면을 다시 그림.

때로는 이것만으로는 충분하지 않음. Hover 시 어떤 요소 옆에 표시되는 tooltip을 상상해보면, 공간이 충분하다면 tooltip이 요소 위에 표시되어야 하지만, 공간이 충분하지 않다면 아래에 표시되어야 함. Tooltip을 올바른 최종 위치에 렌더링하려면 tooltip의 높이(즉, 요소 위의 공간에 배치될 수 있는지)를 알아야 함.

이를 위해서는 두 번의 패스로 렌더링해야 함:

1. Tooltip을 아무 곳에나 렌더링(위치가 잘못된 경우에도).
2. 높이를 측정하고 tooltip을 배치할 위치를 결정.
3. Tooltip을 올바른 위치에 다시 렌더링.

이 모든 작업은 브라우저가 화면을 다시 그리기 전에 이루어져야 함. 사용자에게 tooltip이 움직이는 모습을 보여서는 안됨. 브라우저가 화면을 다시 그리기 전에 useLayoutEffect를 호출하여 레이아웃 측정을 수행할 것:

function Tooltip() {
  const ref = useRef(null);
  const [tooltipHeight, setTooltipHeight] = useState(0); // You don't know real height yet

  useLayoutEffect(() => {
    const { height } = ref.current.getBoundingClientRect();
    setTooltipHeight(height); // Re-render now that you know the real height
  }, []);

  // ...use tooltipHeight in the rendering logic below...
}

단계별 작동 방식은 다음과 같음:

1. Tooltip은 초기 tooltipHeight = 0으로 렌더링됨(따라서 툴팁의 위치가 잘못될 수 있음).

2. React는 tooltip을 DOM에 배치하고 useLayoutEffect의 코드를 실행함.

3. useLayoutEffect는 tooltip 콘텐츠의 높이를 측정하고 즉시 다시 렌더링을 트리거함.

4. Tooltip은 실제 tooltipHeight로 다시 렌더링됨(따라서 tooltip의 위치가 올바르게 지정됨).

5. React는 DOM에서 이를 업데이트하고 브라우저는 마침내 tooltip을 표시함.

// Tooltip.js
import { useRef, useLayoutEffect, useState } from 'react';
import { createPortal } from 'react-dom';
import TooltipContainer from './TooltipContainer.js';

export default function Tooltip({ children, targetRect }) {
  const ref = useRef(null);
  const [tooltipHeight, setTooltipHeight] = useState(0);

  useLayoutEffect(() => {
    const { height } = ref.current.getBoundingClientRect();
    setTooltipHeight(height);
    console.log('Measured tooltip height: ' + height);
  }, []);

  let tooltipX = 0;
  let tooltipY = 0;
  if (targetRect !== null) {
    tooltipX = targetRect.left;
    tooltipY = targetRect.top - tooltipHeight;
    if (tooltipY < 0) {
      // It doesn't fit above, so place below.
      tooltipY = targetRect.bottom;
    }
  }

  return createPortal(
    <TooltipContainer x={tooltipX} y={tooltipY} contentRef={ref}>
      {children}
    </TooltipContainer>,
    document.body
  );
}

Tooltip 컴포넌트가 두 번에 걸쳐(먼저, 0으로 초기화 된 tooltipHeight로, 다음은 실제 측정된 높이로) 렌더링되어야 함에도 불구하고 최종 결과만 표시된다는 점에 유의할 것.

Note

두 번에 걸쳐 렌더링하고 브라우저를 blocking하면 성능이 저하됨. 가능한 한 이를 피할 것.

Troubleshooting

I’m getting an error: ”useLayoutEffect does nothing on the server”

useLayoutEffect의 목적은 컴포넌트가 렌더링에 레이아웃 정보를 사용할 수 있도록 하는 것:

1. 초기 콘텐츠 렌더링
2. 브라우저가 화면을 다시 그리기 전에 레이아웃 측정
3. 읽은 레이아웃 정보를 사용하여 최종 콘텐츠 렌더링

사용자 또는 프레임워크가 서버 렌더링을 사용하는 경우, React 앱은 초기 렌더링을 할 때 서버의 HTML에 렌더링함. 이를 통해 JavaScript 코드가 로드되기 전에 초기 HTML을 표시할 수 있음.

문제는 서버에 레이아웃 정보가 없다는 것!

앞선 예제에서 Tooltip 컴포넌트의 useLayoutEffect 호출은 콘텐츠 높이에 따라 콘텐츠 위 또는 아래에 올바르게 배치될 수 있도록 함. 초기 서버 HTML의 일부로 Tooltip을 렌더링하려고 했다면 이를 결정할 수 없었을 것. 서버에는 아직 레이아웃이 없기 때문! 따라서 서버에서 렌더링하더라도 JavaScript가 로드되고 실행된 후 클라이언트에서 그 위치가 '점프'됨.

일반적으로 레이아웃 정보에 의존하는 컴포넌트는 서버에서 렌더링할 필요가 없음. 예를 들어, 초기 렌더링 중에 Tooltip을 표시하는 것은 의미가 없을 수 있음. Tooltip은 클라이언트 상호작용에 의해 트리거됨.

그러나 이 문제를 해결할 몇 가지 다른 방법이 있음:

• useLayoutEffect대신 useEffect를 사용할 것. 이렇게 하면 React가 페인트를 막지 않고 초기 렌더링 결과를 표시해도 괜찮다는 것을 알 수 있음(Effect가 실행되기 전에 원래 HTML이 표시되기 때문).

• 또는 컴포넌트를 클라이언트 전용으로 표시할 것. 이렇게 하면 서버 렌더링 중에 가장 가까운 <Suspense> 바운더리까지의 콘텐츠를 loading fallback(예: spinner 또는 glimmer)으로 대체하도록 React에 지시할 수 있음.

• 또는 hydration 후에 useLayoutEffect를 사용하여 컴포넌트를 렌더링할 수 있음. false로 초기화된 boolean isMounted state를 유지하고, useEffect 호출 내에서 true로 설정한 후 렌더링 로직은 return isMounted ? <RealContent /> : <FallbackContent />처럼 작성할 것. 서버에서와 hydration 중에 사용자는 useLayoutEffect를 호출해서는 안 되는 FallbackContent를 보게 됨. 그런 다음 React는 이를 클라이언트에서만 실행되고useLayoutEffect 호출을 포함할 수 있는 RealContent로 대체함.

• 컴포넌트를 외부 데이터 저장소와 동기화하고 레이아웃 측정이 아닌 다른 이유로 useLayoutEffect에 의존하는 경우, 서버 렌더링을 지원하는 useSyncExternalStore를 대신 고려할 것.

const SomeContext = createContext(defaultValue)

Reference

createContext(defaultValue)

컴포넌트 외부에서 createContext를 호출하여 컨텍스트를 생성함.

import { createContext } from 'react';

const ThemeContext = createContext('light');

Parameters

• defaultValue: Context를 읽는 컴포넌트 위의 트리에 일치하는 context provider가 없을 때 context에 적용할 값. 의미 있는 기본값이 없는 경우 null을 지정함. 기본값은 "최후의 수단"으로 사용되는 것. 기본값은 정적이며 시간이 지나도 변경되지 않음.

Returns

Context 객체를 반환함.

Context 객체 자체는 어떠한 정보도 보유하지 않고, 다른 컴포넌트가 읽거나 제공하는 context가 어떤 context인지를 나타냄. 일반적으로 상위 컴포넌트에서 SomeContext.Provider를 사용하여 context 값을 지정하고, 아래 컴포넌트에서 useContext(SomeContext)를 호출하여 값을 읽음. Context 객체에는 몇 가지 프로퍼티가 있음:

• SomeContext.Provider는 컴포넌트에 context 값을 제공할 수 있음.
• SomeContext.Consumer는 context 값을 읽는 대체 방법이며 거의 사용되지 않음.

SomeContext.Provider

컴포넌트를 context provider로 감싸면 내부의 모든 컴포넌트에 대해 이 context의 값을 지정할 수 있음:

function App() {
  const [theme, setTheme] = useState('light');
  // ...
  return (
    <ThemeContext.Provider value={theme}>
      <Page />
    </ThemeContext.Provider>
  );
}

Props

• value: 이 provider 내에서 이 context를 읽는 모든 컴포넌트에 (깊이에 상관없이) 전달할 값. Context 값은 모든 타입이 될 수 있음. Provider 내부에서 useContext(SomeContext)를 호출하는 컴포넌트는 그 상위에 있는 가장 안쪽의 context provider의 value를 받음.

SomeContext.Consumer

useContext가 존재하기 전에, context를 읽던 방식:

function Button() {
  // 🟡 Legacy way (not recommended)
  return (
    <ThemeContext.Consumer>
      {theme => (
        <button className={theme} />
      )}
    </ThemeContext.Consumer>
  );
}

이 이전 방식은 여전히 작동하지만 새로 작성된 코드는 대신 useContext(SomeContext)를 사용하여 context를 읽어야함:

function Button() {
  // ✅ Recommended way
  const theme = useContext(ThemeContext);
  return <button className={theme} />;
}

Props

• children: 함수. React는 useContext()와 동일한 알고리즘에 의해 결정된 현재 context 값으로 전달한 함수를 호출하고, 이 함수에서 반환한 결과를 렌더링함. 또한 React는 부모 컴포넌트의 context가 변경될 때마다 이 함수를 다시 실행하고 UI를 업데이트함.

Usage

Creating context

Context는 컴포넌트가 props를 명시적으로 전달하지 않고도 정보를 깊은 곳까지 전달할 수 있게 함.

우선, 컴포넌트 외부에서 createContext를 호출하여 하나 이상의 context를 생성:

import { createContext } from 'react';

const ThemeContext = createContext('light');
const AuthContext = createContext(null);

createContext는 context 객체를 반환함. 컴포넌트는 context를 useContext()에 전달하여 context를 읽을 수 있음:

function Button() {
  const theme = useContext(ThemeContext);
  // ...
}

function Profile() {
  const currentUser = useContext(AuthContext);
  // ...
}

기본적으로 받는 값은 context를 만들 때 지정한 기본값이 됨. 그러나 기본값은 절대 변경되지 않으므로 그 자체로는 유용하지 않음.

Context가 유용한 이유는 컴포넌트에서 다른 동적 값을 제공할 수 있기 때문:

function App() {
  const [theme, setTheme] = useState('dark');
  const [currentUser, setCurrentUser] = useState({ name: 'Taylor' });

  // ...

  return (
    <ThemeContext.Provider value={theme}>
      <AuthContext.Provider value={currentUser}>
        <Page />
      </AuthContext.Provider>
    </ThemeContext.Provider>
  );
}

이제 Page 컴포넌트와 그 안에 있는 모든 컴포넌트는 아무리 깊숙이 들어가도 전달된 context 값을 '보게' 됨. 전달된 context 값이 변경되면 React는 context를 읽는 컴포넌트도 다시 렌더링함.

참고: 컨텍스트 읽기 및 제공하기

Importing and exporting context from a file

서로 다른 파일에 있는 컴포넌트가 동일한 context에 접근해야 하는 경우가 종종 있음. 그렇기 때문에 context를 별도의 파일에 선언하는 것이 일반적임. 그런 다음 export 문을 사용하여 다른 파일에서 context를 사용할 수 있도록 할 수 있음:

// Contexts.js
import { createContext } from 'react';

export const ThemeContext = createContext('light');
export const AuthContext = createContext(null);

그런 다음, 다른 파일에서 선언된 컴포넌트는 import 문을 사용하여 이 context를 읽거나 제공할 수 있음:

// Button.js
import { ThemeContext } from './Contexts.js';

function Button() {
  const theme = useContext(ThemeContext);

  // ...
}

// App.js
import { ThemeContext, AuthContext } from './Contexts.js';

function App() {

  // ...

  return (
    <ThemeContext.Provider value={theme}>
      <AuthContext.Provider value={currentUser}>
        <Page />
      </AuthContext.Provider>
    </ThemeContext.Provider>
  );
}

이는 컴포넌트 가져오기 및 내보내기와 유사하게 작동함.

Troubleshooting

I can’t find a way to change the context value

다음과 같은 코드는 기본 context 값을 지정함:

const ThemeContext = createContext('light');

이 값은 절대 변하지 않음. React는 상위에서 일치하는 provider를 찾을 수 없는 경우에만 이 값을 fallback으로 사용함.

시간이 지남에 따라 context가 변경되도록 하려면 context provider더에 state와 래핑 컴포넌트를 추가할 것.

const value = useContext(SomeContext)

Reference

useContext(SomeContext)

컴포넌트의 최상위 수준에서 useContext를 호출하여 context를 읽고 구독할 수 있음.

import { useContext } from 'react';

function MyComponent() {
  const theme = useContext(ThemeContext);

  // ...

Parameters

• someContext: 이전에 createContext로 생성한 context입니다. Context 자체는 정보를 보유하지 않으며, 컴포넌트에서 제공하거나 읽을 수 있는 정보의 종류를 나타낼 뿐.

Returns

useContext는 호출하는 컴포넌트의 context 값을 반환함. 이 값은 트리에서 호출 컴포넌트 위에 있는 가장 가까운 SomeContext.Provider에 전달된 값으로 결정됨. 그러한 provider가 없는 경우 반환되는 값은 해당 context에 대해 createContext에 전달한 defaultValue가 됨. 반환된 값은 항상 최신 값임. React는 context가 변경되면 context를 읽는 컴포넌트를 자동으로 다시 렌더링함.

Caveats

• 컴포넌트의 useContext() 호출은 동일한 컴포넌트에서 반환된 provider의 영향을 받지 않음. 해당 <Context.Provider>는 useContext() 호출을 수행하는 컴포넌트 위에 있어야 함.
• React는 다른 value를 받는 provider부터 시작해서 특정 context를 사용하는 모든 자식들을 자동으로 다시 렌더링함. 이전 값과 다음 값은 Object.is를 통해 비교됨. memo로 재렌더링을 건너뛰어도 자식들이 새로운 context 값을 받는 것을 막지는 못함.
• 빌드 시스템에서 결과로 중복 모듈을 생성하는 경우(symlinks에서 발생할 수 있음) context가 손상될 수 있음. Context를 통해 무언가를 전달하는 것은 context를 제공하는 데 사용하는 someContext와 context를 읽는 데 사용하는 someContext가 === 비교에 의해 결정되는 정확히 동일한 객체인 경우에만 작동함.

Usage

Passing data deeply into the tree

컴포넌트의 최상위 수준에서 useContext를 호출하여 context를 읽고 구독할 수 있음.

import { useContext } from 'react';

function Button() {
  const theme = useContext(ThemeContext);

  // ...

useContext는 전달한 context에 대한 context 값을 반환함. Context 값을 결정하기 위해 React는 컴포넌트 트리를 검색하고 특정 context에 대해 가장 가까운 상위 context provider를 찾음.

Context를 Button에 전달하려면 Button 또는 그 부모 컴포넌트 중 하나를 해당 context provider로 감쌀 것:

function MyPage() {
  return (
    <ThemeContext.Provider value="dark">
      <Form />
    </ThemeContext.Provider>
  );
}

function Form() {

  // ... renders buttons inside ...
}

Provider와 Button 사이에 얼마나 많은 컴포넌트 레이어가 있는지는 중요하지 않음. Form 내부의 버튼이 useContext(ThemeContext)를 호출하면 "dark"를 값으로 받음.

Pitfall

useContext()는 항상 이를 호출하는 컴포넌트 '상위'에서 가장 가까운 provider를 찾음. useContext()를 호출하는 컴포넌트 내의 provider는 고려하지 않음.

Updating data passed via context

시간이 지남에 따라 context가 변경되기를 원하는 경우가 종종 있음. Context를 업데이트하려면 context를 state와 결합할 것. 부모 컴포넌트에서 state 변수를 선언하고 현재 state를 context 값으로 provider에게 전달하면 됨.

function MyPage() {
  const [theme, setTheme] = useState('dark');
  return (
    <ThemeContext.Provider value={theme}>
      <Form />
      <Button onClick={() => {
        setTheme('light');
      }}>
        Switch to light theme
      </Button>
    </ThemeContext.Provider>
  );
}

이제 provider 내부의 모든 Button이 현재 theme 값을 받게 됨. setTheme을 호출하여 provider에게 전달한 theme 값을 업데이트하면 모든 Button 컴포넌트가 새로운 'light' 값으로 다시 렌더링됨.

Specifying a fallback default value

React가 부모 트리에서 특정 context의 provider를 찾을 수 없는 경우, useContext()가 반환하는 context 값은 해당 context를 생성할 때 지정한 기본값과 같음:

const ThemeContext = createContext(null);

기본값은 변경되지 않음. Context를 업데이트하려면 위에서 설명한 대로 state와 함께 사용해야 함.

예를 들어, null 대신 더 의미 있는 값을 기본값으로 사용할 수 있는 경우가 종종 있음:

const ThemeContext = createContext('light');

이렇게 하면 실수로 해당 provider 없이 일부 컴포넌트를 렌더링해도 깨지지 않음. 또한 테스트 환경에서 많은 provider를 설정하지 않고도 컴포넌트가 잘 작동하도록 도와줌.

Overriding context for a part of the tree

트리의 일부분을 다른 값의 provider로 감싸면 해당 부분에 대한 context를 재정의할 수 있음.

<ThemeContext.Provider value="dark">
  ...

  <ThemeContext.Provider value="light">
    <Footer />
  </ThemeContext.Provider>

  ...
</ThemeContext.Provider>

필요한 만큼 provider를 중첩하고 재정의할 수 있음.

Optimizing re-renders when passing objects and functions

Context를 통해 객체와 함수를 포함한 모든 값을 전달할 수 있음.

function MyApp() {
  const [currentUser, setCurrentUser] = useState(null);

  function login(response) {
    storeCredentials(response.credentials);
    setCurrentUser(response.user);
  }

  return (
    <AuthContext.Provider value={{ currentUser, login }}>
      <Page />
    </AuthContext.Provider>
  );
}

여기서 context 값은 두 개의 프로퍼티를 가진 JavaScript 객체이며, 그 중 하나는 함수임. 이 객체는 MyApp이 route 업데이트 등의 이유로 다시 렌더링될 때마다 다른 함수를 가리키는 다른 객체가 될 것이므로, React는 useContext(AuthContext)를 호출하는 트리 깊숙한 곳의 모든 컴포넌트를 다시 렌더링해야함.

작은 앱에서는 문제가 되지 않기는 하지만, currentUser와 같은 기본 데이터가 변경되지 않았다면 다시 렌더링할 필요가 없음. React가 이 사실을 활용하도록 돕기 위해 login 함수를 useCallback으로 감싸고 객체 생성을 useMemo로 감쌀 수 있음. 이것은 성능 최적화를 위한 것:

import { useCallback, useMemo } from 'react';

function MyApp() {
  const [currentUser, setCurrentUser] = useState(null);

  const login = useCallback((response) => {
    storeCredentials(response.credentials);
    setCurrentUser(response.user);
  }, []);

  const contextValue = useMemo(() => ({
    currentUser,
    login
  }), [currentUser, login]);

  return (
    <AuthContext.Provider value={contextValue}>
      <Page />
    </AuthContext.Provider>
  );
}

이렇게 변경하면, MyApp이 다시 렌더링되어야 하는 경우에도 currentUser가 변경되지 않는 한 useContext(AuthContext)를 호출하는 컴포넌트는 다시 렌더링할 필요가 없음.

참고: useCallback, useMemo

Troubleshooting

My component doesn’t see the value from my provider

이러한 일이 발생하는 몇 가지 일반적인 상황이 있음:

1. useContext()를 호출하는 곳과 동일한 컴포넌트(또는 그 아래)에서 <SomeContext.Provider>를 렌더링하는 경우. <SomeContext.Provider>를 useContext()를 호출하는 컴포넌트의 위와 바깥으로 이동할 것.
2. 컴포넌트를 <SomeContext.Provider>로 감싸는 것을 잊었거나 생각했던 것과 다른 트리 부분에 넣었을 경우. React 개발자 도구를 사용하여 계층 구조가 올바른지 확인할 것.
3. Tooling에서 빌드 문제가 발생하여 provider 컴포넌트에서 보는 SomeContext와 reading 컴포넌트에서 보는 SomeContext가 두 개의 다른 객체가 될 수 있음. 예를 들어, symlinks를 사용하는 경우 이런 문제가 발생할 수 있음. 이를 확인하려면 각 SomeContext를 window.SomeContext1 및 window.SomeContext2처럼 전역에 할당하고 콘솔에서 window.SomeContext1 === window.SomeContext2인지 확인하면 됨. 동일하지 않은 경우 빌드 tool 수준에서 해당 문제를 수정할 것.

I am always getting undefined from my context although the default value is different

트리에 value가 없는 provider가 있을 수 있음:

// 🚩 Doesn't work: no value prop
<ThemeContext.Provider>
   <Button />
</ThemeContext.Provider>

value를 지정하는 것을 잊어버리면 value={undefined}를 전달하는 것과 같음.

실수로 다른 prop 이름을 잘못 사용했을 수도 있음:

// 🚩 Doesn't work: prop should be called "value"
<ThemeContext.Provider theme={theme}>
   <Button />
</ThemeContext.Provider>

이 두 가지 경우 모두 콘솔에서 React의 경고가 표시될 것. 이를 수정하려면 prop value을 호출할 것:

// ✅ Passing the value prop
<ThemeContext.Provider value={theme}>
   <Button />
</ThemeContext.Provider>

createContext(defaultValue) 호출의 기본값은 위에 일치하는 provider가 전혀 없는 경우에만 사용된다는 점에 유의할 것. 부모 트리 어딘가에 <SomeContext.Provider value={undefined}> 컴포넌트가 있는 경우, useContext(SomeContext)를 호출하는 컴포넌트는 undefined를 context 값으로 받음.