Plans for Cache-Control: immutable with Static Assets in Vite Plugin (and Frameworks)

[benjavicente]

Hi!

There is an improvement that could be done about static assets on frameworks or with the new Vite plugin: adding the immutable cache header directive to immutable files generated with bundlers (files with a hash at the end).

The current default headers with must-revalidate,max-age=0 doesn't take advantage of the immutable strategy that most bundlers have, and (for what I have seen), headers aren't present on starting templates or in build outputs with the Vite plugin.

For example, Vite has an asset directory where every file has a hash in their name. If the content changes, the file name changes, so there isn't a need to revalidate the file content: it's immutable.

---

I made a PR for NextJS (OpenNext) for the starter template #9131 and in OpenNext docs opennextjs/docs#144

For Vite, there are 2 options: adding a _headers file to each template, or automatically add the header file.

The first option is a quick win, but I believe that the second option is better in the long run.

---

Vite has the build.assetsdir for configuring where generated assets end up. Some frameworks keep the default asstets directory, but some fremaworks change it (_nuxt, _astro), and even the users might change it for some reason.

For that reason, I believe it's preferable that _headers is generated by the build tool: the vite plugin. Also, I believe it isn't intuitive to add a _header file in the public folder to apply headers to immutable build output, since it isn't really there.

My proposal would be to consider an API like this:

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
  plugins: [
    cloudflare({
      // clear distinction that this only applies to static assets
      // if the file _headers (or _redirects) exists, throw an error
      staticAssets: {
        // immutableAssetUrl === `/${config.build.assetsdir}/*`
        headers: ({ immutableAssetUrl }) => [ // generates _headers
          { url: "/*", headers: [{ name: "Content-Security-Policy", value: "default-src 'self'" }]},
          { url: "/*.jpg", headers: [{ unset: "Content-Security-Policy" }]},
          // This last header could be applied by default if the user
          // doesn't provide a header url with the same value
          { url: immutableAssetUrl, headers: [{ name: "Cache-Control", value: "public,max-age=31536000,immutable" }]}
        ],
        // Similar idea for redirects
        redirects: () => [ // generates _redirects
          { source: "/blog/*", destination: "https://blog.my.domain/:splat", code: 302 }
        ],
      },
    }),
  ],
});

Users would benefit for faster subsequent loads by free if a default is added, and would allow clearer control of headers (and redirects).

Also, some frameworks allow users to add custom headers to pages (for example, routeRules in nitro, used on Nuxt and Analog) in their config file, so it would be adding static files headers close to the dynamic header configuration.

[benjavicente]

Note: I believe it's also important to inform users on the Static Assets docs that bundlers or frameworks expect that immutable assets are served with the appropriate immutable headers, which requires manual configuration. Obviously, adding that to each guide (including ones at the frameworks docs) ideally should be avoided.