정적 프리렌더링

정적 프리렌더링은 애플리케이션의 정적 HTML 파일을 생성하는 과정입니다. 이를 사용하면 미리 렌더링된 HTML 파일을 즉석에서 생성할 필요 없이 사용자에게 제공하여 애플리케이션 성능을 개선하거나, 서버 측 렌더링을 지원하지 않는 플랫폼에 정적 사이트를 배포할 수 있습니다.

프리렌더링

TanStack Start는 애플리케이션을 정적 HTML 파일로 프리렌더링할 수 있으며, 이렇게 생성된 파일은 즉석에서 생성할 필요 없이 사용자에게 제공할 수 있습니다. 애플리케이션을 프리렌더링하려면 prerender 구성에 tanstackStart 옵션을 추가할 수 있습니다:

Vite

vite.config.ts

import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [
    tanstackStart({
      prerender: {
        // Switch to true to enable prerendering
        enabled: false,

        // Disable if you need pages to be at `/page.html` instead of `/page/index.html`
        autoSubfolderIndex: true,

        // If disabled, only the root path or the paths defined in the pages config will be prerendered
        autoStaticPathsDiscovery: true,

        // How many prerender jobs to run at once
        concurrency: 14,

        // Whether to extract links from the HTML and prerender them also
        crawlLinks: true,

        // Filter function takes the page object and returns whether it should prerender
        filter: ({ path }) => !path.startsWith('/do-not-render-me'),

        // Number of times to retry a failed prerender job
        retryCount: 2,

        // Delay between retries in milliseconds
        retryDelay: 1000,

        // Maximum number of redirects to follow during prerendering
        maxRedirects: 5,

        // Fail if an error occurs during prerendering
        failOnError: true,

        // Callback when page is successfully rendered
        onSuccess: ({ page }) => {
          console.log(`Rendered ${page.path}!`)
        },
      },
      // Optional configuration for specific pages
      // Note: When autoStaticPathsDiscovery is enabled (default), discovered static
      // routes will be merged with the pages specified below
      pages: [
        {
          path: '/my-page',
          prerender: { enabled: true, outputPath: '/my-page/index.html' },
        },
      ],
    }),
    viteReact(),
  ],
})

Rsbuild

rsbuild.config.ts

import { defineConfig } from '@rsbuild/core'
import { pluginReact } from '@rsbuild/plugin-react'
import { tanstackStart } from '@tanstack/react-start/plugin/rsbuild'

export default defineConfig({
  plugins: [
    pluginReact(),
    tanstackStart({
      prerender: {
        // Switch to true to enable prerendering
        enabled: false,

        // Disable if you need pages to be at `/page.html` instead of `/page/index.html`
        autoSubfolderIndex: true,

        // If disabled, only the root path or the paths defined in the pages config will be prerendered
        autoStaticPathsDiscovery: true,

        // How many prerender jobs to run at once
        concurrency: 14,

        // Whether to extract links from the HTML and prerender them also
        crawlLinks: true,

        // Filter function takes the page object and returns whether it should prerender
        filter: ({ path }) => !path.startsWith('/do-not-render-me'),

        // Number of times to retry a failed prerender job
        retryCount: 2,

        // Delay between retries in milliseconds
        retryDelay: 1000,

        // Maximum number of redirects to follow during prerendering
        maxRedirects: 5,

        // Fail if an error occurs during prerendering
        failOnError: true,

        // Callback when page is successfully rendered
        onSuccess: ({ page }) => {
          console.log(`Rendered ${page.path}!`)
        },
      },
      // Optional configuration for specific pages
      // Note: When autoStaticPathsDiscovery is enabled (default), discovered static
      // routes will be merged with the pages specified below
      pages: [
        {
          path: '/my-page',
          prerender: { enabled: true, outputPath: '/my-page/index.html' },
        },
      ],
    }),
  ],
})

자동 정적 라우트 검색

모든 정적 경로는 자동으로 검색되어 지정된 pages 구성과 원활하게 병합됩니다

다음과 같은 경우 라우트는 자동 검색에서 제외됩니다:

• 경로 매개변수가 있는 라우트(예: /users/$userId): 특정 매개변수 값이 필요하기 때문입니다
• 레이아웃 라우트(_ 접두사 사용): 독립 실행형 페이지를 렌더링하지 않기 때문입니다
• 컴포넌트가 없는 라우트(예: API 라우트)

참고: crawlLinks이 활성화된 경우 동적 라우트가 다른 페이지에서 링크되어 있다면 해당 라우트도 프리렌더링할 수 있습니다.

링크 크롤링

crawlLinks이 활성화되면(기본값: true) TanStack Start는 프리렌더링된 페이지에서 링크를 추출하고 링크된 페이지도 프리렌더링합니다.

예를 들어 /에 /posts 링크가 포함되어 있으면 /posts도 자동으로 프리렌더링됩니다.