Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 38 ยท Frameworks and SSR

Vite Backend Integration and the Manifest

Use Vite with a traditional backend: the dev server and proxy, build.manifest, reading the manifest to emit hashed tags, CORS, multi-page entries and server-rendered HTML.

Not every app is a single-page application. Many sites are rendered by a backend such as Laravel, Rails, Django or an Express server, and only need Vite for their JavaScript and CSS. Vite supports this directly: in dev the backend points script tags at the Vite dev server, and in production it reads a manifest that maps source files to hashed output files.

This lesson explains both modes, the manifest format, a proxy setup for APIs, and multi-entry builds. The config and templates are real and read-only. The stand-ins run the manifest logic a backend integration performs.

The two modes

flowchart TD
  A["Backend template"] --> B{"Dev or production?"}
  B -->|Dev| C["script tag points to the Vite dev server (localhost:5173)"]
  B -->|Production| D["Read manifest.json, emit hashed file URLs"]

The backend template decides what to print. Integration packages do this for you in most frameworks.

Configuration

JavaScript
// vite.config.js (real Vite, read-only)
import { defineConfig } from 'vite';

export default defineConfig({
  base: '/build/',                 // URL prefix where built files are served
  build: {
    manifest: true,                // write .vite/manifest.json
    outDir: 'public/build',
    rollupOptions: {
      input: {
        app: 'resources/js/app.js',      // JS entry
        admin: 'resources/js/admin.js',  // a second entry
      },
    },
  },
  server: {
    origin: 'http://localhost:5173',     // so asset URLs point at the dev server
    cors: true,                          // allow the backend's origin to load modules
  },
});
  • There is no index.html entry: you list entries yourself in rollupOptions.input.
  • build.manifest: true writes manifest.json into the output folder's .vite directory (older versions wrote it at the root).
  • server.origin makes generated absolute URLs (for example for images referenced from CSS) point at the Vite server rather than the backend.
  • cors: true is required when the page is served from a different origin than the dev server, because module scripts are subject to CORS.

Development mode in the template

The backend prints two tags in dev: the Vite client for HMR and your entry.

HTML
<!-- dev (real HTML, read-only) -->
<script type="module" src="http://localhost:5173/@vite/client"></script>
<script type="module" src="http://localhost:5173/resources/js/app.js"></script>

If a framework (React Fast Refresh) needs a preamble, its plugin documents an extra inline script to add before the entry.

Production mode: the manifest

After vite build, the manifest looks like this:

JSON
{
  "resources/js/app.js": {
    "file": "assets/app-4ed993c7.js",
    "name": "app",
    "src": "resources/js/app.js",
    "isEntry": true,
    "imports": ["_shared-83069a53.js"],
    "css": ["assets/app-0b1f2e3a.css"]
  },
  "_shared-83069a53.js": {
    "file": "assets/shared-83069a53.js",
    "name": "shared"
  }
}

For an entry the backend must print:

  1. the stylesheet links from css,
  2. <link rel="modulepreload"> for each file in imports (recursively),
  3. the <script type="module"> for file.
JS Stand-in: building tags from a manifest

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Because the manifest changes on every build, the backend must read it at request time or on deploy, never cache an old copy forever. Laravel's @vite directive, Rails' vite_rails and Django's django-vite all implement exactly this logic.

Proxying the API in development

When the frontend runs on localhost:5173 and the API on another port, the browser treats API calls as cross-origin. A dev proxy forwards them, so frontend code can call /api/... with no CORS setup:

JavaScript
// real Vite
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:8000',
        changeOrigin: true,
        // rewrite: (path) => path.replace(/^\/api/, ''),
      },
      '/ws': { target: 'ws://localhost:8000', ws: true },
    },
  },
});
JS Stand-in: matching proxy rules

Press Run (or Ctrl + Enter) to see the console output here.

No output.

A proxy exists only in the dev server. In production your real web server (nginx, a CDN rule, or the backend itself) must route /api correctly.

Multi-page apps

Without a backend, Vite can also build several HTML pages: list each in rollupOptions.input:

JavaScript
// real Vite
import { resolve } from 'node:path';
build: {
  rollupOptions: {
    input: {
      main: resolve(import.meta.dirname, 'index.html'),
      about: resolve(import.meta.dirname, 'about/index.html'),
    },
  },
}

Each page becomes an entry; shared modules are put into shared chunks automatically.

Common problems

  • Mixed content or wrong host in assets: set server.origin (dev) and base (build).
  • CORS error loading /@vite/client: enable server.cors and allow your backend origin.
  • Missing manifest entry: the key is the source path relative to the project root, exactly as in input.
  • Stale assets after deploy: the template read an old manifest; read it fresh.
  • HMR socket fails behind a proxy: configure server.hmr.host/clientPort or use the same origin.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does build.manifest: true produce?

    A backend reads this file to print the correct hashed script, style and preload tags.
  2. 2. Why is server.cors needed when a backend page loads modules from the Vite dev server?

    The page origin (backend) differs from the dev server origin, and module scripts require CORS headers.
  3. 3. In a manifest, what do the imports of an entry list?

    imports names shared chunks (keys of other manifest entries) that the entry statically depends on.
  4. 4. Does server.proxy apply in production?

    In production your real server or CDN must route API requests.

Summary

  • A backend-driven app lists entries in rollupOptions.input and enables build.manifest.
  • In dev, templates point at the Vite server (with server.origin and CORS); in production they read the manifest.
  • Emit CSS links, modulepreload links for imports and the entry script.
  • Use server.proxy to forward API calls in dev only.
  • Multi-page apps are just several HTML entries.

Next: Testing with Vitest