fix: add immutable cache headers for Vite build assets

Vite-built assets (JS chunks, CSS) were served with no-cache headers
because the static files middleware only recognized builder-path assets
(under /_fresh/js/{BUILD_ID}/) as immutable.

Add an `immutable` flag to the file snapshot interface. The Vite plugin
marks manifest chunks and CSS as immutable (content-hashed filenames),
while public directory files remain non-immutable. The middleware checks
this flag alongside the existing path and query param checks.

Closes #3282

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: bartlomieju

packages/fresh/src/build_cache.ts

@@ -11,6 +11,7 @@ export interface FileSnapshot {
   filePath: string;
   hash: string | null;
   contentType: string;
+  immutable?: boolean;
 }
 
 export interface BuildSnapshot<State> {
@@ -28,6 +29,7 @@ export interface StaticFile {
   contentType: string;
   readable: ReadableStream<Uint8Array> | Uint8Array;
   close(): void;
+  immutable?: boolean;
 }
 
 // deno-lint-ignore no-explicit-any
@@ -87,6 +89,7 @@ export class ProdBuildCache<State> implements BuildCache<State> {
       size: stat.size,
       readable: file.readable,
       close: () => file.close(),
+      immutable: info.immutable,
     };
   }
 }

packages/fresh/src/dev/dev_build_cache.ts

@@ -425,6 +425,7 @@ export interface PendingStaticFile {
   pathname: string;
   filePath: string;
   hash: string | null;
+  immutable?: boolean;
 }
 
 export async function writeCompiledEntry(outDir: string) {
@@ -548,7 +549,13 @@ export async function prepareStaticFile(
   item: PendingStaticFile,
   outDir: string,
 ): Promise<
-  { name: string; hash: string; filePath: string; contentType: string }
+  {
+    name: string;
+    hash: string;
+    filePath: string;
+    contentType: string;
+    immutable?: boolean;
+  }
 > {
   const file = await Deno.open(item.filePath);
   const hash = item.hash ? item.hash : await hashContent(file.readable);
@@ -563,6 +570,7 @@ export async function prepareStaticFile(
         : item.filePath,
     ),
     contentType: getContentType(item.filePath),
+    immutable: item.immutable,
   };
 }
 

packages/fresh/src/middlewares/static_files.ts

@@ -89,7 +89,8 @@ export function staticFiles<T>(): Middleware<T> {
         (BUILD_ID === cacheKey ||
           url.pathname.startsWith(
             `${ctx.config.basePath}/_fresh/js/${BUILD_ID}/`,
-          ))
+          ) ||
+          file.immutable)
       ) {
         span.setAttribute("fresh.cache", "immutable");
         headers.append("Cache-Control", "public, max-age=31536000, immutable");

packages/fresh/src/runtime/server/preact_hooks.ts

@@ -507,13 +507,13 @@ function RemainingHead() {
       if (island.css.length > 0) {
         for (let i = 0; i < island.css.length; i++) {
           const css = island.css[i];
-          items.push(h("link", { rel: "stylesheet", href: css }));
+          items.push(h("link", { rel: "stylesheet", href: asset(css) }));
         }
       }
     });
 
     RENDER_STATE.islandAssets.forEach((css) => {
-      items.push(h("link", { rel: "stylesheet", href: css }));
+      items.push(h("link", { rel: "stylesheet", href: asset(css) }));
     });
 
     if (items.length > 0) {
@@ -702,7 +702,7 @@ function FreshRuntimeScript() {
       const islandSpec = island.file.startsWith(".")
         ? island.file.slice(1)
         : island.file;
-      return `import ${named} from "${basePath}${islandSpec}";`;
+      return `import ${named} from "${asset(`${basePath}${islandSpec}`)}";`;
     }).join("");
 
     const islandObj = "{" + islandArr.map((island) => island.name)
@@ -717,8 +717,9 @@ function FreshRuntimeScript() {
     const runtimeUrl = buildCache.clientEntry.startsWith(".")
       ? buildCache.clientEntry.slice(1)
       : buildCache.clientEntry;
-    const scriptContent =
-      `import { boot } from "${basePath}${runtimeUrl}";${islandImports}boot(${islandObj},${serializedProps});`;
+    const scriptContent = `import { boot } from "${
+      asset(`${basePath}${runtimeUrl}`)
+    }";${islandImports}boot(${islandObj},${serializedProps});`;
 
     return (
       h(

packages/plugin-vite/src/plugins/server_entry.ts

@@ -131,6 +131,7 @@ if (import.meta.hot) import.meta.hot.accept();`;
                 filePath: path.join(serverOutDir, id),
                 hash: null,
                 pathname: getAssetPath(id),
+                immutable: true,
               });
             }
           }
@@ -143,6 +144,7 @@ if (import.meta.hot) import.meta.hot.accept();`;
                 filePath: path.join(serverOutDir, id),
                 hash: null,
                 pathname: getAssetPath(id),
+                immutable: true,
               });
             }
           }

packages/plugin-vite/src/plugins/server_snapshot.ts

@@ -221,6 +221,7 @@ export function serverSnapshot(options: ResolvedFreshViteConfig): Plugin[] {
                 filePath: path.join(clientOutDir, chunk.file),
                 pathname: chunk.file,
                 hash: null,
+                immutable: true,
               });
 
               if (chunk.css !== undefined) {
@@ -233,6 +234,7 @@ export function serverSnapshot(options: ResolvedFreshViteConfig): Plugin[] {
                     filePath: path.join(clientOutDir, id),
                     hash: null,
                     pathname,
+                    immutable: true,
                   });
 
                   if (chunk.name === clientEntryName) {

packages/plugin-vite/tests/build_test.ts

@@ -606,3 +606,53 @@ integrationTest(
     );
   },
 );
+
+integrationTest(
+  "vite build - asset cache headers on CSS and JS",
+  async () => {
+    await launchProd(
+      { cwd: viteResult.tmp },
+      async (address) => {
+        // Fetch a page with islands to get CSS and JS asset URLs
+        const res = await fetch(`${address}/tests/island_hooks`);
+        const html = await res.text();
+
+        // CSS link tags should get immutable cache headers
+        const cssMatches = html.matchAll(
+          /href="(\/assets\/[^"]*\.css[^"]*)"/g,
+        );
+        for (const match of cssMatches) {
+          const href = match[1];
+          const cssRes = await fetch(`${address}${href}`);
+          await cssRes.body?.cancel();
+          expect(cssRes.status).toEqual(200);
+          expect(cssRes.headers.get("Cache-Control")).toEqual(
+            "public, max-age=31536000, immutable",
+          );
+        }
+
+        // JS module imports should get immutable cache headers
+        const scriptMatch = html.match(
+          /<script[^>]*type="module"[^>]*>([\s\S]*?)<\/script>/,
+        );
+        expect(scriptMatch).not.toBeNull();
+        const scriptContent = scriptMatch![1];
+
+        const importMatches = scriptContent.matchAll(
+          /from "([^"]+)"/g,
+        );
+        for (const match of importMatches) {
+          const url = match[1];
+          if (url.startsWith("/assets/") || url.includes("/assets/")) {
+            const jsRes = await fetch(`${address}${url}`);
+            await jsRes.body?.cancel();
+            expect(jsRes.status).toEqual(200);
+            expect(jsRes.headers.get("Cache-Control")).toEqual(
+              "public, max-age=31536000, immutable",
+            );
+          }
+        }
+      },
+    );
+  },
+);