Skip to content
Source
Sign inSign up
TanStack/router
Open History to see the last commit

static-prerendering.md

158 lines5.2 KB

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/solid-start/plugin/vite'
19import viteSolid from 'vite-plugin-solid'
20​
21export default defineConfig({
22 plugins: [
23 tanstackStart({
24 prerender: {
25 // Enable prerendering
26 enabled: true,
27​
28 // Enable if you need pages to be at `/page/index.html` instead of `/page.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 viteSolid({ ssr: true }),
71 ],
72})
73```
74​
75# Rsbuild
76​
77```ts title="rsbuild.config.ts"
78import { defineConfig } from '@rsbuild/core'
79import { pluginBabel } from '@rsbuild/plugin-babel'
80import { pluginSolid } from '@rsbuild/plugin-solid'
81import { tanstackStart } from '@tanstack/solid-start/plugin/rsbuild'
82​
83export default defineConfig({
84 plugins: [
85 pluginBabel({
86 include: /\.(?:jsx|tsx)$/,
87 }),
88 pluginSolid(),
89 tanstackStart({
90 prerender: {
91 // Enable prerendering
92 enabled: true,
93​
94 // Enable if you need pages to be at `/page/index.html` instead of `/page.html`
95 autoSubfolderIndex: true,
96​
97 // If disabled, only the root path or the paths defined in the pages config will be prerendered
98 autoStaticPathsDiscovery: true,
99​
100 // How many prerender jobs to run at once
101 concurrency: 14,
102​
103 // Whether to extract links from the HTML and prerender them also
104 crawlLinks: true,
105​
106 // Filter function takes the page object and returns whether it should prerender
107 filter: ({ path }) => !path.startsWith('/do-not-render-me'),
108​
109 // Number of times to retry a failed prerender job
110 retryCount: 2,
111​
112 // Delay between retries in milliseconds
113 retryDelay: 1000,
114​
115 // Maximum number of redirects to follow during prerendering
116 maxRedirects: 5,
117​
118 // Fail if an error occurs during prerendering
119 failOnError: true,
120​
121 // Callback when page is successfully rendered
122 onSuccess: ({ page }) => {
123 console.log(`Rendered ${page.path}!`)
124 },
125 },
126 // Optional configuration for specific pages
127 // Note: When autoStaticPathsDiscovery is enabled (default), discovered static
128 // routes will be merged with the pages specified below
129 pages: [
130 {
131 path: '/my-page',
132 prerender: { enabled: true, outputPath: '/my-page/index.html' },
133 },
134 ],
135 }),
136 ],
137})
138```
139​
140<!-- ::end:tabs -->
141​
142## Automatic Static Route Discovery
143​
144All static paths will be automatically discovered and seamlessly merged with the specified `pages` config
145​
146Routes are excluded from automatic discovery in the following cases:
147​
148- Routes with path parameters (e.g., `/users/$userId`) since they require specific parameter values
149- Layout routes (prefixed with `_`) since they don't render standalone pages
150- Routes without components (e.g., API routes)
151​
152Note: Dynamic routes can still be prerendered if they are linked from other pages when `crawlLinks` is enabled.
153​
154## Crawling Links
155​
156When `crawlLinks` is enabled (default: `true`), TanStack Start will extract links from prerendered pages and prerender those linked pages as well.
157​
158For example, if `/` contains a link to `/posts`, then `/posts` will also be automatically prerendered.