Vite Impl Backend Integration

vite-impl-backend-integration

Quick Reference

When This Skill Applies

Use this skill when:

• Integrating Vite with a backend framework (Django, Laravel, Rails, Express, ASP.NET, etc.)
• Rendering Vite-built assets from server-side templates
• Setting up dev/production HTML serving for a non-SPA architecture
• Reading .vite/manifest.json to resolve hashed asset paths

Architecture Overview

| Concern | Development | Production | |---------|------------|------------| | Asset serving | Vite dev server (localhost:5173) | Static files from dist/ | | HTML generation | Backend injects Vite client + entry scripts | Backend reads manifest.json, renders tags | | HMR | Automatic via @vite/client | N/A | | CSS | Injected by Vite dev server | Extracted as separate files | | Entry resolution | Direct source path | Hashed filename from manifest |

Critical Warnings

NEVER omit import 'vite/modulepreload-polyfill' from your entry point -- without it, `` tags will not work in browsers that lack native support.

NEVER hardcode hashed filenames in production templates -- ALWAYS read .vite/manifest.json at runtime or build time. Hashed names change on every build.

NEVER serve the Vite dev server scripts in production -- ALWAYS use environment detection to switch between dev mode HTML and production manifest rendering.

NEVER omit the React preamble when using @vitejs/plugin-react with a backend -- HMR will silently fail without it.

ALWAYS set build.manifest: true in vite.config.ts when integrating with a backend framework.

ALWAYS set server.cors to allow your backend origin during development.

ALWAYS specify build.rollupOptions.input (Vite 6/7) or build.rolldownOptions.input (Vite 8+) to define your entry point explicitly.

---

Configuration

vite.config.ts (Backend Integration)

import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    cors: {
      origin: 'http://my-backend.example.com',
    },
  },
  build: {
    manifest: true,
    // Vite 6/7:
    rollupOptions: {
      input: '/path/to/main.js',
    },
    // Vite 8+:
    // rolldownOptions: {
    //   input: '/path/to/main.js',
    // },
  },
})

Entry Point Setup

ALWAYS add the modulepreload polyfill as the first import in your entry file:

// main.js
import 'vite/modulepreload-polyfill'

// Rest of your application code
import './styles/app.css'
import { createApp } from './app'

createApp()

---

Development Mode

HTML Template (Dev)

In development, your backend template MUST include two scripts pointing to the Vite dev server:

React Preamble (Dev Only)

When using @vitejs/plugin-react, ALWAYS inject the React Refresh preamble BEFORE the Vite client script:

  import RefreshRuntime from 'http://localhost:5173/@react-refresh'
  RefreshRuntime.injectIntoGlobalHook(window)
  window.$RefreshReg$ = () => {}
  window.$RefreshSig$ = () => (type) => type
  window.__vite_plugin_react_preamble_installed__ = true

---

Production Mode

Manifest Location

After running vite build, the manifest file is located at:

dist/.vite/manifest.json

ManifestChunk Properties

| Property | Type | Description | |----------|------|-------------| | src | string | Original source file path | | file | string | Hashed output file path | | css | string[] | CSS files associated with this chunk | | assets | string[] | Non-JS/CSS assets imported by this chunk | | isEntry | boolean | Whether this is an entry point | | name | string | Short name of the chunk | | isDynamicEntry | boolean | Whether this is a dynamic import entry | | imports | string[] | Keys of statically imported chunks | | dynamicImports | string[] | Keys of dynamically imported chunks |

Rendering Order (CRITICAL)

For each entry point, ALWAYS render tags in this exact order:

1. `` for the entry chunk's own CSS files
2. `` for all recursively imported chunks' CSS files
3. `` for the entry chunk's JS file
4. `` for all recursively imported JS chunks

Manifest Traversal Algorithm

Use this recursive algorithm to collect all imported chunks (prevents duplicates via seen Set):

import type { Manifest, ManifestChunk } from 'vite'

export default function importedChunks(
  manifest: Manifest,
  name: string,
): ManifestChunk[] {
  const seen = new Set()

  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])
}

---

Dev vs Production Switching

Decision Tree

Is this a development environment?
├─ YES → Inject Vite dev server scripts into HTML
│        ├─ Using React? → Add React preamble FIRST
│        ├─ Add @vite/client script
│        └─ Add entry point script
└─ NO  → Read .vite/manifest.json
         ├─ Look up entry chunk by source path
         ├─ Collect CSS from entry + recursive imports
         ├─ Render  tags
         ├─ Render  for entry
         └─ Render  for imports

Server-Side Switching Pattern

# Example: Python/Django-style pseudocode
def vite_tags(entry: str) -> str:
    if settings.DEBUG:
        return dev_tags(entry)
    else:
        return production_tags(entry)

def dev_tags(entry: str) -> str:
    return f'''
        
        
    '''

def production_tags(entry: str) -> str:
    manifest = load_manifest('dist/.vite/manifest.json')
    chunk = manifest[entry]
    imported = get_imported_chunks(manifest, entry)
    tags = []
    # 1. Entry CSS
    for css in chunk.get('css', []):
        tags.append(f'')
    # 2. Imported CSS
    for imp in imported:
        for css in imp.get('css', []):
            tags.append(f'')
    # 3. Entry JS
    tags.append(f'')
    # 4. Modulepreload
    for imp in imported:
        tags.append(f'')
    return '\n'.join(tags)

---

Reference Links

• [references/manifest-reference.md](references/manifest-reference.md) -- ManifestChunk interface, manifest.json structure, traversal algorithm details
• [references/examples.md](references/examples.md) -- Complete dev HTML, production rendering, React preamble examples
• [references/anti-patterns.md](references/anti-patterns.md) -- Common backend integration mistakes and how to avoid them

Official Sources

• https://vite.dev/guide/backend-integration.html
• https://vite.dev/config/build-options.html#build-manifest
• https://vite.dev/config/server-options.html#server-cors

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Impertio-Studio
• Source: Impertio-Studio/Vite-Claude-Skill-Package
• License: MIT

Install and usage instructions live in the source repository linked above.