2021-01-01 16:40:16 -05:00
# Backend Integration
2021-08-06 10:46:34 +02:00
:::tip Note
2021-03-15 11:31:50 -03:00
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 ](https://github.com/vitejs/awesome-vite#integrations-with-backends ).
2026-01-05 20:31:39 -05:00
If you need a custom integration, you can follow the steps in this guide to configure it manually.
2021-08-06 10:46:34 +02:00
:::
2021-01-01 16:40:16 -05:00
2021-01-05 00:37:22 -05:00
1. In your Vite config, configure the entry and enable build manifest:
2024-09-19 12:53:21 +08:00
```js twoslash [vite.config.js]
2024-03-15 17:24:38 +09:00
import { defineConfig } from 'vite'
// ---cut---
2021-07-27 17:00:51 +02:00
export default defineConfig({
2025-01-15 17:04:31 +09:00
server: {
cors: {
// the origin you will be accessing via browser
origin: 'http://my-backend.example.com',
},
},
2021-01-05 00:37:22 -05:00
build: {
2023-09-18 17:40:49 +09:00
// generate .vite/manifest.json in outDir
2021-01-05 00:37:22 -05:00
manifest: true,
rollupOptions: {
// overwrite default .html entry
input: '/path/to/main.js',
},
},
2021-07-27 17:00:51 +02:00
})
2021-01-05 00:37:22 -05:00
` ``
2021-01-01 16:40:16 -05:00
2022-06-19 18:12:59 +09:00
If you haven't disabled the [module preload polyfill](/config/build-options.md#build-polyfillmodulepreload), you also need to import the polyfill in your entry
2021-07-29 07:17:13 +02:00
` ``js
// add the beginning of your app entry
import 'vite/modulepreload-polyfill'
` ``
2022-05-12 16:47:04 +02:00
2. For development, inject the following in your server's HTML template (substitute ` http://localhost:5173` with the local URL Vite is running at):
2021-01-01 16:40:16 -05:00
2021-01-05 00:37:22 -05:00
` ``html
<!-- if development -->
2022-07-21 02:54:18 +08:00
<script type="module" src="http://localhost:5173/@vite/client"></script>
2022-05-12 16:47:04 +02:00
<script type="module" src="http://localhost:5173/main.js"></script>
2021-01-05 00:37:22 -05:00
` ``
2021-01-01 16:40:16 -05:00
2022-05-10 12:45:55 -04:00
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
2022-06-19 18:12:59 +09:00
- Set [` server.origin`](/config/server-options.md#server-origin) so that generated asset URLs will be resolved using the back-end server URL instead of a relative path
2022-05-10 12:45:55 -04:00
This is needed for assets such as images to load properly.
2021-01-01 16:40:16 -05:00
2023-08-23 01:56:10 -05:00
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 (substitute ` http://localhost:5173` with the local URL Vite is running at):
2021-02-12 11:21:22 -05:00
` ``html
<script type="module">
2022-05-12 16:47:04 +02:00
import RefreshRuntime from 'http://localhost:5173/@react-refresh'
2021-03-31 22:06:16 +02:00
RefreshRuntime.injectIntoGlobalHook(window)
2021-02-18 15:31:48 -05:00
window.$RefreshReg$ = () => {}
2021-02-12 11:21:22 -05:00
window.$RefreshSig$ = () => (type) => type
window.__vite_plugin_react_preamble_installed__ = true
</script>
` ``
2025-08-18 08:20:17 +06:00
3. 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:
2021-01-26 22:03:28 -05:00
2025-11-20 16:44:03 +09:00
` ``json [.vite/manifest.json] style:max-height:400px
2021-01-26 22:03:28 -05:00
{
2024-05-07 19:16:36 +09:00
"_shared-B7PI925R.js": {
"file": "assets/shared-B7PI925R.js",
"name": "shared",
"css": ["assets/shared-ChJ_j-JJ.css"]
},
2024-10-25 20:16:30 +09:00
"_shared-ChJ_j-JJ.css": {
"file": "assets/shared-ChJ_j-JJ.css",
"src": "_shared-ChJ_j-JJ.css"
},
2025-08-05 17:44:10 +09:00
"logo.svg": {
"file": "assets/logo-BuPIv-2h.svg",
"src": "logo.svg"
},
2024-05-07 19:16:36 +09:00
"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",
2021-01-26 22:03:28 -05:00
"isEntry": true,
2024-05-07 19:16:36 +09:00
"imports": ["_shared-B7PI925R.js"],
"dynamicImports": ["baz.js"]
2021-01-26 22:03:28 -05:00
},
"views/foo.js": {
2024-05-07 19:16:36 +09:00
"file": "assets/foo-BRBmoGS9.js",
"name": "foo",
2021-01-26 22:03:28 -05:00
"src": "views/foo.js",
2024-05-07 19:16:36 +09:00
"isEntry": true,
"imports": ["_shared-B7PI925R.js"],
"css": ["assets/foo-5UjPuW-k.css"]
2021-01-26 22:03:28 -05:00
}
}
` ``
2025-06-30 12:25:03 +09:00
2026-03-04 21:09:26 +09:00
The manifest maps source files to their build outputs and dependencies:
` ``dot
digraph manifest {
rankdir=TB
node [shape=box style="rounded,filled" fontname="Arial" fontsize=10 margin="0.2,0.1" fontcolor="${#3c3c43|#ffffff}" color="${#c2c2c4|#3c3f44}"]
edge [color="${#67676c|#98989f}" fontname="Arial" fontsize=9 fontcolor="${#67676c|#98989f}"]
bgcolor="transparent"
foo [label="views/foo.js\n(entry)" fillcolor="${#e9eaff|#222541}"]
bar [label="views/bar.js\n(entry)" fillcolor="${#e9eaff|#222541}"]
shared [label="_shared-B7PI925R.js\n(common chunk)" fillcolor="${#f2ecfc|#2c273e}"]
baz [label="baz.js\n(dynamic import)" fillcolor="${#fcf4dc|#38301a}"]
foocss [label="foo.css" shape=ellipse fillcolor="${#fde4e8|#3a1d27}"]
sharedcss [label="shared.css" shape=ellipse fillcolor="${#fde4e8|#3a1d27}"]
logo [label="logo.svg\n(asset)" shape=ellipse fillcolor="${#def5ed|#15312d}"]
foo -> shared [label="imports"]
bar -> shared [label="imports"]
bar -> baz [label="dynamicImports" style=dashed]
foo -> foocss [label="css"]
shared -> sharedcss [label="css"]
}
` ``
2025-08-05 17:44:10 +09:00
The manifest has a ` Record<name, chunk>` structure where each chunk follows the ` ManifestChunk` interface:
2025-11-20 16:44:03 +09:00
` ``ts style:max-height:400px
2025-08-05 17:44:10 +09:00
interface ManifestChunk {
2025-11-20 16:44:03 +09:00
/**
* The input file name of this chunk / asset if known
*/
2025-08-05 17:44:10 +09:00
src?: string
2025-11-20 16:44:03 +09:00
/**
* The output file name of this chunk / asset
*/
2025-08-05 17:44:10 +09:00
file: string
2025-11-20 16:44:03 +09:00
/**
* The list of CSS files imported by this chunk
*/
2025-08-05 17:44:10 +09:00
css?: string[]
2025-11-20 16:44:03 +09:00
/**
* The list of asset files imported by this chunk, excluding CSS files
*/
2025-08-05 17:44:10 +09:00
assets?: string[]
2025-11-20 16:44:03 +09:00
/**
* Whether this chunk or asset is an entry point
*/
2025-08-05 17:44:10 +09:00
isEntry?: boolean
2025-11-20 16:44:03 +09:00
/**
* The name of this chunk / asset if known
*/
2025-08-05 17:44:10 +09:00
name?: string
2025-11-20 16:44:03 +09:00
/**
* Whether this chunk is a dynamic entry point
*
* This field is only present in JS chunks.
*/
2025-08-05 17:44:10 +09:00
isDynamicEntry?: boolean
2025-11-20 16:44:03 +09:00
/**
* The list of statically imported chunks by this chunk
*
* The values are the keys of the manifest. This field is only present in JS chunks.
*/
2025-08-05 17:44:10 +09:00
imports?: string[]
2025-11-20 16:44:03 +09:00
/**
* The list of dynamically imported chunks by this chunk
*
* The values are the keys of the manifest. This field is only present in JS chunks.
*/
2025-08-05 17:44:10 +09:00
dynamicImports?: string[]
}
` ``
Each entry in the manifest represents one of the following:
- **Entry chunks**: Generated from files specified in [` build.rollupOptions.input`](https://rollupjs.org/configuration-options/#input). These chunks have ` isEntry: true` and their key is the relative src path from project root.
- **Dynamic entry chunks**: Generated from dynamic imports. These chunks have ` isDynamicEntry: true` and their key is the relative src path from project root.
- **Non-entry chunks**: Their key is the base name of the generated file prefixed with ` _`.
- **Asset chunks**: Generated from imported assets like images, fonts. Their key is the relative src path from project root.
- **CSS files**: When [` build.cssCodeSplit`](/config/build-options.md#build-csscodesplit) is ` false`, a single CSS file is generated with the key ` style.css`. When ` build.cssCodeSplit` is not ` false`, the key is generated similar to JS chunks (i.e. entry chunks will not have ` _` prefix and non-entry chunks will have ` _` prefix).
2026-02-02 11:38:24 +01:00
JS chunks (chunks other than assets or CSS) will contain information on their static and dynamic imports (both are keys that map to the corresponding chunk in the manifest). Chunks also list their corresponding CSS and asset files if they have any.
2021-01-26 22:03:28 -05:00
2024-03-14 07:09:07 -04:00
4. 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.
2021-01-01 16:40:16 -05:00
2021-01-05 00:37:22 -05:00
` ``html
<!-- if production -->
2024-03-14 07:09:07 -04:00
<!-- for cssFile of manifest[name].css -->
<link rel="stylesheet" href="/{{ cssFile }}" />
2024-03-14 20:48:28 +09:00
<!-- for chunk of importedChunks(manifest, name) -->
2024-03-14 07:09:07 -04:00
<!-- for cssFile of chunk.css -->
<link rel="stylesheet" href="/{{ cssFile }}" />
<script type="module" src="/{{ manifest[name].file }}"></script>
<!-- for chunk of importedChunks(manifest, name) -->
2024-03-27 06:03:49 +01:00
<link rel="modulepreload" href="/{{ chunk.file }}" />
2024-03-14 07:09:07 -04:00
` ``
Specifically, a backend generating HTML should include the following tags given a manifest
2025-08-05 17:44:10 +09:00
file and an entry point. Note that following this order is recommended for optimal performance:
1. A ` <link rel="stylesheet">` tag for each file in the entry point chunk's ` css` list (if it exists)
2. 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's ` css` list (if it exists).
3. A tag for the ` file` key of the entry point chunk. This can be ` <script type="module">` for JavaScript, ` <link rel="stylesheet">` for CSS.
4. Optionally, ` <link rel="modulepreload">` tag for the ` file` of each imported JavaScript
chunk, again recursively following the imports starting from the entry point chunk.
2024-03-14 07:09:07 -04:00
2024-05-07 19:16:36 +09:00
Following the above example manifest, for the entry point ` views/foo.js` the following tags should be included in production:
2024-03-14 07:09:07 -04:00
` ``html
2024-05-07 19:16:36 +09:00
<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>
2024-03-14 07:09:07 -04:00
<!-- optional -->
2024-05-07 19:16:36 +09:00
<link rel="modulepreload" href="assets/shared-B7PI925R.js" />
2024-03-14 07:09:07 -04:00
` ``
2024-05-07 19:16:36 +09:00
While the following should be included for the entry point ` views/bar.js`:
2024-03-14 07:09:07 -04:00
` ``html
2024-05-07 19:16:36 +09:00
<link rel="stylesheet" href="assets/shared-ChJ_j-JJ.css" />
<script type="module" src="assets/bar-gkvgaI9m.js"></script>
2024-03-14 07:09:07 -04:00
<!-- optional -->
2024-05-07 19:16:36 +09:00
<link rel="modulepreload" href="assets/shared-B7PI925R.js" />
2021-01-05 00:37:22 -05:00
` ``
2024-10-18 16:38:27 +03:00
::: details Pseudo implementation of ` importedChunks`
An example pseudo implementation of ` importedChunks` in TypeScript (This will
need to be adapted for your programming language and templating language):
` ``ts
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])
}
` ``
:::
