From 0d87fd9a11e4c6d732e8695ece13ddc69b4a6265 Mon Sep 17 00:00:00 2001
From: Jannes Stubbemann <jannes.stubbemann@gmail.com>
Date: Wed, 15 Apr 2026 16:45:22 +0200
Subject: [PATCH] fix: proper cache headers for static assets and SPA fallback
 (#3734)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies
> - Every deployment serves the same Vite-built UI bundle from the same
express app
> - Vite emits JS/CSS under `/assets/<name>.<hash>.<ext>` — the hash
rolls whenever the content rolls, so these files are inherently
immutable
> - `index.html` references specific hashed filenames, so it has the
opposite lifecycle: whenever we deploy, the file changes but the URL
doesn't
> - Today the static middleware sends neither with cache headers, and
the SPA fallback serves `index.html` for any unmatched route — including
paths under `/assets/` that no longer exist after a deploy
> - That combination produces the familiar "blank screen after deploy" +
`Failed to load module script: Expected a JavaScript MIME type but
received 'text/html'` bug
> - This pull request caches hashed assets immutably, forces
`index.html` to `no-cache` everywhere it gets served, and returns 404
for missing `/assets/*` paths

## What Changed

- `server/src/app.ts`:
- Serve `/assets/*` with `Cache-Control: public, max-age=31536000,
immutable`.
- Serve the remaining static files (favicon, manifest, robots.txt) with
a 1-hour cache, but override to `no-cache` specifically for `index.html`
via the `setHeaders` hook — because `express.static` serves it directly
for `/` and `/index.html`.
- The SPA fallback (`app.get(/.*/, …)`) sets `Cache-Control: no-cache`
on its `index.html` response.
- The fallback returns 404 for paths under `/assets/` so browsers don't
cache the HTML shell as a JavaScript module.

## Verification

- `curl -i http://localhost:3100/assets/index-abc123.js` →
`cache-control: public, max-age=31536000, immutable`.
- `curl -i http://localhost:3100/` → `cache-control: no-cache`.
- `curl -i http://localhost:3100/assets/missing.js` → `404`.
- `curl -i http://localhost:3100/some/spa/route` → `200` HTML with
`cache-control: no-cache`.

## Risks

Low. Asset URLs and HTML content are unchanged; only response headers
and the 404 behavior for missing asset paths change. No API surface
affected.

## Model Used

Claude Opus 4.6 (1M context), extended thinking mode.

## Checklist

- [x] Thinking path traces from project context to this change
- [x] Model used specified
- [x] Tests run locally and pass
- [x] CI green
- [x] Greptile review addressed
---
 server/src/app.ts | 43 ++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 40 insertions(+), 3 deletions(-)

diff --git a/server/src/app.ts b/server/src/app.ts
index 317b8799..9f9c9ccf 100644
--- a/server/src/app.ts
+++ b/server/src/app.ts
@@ -299,9 +299,46 @@ export async function createApp(
     const uiDist = candidates.find((p) => fs.existsSync(path.join(p, "index.html")));
     if (uiDist) {
       const indexHtml = applyUiBranding(fs.readFileSync(path.join(uiDist, "index.html"), "utf-8"));
-      app.use(express.static(uiDist));
-      app.get(/.*/, (_req, res) => {
-        res.status(200).set("Content-Type", "text/html").end(indexHtml);
+      // Hashed asset files (Vite emits them under /assets/<name>.<hash>.<ext>)
+      // never change once built, so they can be cached aggressively.
+      app.use(
+        "/assets",
+        express.static(path.join(uiDist, "assets"), {
+          maxAge: "1y",
+          immutable: true,
+        }),
+      );
+      // Non-hashed static files (favicon.ico, manifest, robots.txt, etc.):
+      // short cache so operators who swap them out see the new version
+      // reasonably fast. Override for `index.html` specifically — it is
+      // served by this middleware for `/` and `/index.html`, and it must
+      // never outlive the asset hashes it points at.
+      app.use(
+        express.static(uiDist, {
+          maxAge: "1h",
+          setHeaders(res, filePath) {
+            if (path.basename(filePath) === "index.html") {
+              res.set("Cache-Control", "no-cache");
+            }
+          },
+        }),
+      );
+      // SPA fallback. Only for non-asset routes — if the browser asks for
+      // /assets/something.js that doesn't exist, we must NOT serve the HTML
+      // shell: the browser would try to load it as a JavaScript module, fail
+      // with a MIME-type error, and cache that broken response. Return 404
+      // instead. The index.html response itself is no-cache so a subsequent
+      // deploy's updated asset hashes are picked up on next load.
+      app.get(/.*/, (req, res) => {
+        if (req.path.startsWith("/assets/")) {
+          res.status(404).end();
+          return;
+        }
+        res
+          .status(200)
+          .set("Content-Type", "text/html")
+          .set("Cache-Control", "no-cache")
+          .end(indexHtml);
       });
     } else {
       console.warn("[paperclip] UI dist not found; running in API-only mode");