Open History to see the last commit
1---
2id: static-prerendering
3title: Static Prerendering
4---
5β
6Static prerendering is the process of generating static HTML files for your application. This can be useful for either improving the performance of your application, as it allows you to serve pre-rendered HTML files to users without having to generate them on the fly or for deploying static sites to platforms that do not support server-side rendering.
7β
8## Prerendering
9β
10TanStack Start can prerender your application to static HTML files, which can then be served to users without having to generate them on the fly. To prerender your application, you can add the `prerender` option to your `tanstackStart` configuration:
11β
12<!-- ::start:tabs variant="bundler" -->
13β
14# Vite
15β
16```ts title="vite.config.ts"
17import { defineConfig } from 'vite'
18import { tanstackStart } from '@tanstack/react-start/plugin/vite'
19import viteReact from '@vitejs/plugin-react'
20β
21export default defineConfig({
22 plugins: [
23 tanstackStart({
24 prerender: {
25 // Switch to true to enable prerendering
26 enabled: false,
27β
28 // Disable if you need pages to be at `/page.html` instead of `/page/index.html`
29 autoSubfolderIndex: true,
30β
31 // If disabled, only the root path or the paths defined in the pages config will be prerendered
32 autoStaticPathsDiscovery: true,
33β
34 // How many prerender jobs to run at once
35 concurrency: 14,
36β
37 // Whether to extract links from the HTML and prerender them also
38 crawlLinks: true,
39β
40 // Filter function takes the page object and returns whether it should prerender
41 filter: ({ path }) => !path.startsWith('/do-not-render-me'),
42β
43 // Number of times to retry a failed prerender job
44 retryCount: 2,
45β
46 // Delay between retries in milliseconds
47 retryDelay: 1000,
48β
49 // Maximum number of redirects to follow during prerendering
50 maxRedirects: 5,
51β
52 // Fail if an error occurs during prerendering
53 failOnError: true,
54β
55 // Callback when page is successfully rendered
56 onSuccess: ({ page }) => {
57 console.log(`Rendered ${page.path}!`)
58 },
59 },
60 // Optional configuration for specific pages
61 // Note: When autoStaticPathsDiscovery is enabled (default), discovered static
62 // routes will be merged with the pages specified below
63 pages: [
64 {
65 path: '/my-page',
66 prerender: { enabled: true, outputPath: '/my-page/index.html' },
67 },
68 ],
69 }),
70 viteReact(),
71 ],
72})
73```
74β
75# Rsbuild
76β
77```ts title="rsbuild.config.ts"
78import { defineConfig } from '@rsbuild/core'
79import { pluginReact } from '@rsbuild/plugin-react'
80import { tanstackStart } from '@tanstack/react-start/plugin/rsbuild'
81β
82export default defineConfig({
83 plugins: [
84 pluginReact(),
85 tanstackStart({
86 prerender: {
87 // Switch to true to enable prerendering
88 enabled: false,
89β
90 // Disable if you need pages to be at `/page.html` instead of `/page/index.html`
91 autoSubfolderIndex: true,
92β
93 // If disabled, only the root path or the paths defined in the pages config will be prerendered
94 autoStaticPathsDiscovery: true,
95β
96 // How many prerender jobs to run at once
97 concurrency: 14,
98β
99 // Whether to extract links from the HTML and prerender them also
100 crawlLinks: true,
101β
102 // Filter function takes the page object and returns whether it should prerender
103 filter: ({ path }) => !path.startsWith('/do-not-render-me'),
104β
105 // Number of times to retry a failed prerender job
106 retryCount: 2,
107β
108 // Delay between retries in milliseconds
109 retryDelay: 1000,
110β
111 // Maximum number of redirects to follow during prerendering
112 maxRedirects: 5,
113β
114 // Fail if an error occurs during prerendering
115 failOnError: true,
116β
117 // Callback when page is successfully rendered
118 onSuccess: ({ page }) => {
119 console.log(`Rendered ${page.path}!`)
120 },
121 },
122 // Optional configuration for specific pages
123 // Note: When autoStaticPathsDiscovery is enabled (default), discovered static
124 // routes will be merged with the pages specified below
125 pages: [
126 {
127 path: '/my-page',
128 prerender: { enabled: true, outputPath: '/my-page/index.html' },
129 },
130 ],
131 }),
132 ],
133})
134```
135β
136<!-- ::end:tabs -->
137β
138## Automatic Static Route Discovery
139β
140All static paths will be automatically discovered and seamlessly merged with the specified `pages` config
141β
142Routes are excluded from automatic discovery in the following cases:
143β
144- Routes with path parameters (e.g., `/users/$userId`) since they require specific parameter values
145- Layout routes (prefixed with `_`) since they don't render standalone pages
146- Routes without components (e.g., API routes)
147β
148Note: Dynamic routes can still be prerendered if they are linked from other pages when `crawlLinks` is enabled.
149β
150## Crawling Links
151β
152When `crawlLinks` is enabled (default: `true`), TanStack Start will extract links from prerendered pages and prerender those linked pages as well.
153β
154For example, if `/` contains a link to `/posts`, then `/posts` will also be automatically prerendered.