---
name: bolt-asset-caching
description: >-
  Use this skill whenever setting up, optimizing, or debugging client/CDN HTTP caching for Bolt CMS images, thumbnails, CSS, JS, and PDFs. Resolves the critical Symfony SessionListener bug where stateful firewalls rewrite League Glide's public 1-year thumbnail cache to private/no-cache, configures Bolt's save_files thumbnail disk dump, sets up Apache mod_expires and Nginx static expires rules, establishes frontend asset cache-busting (?v=X.X), and checks end to end — Apache with the project's .htaccess plus PHP-FPM, or production — that every thumbnail and upload is served from disk with ETag, Last-Modified, max-age and 304s instead of by PHP.
title: bolt-asset-caching
canonical_url: https://skilld.dev/gh/vondry/bolt-skills/bolt-asset-caching
last_updated: 2026-11-03T05:06:53.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [examples/config_snippet.yaml](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-asset-caching/examples/config_snippet.yaml), [examples/htaccess_mod_expires.conf](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-asset-caching/examples/htaccess_mod_expires.conf), [examples/nginx_static.conf](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-asset-caching/examples/nginx_static.conf), [examples/security.yaml](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-asset-caching/examples/security.yaml), [scripts/check-delivery.php](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-asset-caching/scripts/check-delivery.php), [scripts/serve-apache.sh](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-asset-caching/scripts/serve-apache.sh), [scripts/verify.sh](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-asset-caching/scripts/verify.sh).
>
> If the user asked to install this Skill, run `npx skilld install vondry/bolt-skills/bolt-asset-caching`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/bolt-asset-caching`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/vondry/bolt-skills/bolt-asset-caching) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/bolt-asset-caching`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/bolt-asset-caching --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/bolt-asset-caching --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Bolt CMS Full-Stack Asset & Thumbnail Caching

In Bolt CMS websites, media files, thumbnails, and compiled stylesheets/scripts account for the vast majority of HTTP requests and bandwidth. Without end-to-end caching configuration across Symfony, Bolt core, and the web server (Apache/Nginx), browsers will re-download assets on every visit, degrading Core Web Vitals and overloading PHP-FPM.

This skill documents the complete multi-layer asset caching architecture established across production Bolt CMS repositories.

---

## 1. The Core Root Cause: The Symfony Thumbnail Cache Destruction Bug

### Why Thumbnails Were Not Being Cached:
1. **Glide's Intended Behavior:**
   Bolt CMS dynamically generates manipulated thumbnails on demand via `Bolt\Controller\ImageController` using **League Glide**. Under the hood, Glide sets a public one-year cache header:
   ```http
   Cache-Control: max-age=31536000, public
   Expires: ...
   ```
   It sends **no `ETag` and no `Last-Modified`**, so a browser can't revalidate a thumbnail that PHP served (no `304 Not Modified`); once the year is over, or after a hard reload, it downloads the whole image again. Only a thumbnail saved to disk and served by Apache / Nginx (Step 2) gets `ETag`, `Last-Modified` and 304s.
2. **The Default Symfony Firewall:**
   In standard Symfony and Bolt starter configurations (`config/packages/security.yaml`), the stateless `dev` firewall (which disables security tokens and session handling) only matched:
   ```yaml
   firewalls:
     dev:
       pattern: ^/(_(profiler|wdt)|css|images|js)/
       security: false
   ```
   **Notice that `/thumbs` is omitted.**
3. **The Silent Downgrade:**
   Requests for `/thumbs/320x240/hero.webp` fall through to Symfony's stateful `main` firewall (`pattern: ^/`).
   The `main` firewall initializes the security token and touches the user session. When Symfony's `SessionListener` executes on the response, it detects an active session context and **overwrites Glide's public cache header** with:
   ```http
   Cache-Control: private, must-revalidate, max-age=0
   ```
4. **The Impact:**
   Browsers and CDNs (Cloudflare, Fastly, etc.) strictly obey `private, max-age=0` and refuse to store thumbnails in disk or memory cache. Every page reload triggers full image transfers and forces PHP to repeatedly handle thumbnail requests!

---

## 2. Multi-Layer Caching Architecture

To achieve optimal performance, assets are cached through four synchronized layers:

```text
Request Path:
Browser / CDN
  │
  ├── 1. Direct Web Server Static Cache (Apache mod_expires / Nginx expires 2M)
  │      └── Serves public/files/, public/assets/, and disk-saved public/thumbs/
  │          straight from disk without booting PHP.
  │
  └── 2. First-time Thumbnail Generation (/thumbs/...)
         └── Handled by Symfony / Bolt ImageController
             │
             ├── Bypass Firewall (security.yaml): No session touched -> Glide sends public, max-age=31536000.
             └── Disk Dump (config/bolt/config.yaml save_files: true):
                 Saves to public/thumbs/ so subsequent requests hit Layer 1 directly!
```

---

## 3. Step-by-Step Implementation

### Step 1: Bypass the Security Firewall for `/thumbs`
File: `config/packages/security.yaml`

Update the `dev` firewall pattern to explicitly include `thumbs`:

```yaml
# config/packages/security.yaml

security:
  firewalls:
    dev:
      pattern: ^/(_(profiler|wdt)|css|images|js|thumbs)/
      security: false
```

* **Why this works:** The `/thumbs/` route is now processed statelessly. No security listeners or session managers run, preserving League Glide's `Cache-Control: public, max-age=31536000` header on the HTTP response.

---

### Step 2: Enable Thumbnail Disk Caching (`save_files: true`)
File: `config/bolt/config.yaml`

Ensure `save_files: true` is configured in the `thumbnails` section:

```yaml
# config/bolt/config.yaml

thumbnails:
  default_thumbnail: [ 320, 240 ]
  default_image: [ 1000, 750 ]
  quality: 80
  cropping: crop
  # Save generated thumbnails directly to public/thumbs/ on disk
  save_files: true
  allow_upscale: false

# The upload whitelist (accept_file_types / accept_media_types) is part of
# bolt-security-hardening (examples/config_snippet.yaml).
```

* **How this operates:**
  1. **First request:** The file does not exist on disk in `public/thumbs/`. The request hits PHP, generates the thumbnail, streams it back to the user, and dumps the binary to `public/thumbs/{parameters}/{filename}`.
  2. **Subsequent requests:** Apache and Nginx find the file directly on disk via standard static file rules and serve it directly with 0 ms PHP overhead!

* **bolt/core 6.0.1 – 6.1.x:** these versions save thumbnails to `public/thumbs/<w>_<h>_<q>_<fit>_<location>/` (e.g. `400_300_80_crop_files/`), a path no thumbnail URL points to. The web server never finds them, so **every `/thumbs/…` request still runs PHP** (with Glide's headers from section 1). No fix is coming in 6.x: bolt/core PRs #3828 and #3829 were closed unmerged, and the maintainers plan a new thumbnail route for Bolt 7 (bolt/core #3840). Thumbnails keep working, just through PHP; once a release fixes it, delete the unused `public/thumbs/*_files/` folders (locally and on the server). `scripts/verify.sh` detects the affected versions in `vendor/`, and the delivery check (section 4) shows where each thumbnail actually comes from.

---

### Step 3: Configure Apache Static Expiration (`public/.htaccess`)
File: `public/.htaccess`

Add the `mod_expires` configuration block. `bolt-htaccess` owns `public/.htaccess` and ships the same block: keep **one** `<IfModule mod_expires.c>` and merge missing types into it — a second block makes it unclear which rules apply.

```apache
# public/.htaccess

<IfModule mod_expires.c>
    ExpiresActive On

    # Images (uploads in public/files/ and disk thumbnails in public/thumbs/)
    ExpiresByType image/avif "access plus 2 months"
    ExpiresByType image/gif "access plus 2 months"
    ExpiresByType image/jpeg "access plus 2 months"
    ExpiresByType image/png "access plus 2 months"
    ExpiresByType image/svg+xml "access plus 2 months"
    ExpiresByType image/webp "access plus 2 months"
    # Favicons keep a fixed URL (no ?v=), so a shorter lifetime. Apache names .ico
    # image/vnd.microsoft.icon (current mime.types) or image/x-icon (older).
    ExpiresByType image/vnd.microsoft.icon "access plus 1 week"
    ExpiresByType image/x-icon "access plus 1 week"

    # Documents
    ExpiresByType application/pdf "access plus 2 months"

    # Frontend assets (styles, scripts) — cache-busted with ?v={{ theme.assets_version }}.
    # Apache serves .js as text/javascript (newer mime.types) or application/javascript (older).
    ExpiresByType text/css "access plus 2 months"
    ExpiresByType text/javascript "access plus 2 months"
    ExpiresByType application/javascript "access plus 2 months"

    # Fonts
    ExpiresByType font/woff2 "access plus 1 year"
    ExpiresByType font/woff "access plus 1 year"
</IfModule>
```

* **Without this block** Apache sends uploads and saved thumbnails with `ETag` and `Last-Modified` but without `max-age` / `Expires`, so browsers revalidate every image on every page view. `scripts/verify.sh` fails when the block is missing.
* **TTL Rationale:** A 2-month window (`access plus 2 months`) provides maximum cache hit rates while dropping `must-revalidate`, allowing browsers to serve assets instantly from disk cache.
* **JavaScript MIME types:** current Apache `mime.types` serve `.js` as `text/javascript`; older ones as `application/javascript`. List both, otherwise scripts get no expiry header on newer servers.

---

### Step 4: Configure Nginx Static Expiration (`docker/nginx/conf.d/default.conf`)
File: `docker/nginx/conf.d/default.conf`

The `/theme/`, `/files/` and `/thumbs/` locations come from **`bolt-security-hardening`** (`examples/docker/nginx_security.conf`): they serve only allowlisted file types, set `expires 2M`, and pass a thumbnail that is not on disk yet to Bolt (`try_files $uri /index.php`). Use that file; do not add a second `/thumbs` location — Nginx refuses duplicate locations.

For the rest of `public/` (Bolt's admin assets in `/assets/` and `/bundles/`, a favicon in the root) add the generic static block from [`examples/nginx_static.conf`](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-asset-caching/examples/nginx_static.conf):

```nginx
location ~* ^.+\.(?:avif|css|gif|ico|jpe?g|js|png|svg|webp|woff2?|ttf|otf|webmanifest|pdf|mp4|webm)$ {
    access_log                    off;
    log_not_found                 off;
    expires                       2M;
    try_files                     $uri =404;
}
```

* **No `add_header` in these locations.** An `add_header` inside a location drops every `add_header` of the server block for that location — the HSTS and `nosniff` headers of `bolt-security-hardening` would disappear from every image. `expires 2M` already sends `Cache-Control: max-age=5184000`; an extra `add_header Cache-Control "public"` would send a second `Cache-Control` header, and `Pragma` has no effect on modern browsers.

### Step 5: Frontend Asset Cache-Busting (`?v=X.X`)

Because CSS and JS are now served with 2-month caching, browsers will not check the server for updates until the cache expires. To ensure instant updates upon releasing new styling or scripts, append a version query string to asset paths in the theme's layout shell. The version lives in `theme.yaml` (`assets_version`), so a release changes one line:

```twig
{# public/theme/<theme_name>/partials/_master.twig (bolt-theme-init) #}

<link rel="stylesheet" href="{{ asset('css/index.css') }}?v={{ theme.assets_version|default('1.0') }}">
<script defer src="{{ asset('js/app.js') }}?v={{ theme.assets_version|default('1.0') }}"></script>
```

```yaml
# public/theme/<theme_name>/theme.yaml
assets_version: '1.4'
```

Whenever CSS or JS is rebuilt for a new release, bump `assets_version` (e.g. `'1.3'` → `'1.4'`), forcing all browsers to immediately fetch the new files while retaining long-lived caching. A hard-coded `?v=1.3` in the template works the same way but has to be changed in every layout that loads the assets (`partials/_master.twig`, `helper-pages/_helper_template_without_master.twig`). Bolt registers the active theme as the default asset package on frontend and error pages, so `asset('css/index.css')` resolves to `/theme/<theme_name>/css/index.css`.

---

## 4. Verification & Testing

### 1. Automated Verification Script
Run the automated test runner:

```bash
skills/bolt-asset-caching/scripts/verify.sh
```

The script verifies:
1. `config/packages/security.yaml` dev firewall contains `thumbs` (`^/(_(profiler|wdt)|css|images|js|thumbs)/`).
2. `config/bolt/config.yaml` has `thumbnails.save_files: true`.
3. `public/.htaccess` has `mod_expires.c` with image expiration rules (fails without them); warns when JavaScript is listed only as `application/javascript` (without `text/javascript`) or when more than one `mod_expires` block exists.
4. `docker/nginx/conf.d/default.conf` (if present) has `expires` and `try_files` for `/thumbs`.
5. `vendor/bolt/core` saves thumbnails at the path of their URL; warns on bolt/core 6.0.1 – 6.1.x (Step 2).
6. If a Symfony CLI server runs for the project: the `Cache-Control` of a generated thumbnail is `public`, not `private, max-age=0`.
7. The end-to-end delivery check below, when `scripts/serve-apache.sh` is running for the project or `BOLT_DELIVERY_URL` points at a staging / production site (fails on any thumbnail or upload not served from disk with full cache headers). It does not use `BOLT_BASE_URL`, which is usually `symfony serve` (`bolt-audit` sets `BOLT_DELIVERY_URL` from its `--base-url` when Apache or Nginx answers there). The quick header check of one thumbnail before it runs against `BOLT_BASE_URL` when set and reachable, otherwise against the project's `symfony serve`.

The configuration checks can all pass while every thumbnail still runs PHP (bolt/core 6.0.1 – 6.1.x, a read-only `public/thumbs/`, a web server rule that never looks on disk). Only the delivery check shows what the web server actually does.

### 2. End-to-End Delivery Check (`scripts/check-delivery.php`)
Crawls the running site (`/sitemap.xml` and links), collects every image the pages reference — `/thumbs/…`, `/files/…`, theme images, `srcset`, CSS `url()`, icons, `og:image` — and requests each one three times:

1. **first request** — may go to PHP, which generates and saves the thumbnail;
2. **second request** — must come from disk, with `ETag`, `Last-Modified` and a `max-age`;
3. **conditional request** with the `ETag` / `Last-Modified` of the second — must answer `304`.

It fails when a thumbnail or upload doesn't; theme images only warn, and image URLs that answer 404 are listed as broken references.

Run it against the web server the site runs on in production. `symfony serve` and PHP's built-in server ignore `.htaccess` and send uploads without `ETag` and `Cache-Control`; the check warns when the responses look like that. For an Apache site, `scripts/serve-apache.sh` serves the project locally like the production host — Apache with the project's own root and `public/` `.htaccess` files, PHP-FPM in `prod` — and sets up a PHP-FPM access log that records which requests reached PHP:

```bash
bash $SKILLS/bolt-asset-caching/scripts/serve-apache.sh start --port=8090      # prints the commands below
php $SKILLS/bolt-asset-caching/scripts/check-delivery.php \
    --base-url=http://127.0.0.1:8090 --fpm-log=var/serve-apache/logs/php-fpm-access.log
bash $SKILLS/bolt-asset-caching/scripts/serve-apache.sh stop
```

`serve-apache.sh` needs Apache (`httpd` / `apache2` with `mod_rewrite`, `mod_expires`, `mod_headers`, `mod_proxy_fcgi`) and `php-fpm`; it writes only to `var/serve-apache/` (kept out of `git status`), and Symfony builds `var/cache/prod` on the first request. Run `bin/console cache:clear --env=prod` first if that cache is stale. The check sends `X-Forwarded-Proto: https` to local URLs, so the root `.htaccess` HTTPS redirect stays quiet.

While `serve-apache.sh` runs, `scripts/verify.sh` (and `verify-all.sh`) include the delivery check automatically. The same script works against staging or production (`--base-url=https://example.com`, or `BOLT_DELIVERY_URL=https://example.com` for `verify.sh`; read-only GET requests). Without `--fpm-log` it counts a response without `ETag` and without `Accept-Ranges` as PHP — Bolt's thumbnail responses send neither, Apache and Nginx send both for static files. Add `--alias=www.example.com` when the pages link to the site under another host name, `--details` to list every URL, `--json=report.json` for the raw results.

A passing site looks like this (a thumbnail goes through PHP once, when it is generated):

```text
category  URLs  1st PHP  2nd disk  2nd PHP    broken  ETag  LastMod  max-age   304
thumbs      69       69        69        0         0    69       69       69    69
files       53        0        53        0         0    53       53       53    53
```

On bolt/core 6.0.1 – 6.1.x the same site shows `2nd PHP 69`, no `ETag` / `Last-Modified` and no 304s for thumbnails. A freshly saved thumbnail can carry a weak ETag (`W/"…"`): Apache marks files changed within the last second as weak; 304s work the same.

### 3. Manual HTTP Header Inspection
Test live response headers using `curl -I`:

```bash
# 1. Test thumbnail headers (request it twice — the first request may generate it)
curl -I https://example.com/thumbs/320x240/foto/hero.webp

# Expected Headers (served from disk):
# HTTP/2 200
# cache-control: max-age=5184000
# etag: "..."
# last-modified: ...
# A response without etag / last-modified and with max-age=31536000, public came from PHP (Glide).
# It must never contain "private, max-age=0".

# 2. Test static media headers
curl -I https://example.com/files/foto/hero.webp

# Expected Headers:
# HTTP/2 200
# cache-control: max-age=5184000 (or expires in 2 months)

# 3. Test CSS/JS cache headers
curl -I https://example.com/theme/mytheme/css/index.css?v=1.1
```

---

## 5. Common Pitfalls & Solutions

### Pitfall 1: Session Started in Custom Middleware
- **Symptom:** Even with `thumbs` in `security: false`, headers occasionally show `private`.
- **Cause:** A custom EventSubscriber or Twig extension injected `RequestStack::getSession()` without checking `hasSession()`.
- **Fix:** Never start sessions for asset routes or ensure session calls are guarded by `if ($request->hasSession())`.

### Pitfall 2: Thumbnails Still Served by PHP Despite `save_files: true`
- **Symptom:** the delivery check reports thumbnails as `2nd PHP`; their responses have `Cache-Control: max-age=31536000, public` but no `ETag` / `Last-Modified`, and `public/thumbs/` fills with folders like `400_300_80_crop_files/`.
- **Cause:** bolt/core 6.0.1 – 6.1.x save thumbnails to a path no thumbnail URL points to (Step 2).
- **Fix:** none in the project — wait for a bolt/core release that fixes it (PRs #3828 / #3829 were closed unmerged; a new thumbnail route is planned for Bolt 7, bolt/core #3840), then delete the unused `public/thumbs/*_files/` folders. Until then thumbnails keep working through PHP, with Glide's year-long `Cache-Control`; list it as an expected warning in the site plan.

### Pitfall 3: `public/thumbs/` Directory Permissions
- **Symptom:** Bolt logs `Cannot dump file public/thumbs/... Permission denied`.
- **Cause:** the PHP process (PHP-FPM user, or the hosting account) cannot write to `public/thumbs/`.
- **Fix (server with a shell):**
  ```bash
  mkdir -p public/thumbs
  chmod -R 775 public/thumbs
  chown -R www-data:www-data public/thumbs
  ```
- **Fix (SFTP shared hosting):** PHP runs as the hosting account, which owns the uploaded files, so `chown` is neither possible nor needed. Create `public/thumbs/` in the SFTP client and give it write permission for the owner (`755`; `775` only when the host's panel says PHP runs as a different user). Never upload `public/thumbs/` from a local machine — the server generates its own.

### Pitfall 4: A Replaced Upload Keeps Its Old Version for Two Months
- **Symptom:** an editor replaces `files/logo.png` with a new file under the same name; visitors keep seeing the old one.
- **Cause:** uploads are cached for two months (`access plus 2 months`) and their URL did not change — unlike CSS and JS, they have no `?v=` version.
- **Fix:** upload the new version under a new name (`logo-2026.png`) and pick it in the record. Thumbnails of the old file stay valid for the old URL only.
