Skip to content

docs: Document the SPA and static cache control environment variables #775

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
developerjamiu merged 3 commits into from
Sep 3, 2026
Merged

docs: Document the SPA and static cache control environment variables #775

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
df0e3cc
docs: Document the SPA and static cache control environment variables
developerjamiu Sep 1, 2026
a02a36b
docs: List the cache control variables in the configuration reference
developerjamiu Sep 2, 2026
ea14ee9
Merge remote-tracking branch 'origin/main' into docs/spa-static-cache…
developerjamiu Sep 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/06-concepts/05-web-server/05-static-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Comment thread
developerjamiu marked this conversation as resolved.

```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.
Expand Down
8 changes: 8 additions & 0 deletions docs/06-concepts/05-web-server/07-single-page-apps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 4 additions & 1 deletion docs/06-concepts/lookups/configuration-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
| ------------------------------------------------ | ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
Expand All @@ -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 |
Expand Down
Loading