HomeAboutMeBlogGuest
© 2025 Sejin Cha. All rights reserved.
Built with Next.js, deployed on Vercel
🐣
프론트엔드 데브코스 4기 교육생/
😃
이동근팀/
react@18.2.0
react@18.2.0/
renderToPipeableStream

renderToPipeableStream

 
react-dom/server API를 사용하면 서버에서 React 컴포넌트를 HTML로 렌더링할 수 있습니다. 이러한 API는 앱의 최상위 레벨에 있는 서버에서 초기 HTML을 생성하는 데에만 사용됩니다. 프레임워크가 대신 호출할 수도 있습니다. 대부분의 컴포넌트는 이를 가져오거나 사용할 필요가 없습니다.
 
“Node.js 스트림이 있는 환경에서만 사용할 수 있습니다”
 
renderToPipeableStream은 React 트리를 파이프 가능한 Node.js 스트림으로 렌더링합니다.
 

노트

이 API는 Node.js 전용입니다. Deno와 같은 웹 스트림을 사용하는 환경 및 최신 엣지 런타임에서는 대신 renderToReadableStream을 사용해야 합니다.
 

참조

renderToPipeableStream(reactNode, options?)

renderToPipeableStream를 호출하면 React 트리를 HTML로 Node.js 스트림에 렌더링합니다.
클라이언트에서 hydrateRoot를 호출하면 서버에서 생성된 HTML을 상호작용이 가능하도록 만듭니다.
 

매개변수

  • reactNode: HTML로 렌더링하려는 React 노드. 예를 들어, <App />과 같은 JSX 엘리먼트입니다. 전체 문서를 나타낼 것이므로, App 컴포넌트는 <html> 태그를 렌더링해야 합니다.
 
  • 선택적 options: 스트리밍 옵션이 있는 객체.
    • bootstrapScriptContent
        • 지정하면 이 문자열이 인라인 <script> 태그에 배치됩니다.
    • bootstrapScripts
        • 페이지에 표시할<script> 태그의 문자열 URL 배열. hydrateRoot를 호출하는 <script>를 포함하고자 할 때 사용하세요. 클라이언트에서 React를 아예 실행하지 않으려면 생략하세요.
    • bootstrapModules
        • bootstrapScripts와 비슷하지만, 대신 <script type="module">을 출력합니다.
    • identifierPrefix
        • React가 useId에 의해 생성된 ID에 사용하는 문자열 접두사. 같은 페이지에서 여러 루트를 사용할 때 충돌을 피하는 데 유용합니다. hydrateRoot에 전달된 접두사와 동일해야 합니다.
    • namespaceURI
        • 스트림의 루트 namespace URI가 포함된 문자열. 기본값은 일반 HTML입니다. SVG의 경우 'http://www.w3.org/2000/svg'를, MathML의 경우 'http://www.w3.org/1998/Math/MathML'을 전달합니다.
    • nonce
        • script-src 콘텐츠 보안 정책에 대한 스크립트를 허용하는 nonce 문자열.
    • onAllReady
        • shell과 모든 추가적인 content를 포함한 렌더링이 전부 완료되면 실행되는 콜백. 크롤러 및 정적 생성을 위해 onShellReady 대신 이 옵션을 사용할 수 있습니다. 여기서 스트리밍을 시작하면 점진적 로딩이 발생하지 않습니다. 스트림에는 최종 HTML이 포함됩니다.
    • onError
        • 복구 가능 혹은 불가능 여부에 관계 없이 서버 오류가 발생할 때마다 실행되는 콜백. 기본적으로 console.error만 호출합니다. 이 함수를 재정의하여 로그 충돌 보고서를 기록하도록 한 경우에도 여전히 console.error를 호출해야 합니다. 셸이 출력되기 전에 상태 코드를 조정하는 데 사용할 수도 있습니다.
    • onShellReady
        • 초기 셸이 렌더링된 직후에 실행되는 콜백. 여기에서 상태 코드를 설정하고 pipe를 호출하면 스트리밍이 시작됩니다. React는 HTML 로딩 폴백을 콘텐츠로 대체하는 인라인 <script> 태그와 함께 셸 뒤에 추가 컨텐츠를 스트리밍합니다.
    • onShellError
        • 초기 셸을 렌더링하는 중에 오류가 발생하면 호출되는 콜백. 인자로 에러를 받습니다. 이 경우 아직은 스트림에서 바이트가 전송되지 않았고, onShellReady나 onAllReady도 호출되지 않은 상태이므로, 폴백 HTML 셸을 출력할 수 있습니다.
    • progressiveChunkSize
        • 청크의 바이트 수. (기본 휴리스틱에 대해 자세히 알아보세요.)
         

반환값

renderToPipeableStream는 두 개의 메서드가 있는 객체를 반환합니다:
  • pipe는 제공된 writable한 Node.js 스트림 안으로 HTML을 출력합니다. 스트리밍을 활성화하려면 onShellReady에서, 크롤러 및 정적 생성시에는 onAllReady에서 pipe를 호출하세요.
  • abort를 사용하면 서버 렌더링을 중단하고 나머지는 클라이언트에서 렌더링하도록 해줍니다.
 
 

사용법

1. StreamReact 트리를 HTML로 Node.js 스트림에 렌더링하기

 
renderToPipeableStream을 호출하여 React 트리를 HTML로 Node.js Stream에 렌더링합니다:
 
루트 컴포넌트와 함께 부트스트랩 <script> 경로 목록을 제공해야 합니다. 루트 컴포넌트는 루트 <html> 태그를 포함한 전체 문서를 반환해야 합니다.
 
예를들어, 아래와 같습니다.
 
React는 결과 HTML 스트림에 doctype과 부트스트랩 <script> 태그를 삽입할 것입니다.
 
클라이언트에서 부트스트랩 스크립트는 hydrateRoot를 호출하여 전체 document를 hydrate해야 합니다:
이렇게 하면 서버에서 생성된 HTML에 이벤트 리스너가 첨부되어 상호작용이 가능해 집니다.
 

심화

최종 에셋 URL(예: JavaScript 및 CSS 파일)은 빌드 후에 해시 처리되는 경우가 많습니다. 예를 들어, styles.css 대신 styles.123456.css로 끝날 수 있습니다. 정적 에셋 파일명을 해시하면 동일한 에셋의 모든 개별 빌드에 다른 파일명이 지정됩니다. 이는 정적 asset에 대한 장기 캐싱을 안전하게 활성화할 수 있기 때문에 유용합니다. 특정 이름을 가진 파일은 콘텐츠를 변경하지 않습니다.
 
하지만 빌드가 끝날 때까지 에셋 URL을 모르는 경우 소스 코드에 넣을 방법이 없습니다. 예를 들어, 앞서와 같이 JSX에 "/styles.css"를 하드코딩하면 작동하지 않을 것입니다.
 
소스 코드에 포함되지 않으면서 빌드 시점에 에셋을 로드하기 위해, 루트 컴포넌트가 prop으로 전달된 맵에서 실제 파일명을 읽는 방식을 생각해 봅시다:
 
서버에서 <App assetMap={assetMap} />을 렌더링하고 에셋 URL과 함께 assetMap을 전달합니다:
 
이제 서버가 <App assetMap={assetMap} /> 를 렌더링하고 있으므로, 클라이언트에서도 assetMap 을 사용하여 렌더링해야 하이드레이션 오류를 방지할 수 있습니다. 다음과 같이 assetMap을 직렬화하여 클라이언트에 전달할 수 있습니다:
 
위의 예시에서 bootstrapScriptContent 옵션은 클라이언트에서 전역 window.assetMap 변수를 설정하는 별도의 인라인 <script> 태그를 추가합니다. 이렇게 하면 클라이언트 코드가 동일한 assetMap을 읽을 수 있습니다:
클라이언트와 서버 모두 동일한 AssetMap 프로퍼티로 App을 렌더링하므로 하이드레이션 오류가 발생하지 않습니다.
const { pipe, abort } = renderToPipeableStream(reactNode, options?)
import {renderToPipeableStream} from 'react-dom/server';

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

app.use('/', (request, response) => {
  const {pipe} = renderToPipeableStream(<App />, {
    bootstrapScripts: ['/main.js'],
    onShellReady() {
      response.setHeader('content-type', 'text/html');
      pipe(response);
    },
  });
});
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>
  );
}
<!DOCTYPE html>
<html>
  <!-- ... HTML from your components ... -->
</html>
<script src="/main.js" async=""></script>
import {hydrateRoot} from 'react-dom/client';
import App from './App.js';

hydrateRoot(document, <App />);
export default function App({assetMap}) {
  return (
    <html>
      <head>
        ...
        <link rel="stylesheet" href={assetMap['styles.css']}></link>
        ...
      </head>
      ...
    </html>
  );
}
// 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);
    },
  });
});
// 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);
    },
  });
});
import {hydrateRoot} from 'react-dom/client';
import App from './App.js';

hydrateRoot(document, <App assetMap={window.assetMap} />);