정적 사전 렌더링

정적 사전 렌더링은 애플리케이션의 정적 HTML 파일을 생성하는 과정입니다. 즉석에서 파일을 생성하지 않고 사전 렌더링된 HTML 파일을 사용자에게 제공할 수 있으므로 애플리케이션 성능을 개선하거나, 서버 측 렌더링을 지원하지 않는 플랫폼에 정적 사이트를 배포할 때 유용합니다.

사전 렌더링

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

Vite

vite.config.ts

import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/solid-start/plugin/vite'
import viteSolid from 'vite-plugin-solid'

export default defineConfig({
  plugins: [
    tanstackStart({
      prerender: {
        // Enable prerendering
        enabled: true,

        // Enable if you need pages to be at `/page/index.html` instead of `/page.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' },
        },
      ],
    }),
    viteSolid({ ssr: true }),
  ],
})

Rsbuild

rsbuild.config.ts

import { defineConfig } from '@rsbuild/core'
import { pluginBabel } from '@rsbuild/plugin-babel'
import { pluginSolid } from '@rsbuild/plugin-solid'
import { tanstackStart } from '@tanstack/solid-start/plugin/rsbuild'

export default defineConfig({
  plugins: [
    pluginBabel({
      include: /\.(?:jsx|tsx)$/,
    }),
    pluginSolid(),
    tanstackStart({
      prerender: {
        // Enable prerendering
        enabled: true,

        // Enable if you need pages to be at `/page/index.html` instead of `/page.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도 자동으로 사전 렌더링됩니다.