diff --git a/README.md b/README.md index a601f01..4399e1e 100644 --- a/README.md +++ b/README.md @@ -61,6 +61,75 @@ Note: bfcache availability may vary based on your Full Page Cache engine. * **Auto Close Menu** - Automatically close open menus when page is restored from back/forward cache (for compatible themes). (Default: Yes) * **Exclude URLs** - Optional configuration to exclude specific URL patterns from back/forward cache. Enter URL parts (substring), one per line. The extension automatically excludes non-cacheable URLs, so this is only needed for custom cached URLs that load private data via JavaScript. +#### If you use Varnish FPC + +For the Back/Forward Cache feature to work with Varnish Full Page Cache, you must modify your VCL file's `vcl_deliver` subroutine by updating the existing Cache-Control header logic. + +```vcl +sub vcl_deliver { + # Find the existing line that sets Cache-Control, like: + set resp.http.Cache-Control = "no-store, no-cache, must-revalidate, max-age=0"; + + # Replace it with: + if (resp.http.Cache-Control ~ "public") { + set resp.http.Cache-Control = "no-cache, must-revalidate, max-age=0"; + } else { + set resp.http.Cache-Control = "no-store, no-cache, must-revalidate, max-age=0"; + } +} +``` + +- This modification requires manual VCL file editing and Varnish service restart +- Test thoroughly in a staging environment before deploying to production +- Consider using [elgentos/magento2-varnish-extended](https://github.com/elgentos/magento2-varnish-extended) for a more complete enhanced Varnish configuration + +#### If you use Fastly (including Adobe Commerce Cloud) + +For Fastly CDN, you must create two custom VCL snippets through the Magento admin panel, as follows: + +**Step 1: Access VCL Snippets** +1. Navigate to **Stores** > **Settings** > **Configuration** > **Advanced** > **System** +2. Expand **Full Page Cache** > **Fastly Configuration** > **Custom VCL Snippets** +3. Click **Create Custom Snippet** + +**Step 2: Configure Snippet 1** +- **Name**: `bfcache-preserve-public-private` +- **Type**: `fetch` +- **Priority**: `1` +- **VCL Content**: + +```vcl +if (beresp.http.Cache-Control) { + if (beresp.http.Cache-Control ~ "public") { + set beresp.http.X-MageOS-Bfcache = "public"; + } else { + set beresp.http.X-MageOS-Bfcache = "private"; + } +} +``` +Save the snippet +Click **Create Custom Snippet** again + +**Step 3: Configure Snippet 2** +- **Name**: `bfcache-remove-ccns` +- **Type**: `deliver` +- **Priority**: `100` +- **VCL Content**: + +```vcl +if (fastly.ff.visits_this_service == 0 && req.restarts == 0) { + if (resp.http.X-MageOS-Bfcache == "public") { + set resp.http.Cache-Control = "no-cache, must-revalidate, max-age=0"; + } +} + +unset resp.http.X-MageOS-Bfcache; +``` +Save the snippet + +**Step 4: Deploy** + +Click **Upload VCL to Fastly**, and Activate the uploaded VCL ## Contributors Initial module, page transitions, and speculation rules contributed by [@rhoerr](https://github.com/rhoerr). diff --git a/etc/adminhtml/system.xml b/etc/adminhtml/system.xml index d4ec07a..83cb140 100644 --- a/etc/adminhtml/system.xml +++ b/etc/adminhtml/system.xml @@ -65,6 +65,7 @@ Go back and forwards in the browser history on most pages without reload, by allowing them to be cached in the browser temporarily.

+

Important: Support for bfcache depends on your Full Page Cache backend. While this module works out-of-the-box with Magento's built-in cache, using Varnish, Fastly, or other reverse proxies requires additional configuration. Please see the Varnish & Fastly Configuration section in the README for details.

]]>