6.9 KiB
Backend Integration
:::tip Note If you want to serve the HTML using a traditional backend (e.g. Rails, Laravel) but use Vite for serving assets, check for existing integrations listed in Awesome Vite.
If you need a custom integration, you can follow the steps in this guide to configure it manually :::
-
In your Vite config, configure the entry and enable build manifest:
import { defineConfig } from 'vite' // ---cut--- export default defineConfig({ build: { // generate .vite/manifest.json in outDir manifest: true, rollupOptions: { // overwrite default .html entry input: '/path/to/main.js', }, }, })
If you haven't disabled the module preload polyfill, you also need to import the polyfill in your entry
// add the beginning of your app entry import 'vite/modulepreload-polyfill'
-
For development, inject the following in your server's HTML template (substitute
http://localhost:5173
with the local URL Vite is running at):<!-- if development --> <script type="module" src="http://localhost:5173/@vite/client"></script> <script type="module" src="http://localhost:5173/main.js"></script>
In order to properly serve assets, you have two options:
- Make sure the server is configured to proxy static assets requests to the Vite server
- Set
server.origin
so that generated asset URLs will be resolved using the back-end server URL instead of a relative path
This is needed for assets such as images to load properly.
Note if you are using React with
@vitejs/plugin-react
, you'll also need to add this before the above scripts, since the plugin is not able to modify the HTML you are serving (substitutehttp://localhost:5173
with the local URL Vite is running at):<script type="module"> import RefreshRuntime from 'http://localhost:5173/@react-refresh' RefreshRuntime.injectIntoGlobalHook(window) window.$RefreshReg$ = () => {} window.$RefreshSig$ = () => (type) => type window.__vite_plugin_react_preamble_installed__ = true </script>
-
For production: after running
vite build
, a.vite/manifest.json
file will be generated alongside other asset files. An example manifest file looks like this:{ "_shared-B7PI925R.js": { "file": "assets/shared-B7PI925R.js", "name": "shared", "css": ["assets/shared-ChJ_j-JJ.css"] }, "_shared-ChJ_j-JJ.css": { "file": "assets/shared-ChJ_j-JJ.css", "src": "_shared-ChJ_j-JJ.css" }, "baz.js": { "file": "assets/baz-B2H3sXNv.js", "name": "baz", "src": "baz.js", "isDynamicEntry": true }, "views/bar.js": { "file": "assets/bar-gkvgaI9m.js", "name": "bar", "src": "views/bar.js", "isEntry": true, "imports": ["_shared-B7PI925R.js"], "dynamicImports": ["baz.js"] }, "views/foo.js": { "file": "assets/foo-BRBmoGS9.js", "name": "foo", "src": "views/foo.js", "isEntry": true, "imports": ["_shared-B7PI925R.js"], "css": ["assets/foo-5UjPuW-k.css"] } }
- The manifest has a
Record<name, chunk>
structure - For entry or dynamic entry chunks, the key is the relative src path from project root.
- For non entry chunks, the key is the base name of the generated file prefixed with
_
. - Chunks will contain information on its static and dynamic imports (both are keys that map to the corresponding chunk in the manifest), and also its corresponding CSS and asset files (if any).
- The manifest has a
-
You can use this file to render links or preload directives with hashed filenames.
Here is an example HTML template to render the proper links. The syntax here is for explanation only, substitute with your server templating language. The
importedChunks
function is for illustration and isn't provided by Vite.<!-- if production --> <!-- for cssFile of manifest[name].css --> <link rel="stylesheet" href="/{{ cssFile }}" /> <!-- for chunk of importedChunks(manifest, name) --> <!-- for cssFile of chunk.css --> <link rel="stylesheet" href="/{{ cssFile }}" /> <script type="module" src="/{{ manifest[name].file }}"></script> <!-- for chunk of importedChunks(manifest, name) --> <link rel="modulepreload" href="/{{ chunk.file }}" />
Specifically, a backend generating HTML should include the following tags given a manifest file and an entry point:
- A
<link rel="stylesheet">
tag for each file in the entry point chunk'scss
list - Recursively follow all chunks in the entry point's
imports
list and include a<link rel="stylesheet">
tag for each CSS file of each imported chunk. - A tag for the
file
key of the entry point chunk (<script type="module">
for JavaScript, or<link rel="stylesheet">
for CSS) - Optionally,
<link rel="modulepreload">
tag for thefile
of each imported JavaScript chunk, again recursively following the imports starting from the entry point chunk.
Following the above example manifest, for the entry point
views/foo.js
the following tags should be included in production:<link rel="stylesheet" href="assets/foo-5UjPuW-k.css" /> <link rel="stylesheet" href="assets/shared-ChJ_j-JJ.css" /> <script type="module" src="assets/foo-BRBmoGS9.js"></script> <!-- optional --> <link rel="modulepreload" href="assets/shared-B7PI925R.js" />
While the following should be included for the entry point
views/bar.js
:<link rel="stylesheet" href="assets/shared-ChJ_j-JJ.css" /> <script type="module" src="assets/bar-gkvgaI9m.js"></script> <!-- optional --> <link rel="modulepreload" href="assets/shared-B7PI925R.js" />
::: details Pseudo implementation of
importedChunks
An example pseudo implementation ofimportedChunks
in TypeScript (This will need to be adapted for your programming language and templating language):import type { Manifest, ManifestChunk } from 'vite' export default function importedChunks( manifest: Manifest, name: string, ): ManifestChunk[] { const seen = new Set<string>() function getImportedChunks(chunk: ManifestChunk): ManifestChunk[] { const chunks: ManifestChunk[] = [] for (const file of chunk.imports ?? []) { const importee = manifest[file] if (seen.has(file)) { continue } seen.add(file) chunks.push(...getImportedChunks(importee)) chunks.push(importee) } return chunks } return getImportedChunks(manifest[name]) }
:::
- A