Server-Side Rendering (SSR) | Vite

Dependency Pre-Bundling
Static Asset Handling
Building for Production
Deploying a Static Site
Env Variables and Modes
Server-Side Rendering (SSR)
Environment Instances
SSR specifically refers to front-end frameworks (for example React, Preact, Vue, and Svelte) that support running the same application in Node.js, pre-rendering it to HTML, and finally hydrating it on the client. If you are looking for integration with traditional server-side frameworks, check out the Backend Integration guide instead.
The following guide also assumes prior experience working with SSR in your framework of choice, and will only focus on Vite-specific integration details.
This is a low-level API meant for library and framework authors. If your goal is to create an application, make sure to check out the higher-level SSR plugins and tools at Awesome Vite SSR section first. That said, many applications are successfully built directly on top of Vite's native low-level API.
Currently, Vite is working on an improved SSR API with the Environment API. Check out the link for more details.
Vite provides built-in support for server-side rendering (SSR). create-vite-extra contains example SSR setups you can use as references for this guide:
You can also scaffold these projects locally by running create-vite and choose Others > create-vite-extra under the framework option.
A typical SSR application will have the following source file structure:
The index.html will need to reference entry-client.js and include a placeholder where the server-rendered markup should be injected:
You can use any placeholder you prefer instead of <!--ssr-outlet-->, as long as it can be precisely replaced.
If you need to perform conditional logic based on SSR vs. client, you can use
This is statically replaced during build so it will allow tree-shaking of unused branches.
When building an SSR app, you likely want to have full control over your main server and decouple Vite from the production environment. It is therefore recommended to use Vite in middleware mode. Here is an example with express:
Here vite is an instance of ViteDevServer. vite.middlewares is a Connect instance which can be used as a middleware in any connect-compatible Node.js framework.
SSR-only module updates
By default, updating a module that is only imported by the SSR environment does not reload the page in the browser. Framework integrations usually handle this for you. For a low-level custom SSR setup, you can add a plugin that reloads the browser when an SSR-only module changes:
Add ssrReload() to the plugins array passed to createViteServer in the example above. See the hotUpdate hook for details.
The next step is implementing the * handler to serve server-rendered HTML:
The dev script in package.json should also be changed to use the server script instead:
To ship an SSR project for production, we need to:
Our scripts in package.json will look like this:
Note the --ssr flag which indicates this is an SSR build. It should also specify the SSR entry.
Then, in server.js we need to add some production specific logic by checking process.env.NODE_ENV:
Instead of reading the root index.html, use the dist/client/index.html as the template, since it contains the correct asset links to the client build.
Instead of await vite.ssrLoadModule('/src/entry-server.js'), use import('./dist/server/entry-server.js') (this file is the result of the SSR build).
Move the creation and all usage of the vite dev server behind dev-only conditional branches, then add static file serving middlewares to serve files from dist/client.
Refer to the example projects for a working setup.
vite build supports the --ssrManifest flag which will generate .vite/ssr-manifest.json in build output directory:
The above script will now generate dist/client/.vite/ssr-manifest.json for the client build (Yes, the SSR manifest is generated from the client build because we want to map module IDs to client files). The manifest contains mappings of module IDs to their associated chunks and asset files.
To leverage the manifest, frameworks need to provide a way to collect the module IDs of the components that were used during a server render call.
@vitejs/plugin-vue supports this out of the box and automatically registers used component module IDs on to the associated Vue SSR context:
In the production branch of server.js we need to read and pass the manifest to the render function exported by src/entry-server.js. This would provide us with enough information to render preload directives for files used by async routes! See demo source for a full example. You can also use this information for 103 Early Hints.
If the routes and the data needed for certain routes are known ahead of time, we can pre-render these routes into static HTML using the same logic as production SSR. This can also be considered a form of Static-Site Generation (SSG). See demo pre-render script for working example.
Dependencies are "externalized" from Vite's SSR transform module system by default when running SSR. This speeds up both dev and build.