platform-docs/development/vite-nginx-cache-sync.md

Vite-Nginx Cache Directory Synchronization

When using a custom cacheDir in Vite configuration, the nginx config must have a corresponding location block to properly proxy requests.

The Problem

Vite pre-bundles dependencies into a cache directory. By default, this is node_modules/.vite/deps/. When you specify a custom cacheDir like .vite-cache, the browser requests modules from /.vite-cache/deps/.

If nginx doesn't have an explicit location block for this path, requests fall through to the catch-all / location and may not properly forward the Content-Type header, causing:

Loading module from "http://example.local/.vite-cache/deps/module.js"
was blocked because of a disallowed MIME type ("")

The Solution

When adding cacheDir to a Vite config, ensure the nginx template includes a location block:

In tooling/run/cli/commands/domains/@core/templates.ts

The generateViteHmrLocations() function should include:

location /.vite-cache/ {
    proxy_pass http://${upstreamName};
    proxy_http_version 1.1;
    proxy_set_header Host $host;
}

Verification

Run the sync validator:

bunx tsx infrastructure/scripts/validation/verify-vite-nginx-sync.ts

This checks all Vite configs for custom cacheDir settings and verifies nginx has matching location blocks.

CI/CD

Two workflows prevent this regression:

1. verify-vite-nginx-sync.yml - Validates config sync on PRs
2. e2e-smoke.yml - Tests actual module loading in browser

Checklist When Adding Custom cacheDir

1. Add cacheDir: '.vite-cache' to vite.config.ts
2. Update templates.ts to include location block
3. Run ./run domains:build (or manually update nginx config)
4. Run bunx tsx infrastructure/scripts/validation/verify-vite-nginx-sync.ts
5. Restart nginx: docker exec lilith-dev-nginx nginx -s reload