perf(starters): configure adapters with proper caching headers

Author: wmertens

.changeset/fair-cars-fry.md

@@ -16,12 +16,19 @@ FEAT: Major improvements to prefetching with automatic bundle preloading
 
 ⚠️ **ATTENTION:**
 
-**Keep** your service worker code as is (either `<ServiceWorkerRegister/>` or `<PrefetchServiceWorker/>`).
+- **Keep** your service worker code as is (either `<ServiceWorkerRegister/>` or `<PrefetchServiceWorker/>`).
+- **Configure** your server to provide long caching headers.
+
+Service Worker:
 
 This new implementation will use it to uninstall the current service worker to reduce the unnecessary duplication.
 
 The builtin service workers components are deprecated but still exist for backwards compatibility.
 
+Caching Headers:
+
+The bundles under build/ are named with their content hash and may therefore be cached indefinitely. Typically you should serve `build/**/*.js` with `Cache-Control: public, max-age=31536000, immutable`.
+
 ---
 
 You can configure the prefetch behavior in your SSR configuration:
@@ -52,3 +59,4 @@ npm run qwik add service-worker
 ```
 
 This will add a basic service worker setup that you can customize for specific caching strategies, offline support, or other PWA features beyond just prefetching.
+

starters/adapters/aws-lambda/serverless.yml

@@ -18,6 +18,21 @@ functions:
 custom:
   serverless-offline:
     httpPort: 4000
+  serverless-http:
+    # Make sure serverless-http serves files correctly
+    binary:
+      contentTypes:
+        - "application/javascript"
+        - "text/javascript"
+        - "application/json"
+        - "text/html"
+        - "text/css"
+        - "image/*"
+        - "font/*"
+    # the js files under build have hash names and are immutable
+    cacheControl:
+      - pattern: "build/**/*.js"
+        value: "public, max-age=31536000, immutable"
 
 package:
   excludeDevDependencies: true

starters/adapters/azure-swa/public/staticwebapp.config.json

@@ -19,5 +19,12 @@
   },
   "platform": {
     "apiRuntime": "node:18"
+  },
+  "responseOverrides": {
+    "build/**/*.js": {
+      "headers": {
+        "Cache-Control": "public, max-age=31536000, immutable"
+      }
+    }
   }
 }

starters/adapters/bun/src/entry.bun.ts

@@ -16,6 +16,9 @@ import render from "./entry.ssr";
 const { router, notFound, staticFile } = createQwikCity({
   render,
   qwikCityPlan,
+  static: {
+    cacheControl: "public, max-age=31536000, immutable",
+  },
 });
 
 // Allow for dynamic port

starters/adapters/cloud-run/src/entry.cloud-run.tsx

@@ -53,7 +53,7 @@ const { router, notFound, staticFile } = createQwikCity({
   render,
   qwikCityPlan,
   static: {
-    cacheControl: "public, max-age=31557600",
+    cacheControl: "public, max-age=31536000, immutable",
   },
   getOrigin(req) {
     // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto

starters/adapters/deno/src/entry.deno.ts

@@ -16,6 +16,9 @@ import render from "./entry.ssr";
 const { router, notFound, staticFile } = createQwikCity({
   render,
   qwikCityPlan,
+  static: {
+    cacheControl: "public, max-age=31536000, immutable",
+  },
 });
 
 // Allow for dynamic port

starters/adapters/firebase/firebase.json

@@ -19,6 +19,17 @@
         "function": "app"
       }
     ],
-    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"]
+    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
+    "headers": [
+      {
+        "source": "build/**/*.js",
+        "headers": [
+          {
+            "key": "Cache-Control",
+            "value": "public, max-age=31536000, s-maxage=31536000, immutable"
+          }
+        ]
+      }
+    ]
   }
 }

starters/adapters/node-server/src/entry.node-server.tsx

@@ -19,6 +19,9 @@ const PORT = process.env.PORT ?? 3004;
 const { router, notFound, staticFile } = createQwikCity({
   render,
   qwikCityPlan,
+  static: {
+    cacheControl: "public, max-age=31536000, immutable",
+  },
 });
 
 const server = createServer();

starters/adapters/static/README.md

@@ -1,5 +1,9 @@
 ## Static Site Generator (Node.js)
 
+Be sure to configure your server to serve very long cache headers for the `build/**/*.js` files.
+
+Typically you'd set the `Cache-Control` header for those files to `public, max-age=31536000, immutable`.
+
 ```shell
 npm run build.server
 ```