diff --git a/docs/06-concepts/05-web-server/05-static-files.md b/docs/06-concepts/05-web-server/05-static-files.md index 54a1cc80..44ee9853 100644 --- a/docs/06-concepts/05-web-server/05-static-files.md +++ b/docs/06-concepts/05-web-server/05-static-files.md @@ -52,6 +52,14 @@ pod.webServer.addRoute( ); ``` +To set the header per environment instead of in code, set `SERVERPOD_WEB_SERVER_STATIC_CACHE_CONTROL` to the `Cache-Control` value the route should send: + +```bash +SERVERPOD_WEB_SERVER_STATIC_CACHE_CONTROL="public, max-age=3600" +``` + +The environment variable applies to every `StaticRoute` that does not pass a `cacheControlFactory` of its own. + Reserve `publicImmutable` for [cache-busted](#static-file-cache-busting) assets: `immutable` tells caches to never revalidate, which is only safe when a changed file also gets a new URL. On [Serverpod Cloud](/cloud/concepts/cdn), a CDN sits in front of the web server and honors these headers, and its cache is cleared on every deploy. diff --git a/docs/06-concepts/05-web-server/07-single-page-apps.md b/docs/06-concepts/05-web-server/07-single-page-apps.md index 927615fe..729841cf 100644 --- a/docs/06-concepts/05-web-server/07-single-page-apps.md +++ b/docs/06-concepts/05-web-server/07-single-page-apps.md @@ -59,6 +59,14 @@ pod.webServer.addRoute( ); ``` +To set the header per environment instead of in code, set `SERVERPOD_WEB_SERVER_SPA_CACHE_CONTROL` to the `Cache-Control` value the route should send: + +```bash +SERVERPOD_WEB_SERVER_SPA_CACHE_CONTROL="public, max-age=3600" +``` + +The environment variable applies to every `SpaRoute` that does not pass a `cacheControlFactory` of its own. Like the factory, it never applies to the fallback file, which is always served without a `Cache-Control` header so a deploy is never masked by a cached app shell. The `SERVERPOD_WEB_SERVER_STATIC_CACHE_CONTROL` variable used by `StaticRoute` does not apply here. + See [Static files](static-files#cache-control) for more on cache control, including why `publicImmutable` belongs only with cache-busted assets. ## Cache busting diff --git a/docs/06-concepts/lookups/configuration-reference.md b/docs/06-concepts/lookups/configuration-reference.md index ab556ffb..a1daec7e 100644 --- a/docs/06-concepts/lookups/configuration-reference.md +++ b/docs/06-concepts/lookups/configuration-reference.md @@ -21,7 +21,7 @@ Set the run mode, server role, and boot behavior. Declare each per run mode in t ## Server and services -Ports, hosts, and connection settings for the API, Insights, and web servers, the database, Redis, session logs, and future calls, plus a few options that exist only on the Dart config object. +Ports, hosts, and connection settings for the API, Insights, and web servers, the database, Redis, session logs, and future calls, plus a few options that exist only on the Dart config object or as environment variables. | Environment variable | Config file | Default | Description | | ------------------------------------------------ | ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -38,6 +38,9 @@ Ports, hosts, and connection settings for the API, Insights, and web servers, th | SERVERPOD_WEB_SERVER_PUBLIC_HOST | webServer.publicHost | - | The public host address of the Web server | | SERVERPOD_WEB_SERVER_PUBLIC_PORT | webServer.publicPort | - | The public port number for the Web server | | SERVERPOD_WEB_SERVER_PUBLIC_SCHEME | webServer.publicScheme | - | The public scheme (http/https) for the Web server | +| SERVERPOD_WEB_SERVER_STATIC_CACHE_CONTROL | N/A | - | The `Cache-Control` header for `StaticRoute` responses without a `cacheControlFactory`. See [Static files](../web-server/static-files#cache-control). | +| SERVERPOD_WEB_SERVER_SPA_CACHE_CONTROL | N/A | - | The `Cache-Control` header for `SpaRoute` responses without a `cacheControlFactory`. Never applies to the fallback file. See [Single-page apps](../web-server/single-page-apps#cache-control). | +| SERVERPOD_WEB_SERVER_FLUTTER_CACHE_CONTROL | N/A | - | The `Cache-Control` header for `FlutterRoute` responses without a `cacheControlFactory`. See [Flutter web](../web-server/flutter-web#cache-control). | | SERVERPOD_DATABASE_HOST | database.host | - | The host address of the database | | SERVERPOD_DATABASE_PORT | database.port | - | The port number for the database connection | | SERVERPOD_DATABASE_NAME | database.name | - | The name of the database |