주의하세요!

renderToString은 스트리밍이나 데이터 대기를 지원하지 않습니다. 대안을 참고하세요.

renderToString은 React 트리를 HTML 문자열로 렌더링합니다.

const html = renderToString(reactNode, options?)

레퍼런스

renderToString(reactNode, options?)

서버에서 renderToString을 실행하면 앱을 HTML로 렌더링합니다.

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

const html = renderToString(<App />);

클라이언트에서 hydrateRoot을 호출하면 서버에서 생성된 HTML을 상호작용하게 만듭니다.

아래에서 더 많은 예시를 참고하세요.

매개변수

  • reactNode: HTML로 렌더링할 React 노드입니다. 예를 들어 <App />과 같은 JSX 노드입니다.
  • optional options: 서버 렌더링을 위한 객체입니다.
    • optional identifierPrefix: useId.에 의해 생성된 ID에 대해 React가 사용하는 문자열 접두사입니다. 같은 페이지에서 여러 루트를 사용할 때 충돌을 피하기 위해 유용합니다. hydrateRoot.에 전달된 접두사와 동일해야 합니다.

반환값

HTML 문자열.

주의사항

  • renderToString는 Suspense 지원에 한계가 있습니다. 컴포넌트가 중단된다면 renderToString는 즉시 해당 폴백을 HTML로 보냅니다.

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

사용법

React 트리를 HTML 문자열로 렌더링하기

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

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

// 라우트 핸들러 구문은 백엔드 프레임워크에 따라 다릅니다
app.use('/', (request, response) => {
  const html = renderToString(<App />);
  response.send(html);
});

이렇게 하면 React 컴포넌트의 초기 비대화형 HTML 출력이 생성됩니다. 클라이언트에서 서버에서 생성된 HTML을 hydrate하여 상호작용할 수 있도록 hydrateRoot 를 실행해야 합니다.

주의하세요!

renderToString은 스트리밍 또는 데이터 대기를 지원하지 않습니다. 대안을 참고하세요.

대안

서버에서 renderToString을 스트리밍 함수로 마이그레이션

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

가능하면 다음과 같은 완전한 기능을 갖춘 대안을 사용하는 것을 권장합니다:

서버 환경에서 스트림을 지원하지 않는 경우에도 renderToString을 계속 사용할 수 있습니다.

클라이언트 코드에서 renderToString 제거하기

클라이언트에서 일부 컴포넌트를 HTML로 변환하기 위해 renderToString을 사용하기도 합니다.

// 🚩 불필요: 클라이언트에서 renderToString 사용하기
import { renderToString } from 'react-dom/server';

const html = renderToString(<MyIcon />);
console.log(html); // 예를 들어, "<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); // 예를 들어, "<svg>...</svg>"

flushSync 호출은 innerHTML 속성을 읽기 전에 DOM을 업데이트하기 위해 필요합니다.

문제 해결

컴포넌트가 일시 중단되면 HTML에 항상 폴백을 포함합니다.

renderToString은 Suspense를 완벽하게 지원하지 않습니다.

일부 컴포넌트가 일시 중단되거나 (예를 들어, lazy와 함께 정의되거나 데이터를 가져올 때) renderToString은 콘텐츠가 해결될 때까지 기다리지 않습니다. renderToString는 그 위에 가장 가까운 <Suspense> 경계를 찾아 fallback 프로퍼티를 HTML에 렌더링합니다. 내용은 클라이언트 코드가 로드될 때까지 나타나지 않습니다.

이를 해결하기 위해 권장하는 스트리밍 솔루션 중 하나를 사용하세요. 사용자가 클라이언트 코드가 로드되기 전에 페이지가 점진적으로 채워지는 것을 볼 수 있도록 서버에서 해결할 때 컨텐츠를 청크로 스트리밍할 수 있습니다.

PreviousrenderToStaticNodeStream