Skip to content

서버 사이드 렌더링 API

renderToString()

  • vue/server-renderer에서 내보냄

  • 타입

    ts
    function renderToString(
      input: App | VNode,
      context?: SSRContext
    ): Promise<string>
  • 예시

    js
    import { createSSRApp } from 'vue'
    import { renderToString } from 'vue/server-renderer'
    
    const app = createSSRApp({
      data: () => ({ msg: 'hello' }),
      template: `<div>{{ msg }}</div>`
    })
    
    ;(async () => {
      const html = await renderToString(app)
      console.log(html)
    })()

    SSR 컨텍스트

    선택적으로 컨텍스트 객체를 전달할 수 있으며, 렌더링 중에 추가 데이터를 기록하는 데 사용할 수 있습니다. 예를 들어 Teleport의 내용 접근에 사용할 수 있습니다:

    js
    const ctx = {}
    const html = await renderToString(app, ctx)
    
    console.log(ctx.teleports) // { '#teleported': 'teleported content' }

    이 페이지의 대부분의 다른 SSR API도 선택적으로 컨텍스트 객체를 받을 수 있습니다. 컨텍스트 객체는 컴포넌트 코드에서 useSSRContext 헬퍼를 통해 접근할 수 있습니다.

  • 관련 문서 가이드 - 서버 사이드 렌더링

renderToNodeStream()

입력을 Node.js Readable 스트림으로 렌더링합니다.

  • vue/server-renderer에서 내보냄

  • 타입

    ts
    function renderToNodeStream(
      input: App | VNode,
      context?: SSRContext
    ): Readable
  • 예시

    js
    // Node.js http 핸들러 내부
    renderToNodeStream(app).pipe(res)

    참고

    이 메서드는 Node.js 환경과 분리된 vue/server-renderer의 ESM 빌드에서는 지원되지 않습니다. 대신 pipeToNodeWritable을 사용하세요.

pipeToNodeWritable()

렌더링 후 기존 Node.js Writable 스트림 인스턴스에 파이프합니다.

  • vue/server-renderer에서 내보냄

  • 타입

    ts
    function pipeToNodeWritable(
      input: App | VNode,
      context: SSRContext = {},
      writable: Writable
    ): void
  • 예시

    js
    // Node.js http 핸들러 내부
    pipeToNodeWritable(app, {}, res)

renderToWebStream()

입력을 Web ReadableStream으로 렌더링합니다.

  • vue/server-renderer에서 내보냄

  • 타입

    ts
    function renderToWebStream(
      input: App | VNode,
      context?: SSRContext
    ): ReadableStream
  • 예시

    js
    // ReadableStream을 지원하는 환경에서
    return new Response(renderToWebStream(app))

    참고

    전역 범위에 ReadableStream 생성자가 노출되지 않은 환경에서는 pipeToWebWritable()을 대신 사용해야 합니다.

pipeToWebWritable()

렌더링 후 기존 Web WritableStream 인스턴스에 파이프합니다.

  • vue/server-renderer에서 내보냄

  • 타입

    ts
    function pipeToWebWritable(
      input: App | VNode,
      context: SSRContext = {},
      writable: WritableStream
    ): void
  • 예시

    일반적으로 TransformStream과 함께 사용됩니다:

    js
    // TransformStream은 CloudFlare workers와 같은 환경에서 사용 가능합니다.
    // Node.js에서는 TransformStream을 'stream/web'에서 명시적으로 import해야 합니다.
    const { readable, writable } = new TransformStream()
    pipeToWebWritable(app, {}, writable)
    
    return new Response(readable)

renderToSimpleStream()

간단한 읽기 인터페이스를 사용하여 스트리밍 모드로 입력을 렌더링합니다.

  • vue/server-renderer에서 내보냄

  • 타입

    ts
    function renderToSimpleStream(
      input: App | VNode,
      context: SSRContext,
      options: SimpleReadable
    ): SimpleReadable
    
    interface SimpleReadable {
      push(content: string | null): void
      destroy(err: any): void
    }
  • 예시

    js
    let res = ''
    
    renderToSimpleStream(
      app,
      {},
      {
        push(chunk) {
          if (chunk === null) {
            // 완료
            console(`렌더링 완료: ${res}`)
          } else {
            res += chunk
          }
        },
        destroy(err) {
          // 에러 발생
        }
      }
    )

useSSRContext()

renderToString() 또는 기타 서버 렌더 API에 전달된 컨텍스트 객체를 가져오는 런타임 API입니다.

  • 타입

    ts
    function useSSRContext<T = Record<string, any>>(): T | undefined
  • 예시

    가져온 컨텍스트는 최종 HTML 렌더링에 필요한 정보(예: head 메타데이터)를 첨부하는 데 사용할 수 있습니다.

    vue
    <script setup>
    import { useSSRContext } from 'vue'
    
    // 반드시 SSR 중에만 호출해야 합니다.
    // https://vitejs.dev/guide/ssr.html#conditional-logic
    if (import.meta.env.SSR) {
      const ctx = useSSRContext()
      // ...컨텍스트에 속성 추가
    }
    </script>

data-allow-mismatch

하이드레이션 불일치 경고를 억제하는 데 사용할 수 있는 특수 속성입니다.

  • 예시

    html
    <div data-allow-mismatch="text">{{ data.toLocaleString() }}</div>

    값은 허용되는 불일치 유형을 특정 타입으로 제한할 수 있습니다. 허용되는 값은 다음과 같습니다:

    • text
    • children (직접 자식에 대한 불일치만 허용)
    • class
    • style
    • attribute

    값을 제공하지 않으면 모든 유형의 불일치가 허용됩니다.

서버 사이드 렌더링 API has loaded