PHPackages                             mage-os/module-theme-optimization - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. mage-os/module-theme-optimization

ActiveMagento2-module[Utility & Helpers](/categories/utility)

mage-os/module-theme-optimization
=================================

Page transitions and speculative loading rules for Magento

2.3.0(1mo ago)4120.3k↑27.9%8[1 issues](https://github.com/mage-os/module-theme-optimization/issues)OSL-3.0PHPPHP ~8.1.0||~8.2.0||~8.3.0||~8.4.0||~8.5.0CI passing

Since Aug 19Pushed 1mo ago3 watchersCompare

[ Source](https://github.com/mage-os/module-theme-optimization)[ Packagist](https://packagist.org/packages/mage-os/module-theme-optimization)[ RSS](/packages/mage-os-module-theme-optimization/feed)WikiDiscussions main Synced yesterday

READMEChangelog (10)Dependencies (6)Versions (13)Used By (0)

[![Latest Stable Version](https://camo.githubusercontent.com/08ba0a75107d775c304e9c6480f081b7074ef5847bfbe2af06d41c27987a4993/68747470733a2f2f706f7365722e707567782e6f72672f6d6167652d6f732f6d6f64756c652d7468656d652d6f7074696d697a6174696f6e2f762f737461626c65)](https://packagist.org/packages/mage-os/module-theme-optimization)[![License](https://camo.githubusercontent.com/ff03de7bb818418f855ff9c168f095c8bfb142e60354b57288f8ed1b049e7883/68747470733a2f2f706f7365722e707567782e6f72672f6d6167652d6f732f6d6f64756c652d7468656d652d6f7074696d697a6174696f6e2f6c6963656e7365)](https://packagist.org/packages/mage-os/module-theme-optimization)[![Total Downloads](https://camo.githubusercontent.com/bdd5987410c151e5df5ae7b4c7ba7d040d08276041e10b2ca4b8ce0e76a39632/68747470733a2f2f706f7365722e707567782e6f72672f6d6167652d6f732f6d6f64756c652d7468656d652d6f7074696d697a6174696f6e2f646f776e6c6f616473)](https://packagist.org/packages/mage-os/module-theme-optimization)

 [![Mage-OS](https://camo.githubusercontent.com/8d1ce626cc42a548d8e2b527b9e77ba8541b75b9129415c1229c73c9dfc8f3db/68747470733a2f2f6d6167652d6f732e6f72672f77702d636f6e74656e742f75706c6f6164732f323032332f30312f6d6167652d6f732d6c6f676f2e77656270)](https://mage-os.org)

MageOS\_ThemeOptimization module
================================

[](#mageos_themeoptimization-module)

This module provides theme-related features to improve the performance of your Magento store, including:

- Back/Forward Cache support for faster browser navigation
- Page transitions when navigating between pages on Magento
- Speculative preloading of internal links on hover

Requirements
------------

[](#requirements)

- Magento 2.4.5+ or equivalent version of Adobe Commerce, Adobe Commerce Cloud, or Mage-OS

Installation details
--------------------

[](#installation-details)

To install the module, run the following commands in SSH, from the Magento root directory:

```
composer require mage-os/module-theme-optimization
php bin/magento setup:upgrade
```

Configuration
-------------

[](#configuration)

The module provides settings in the Magento Admin Panel under: **Stores > Configuration > Advanced > System**

All values can be configured at Default, Website, and Store View scopes.

### Back/Forward Cache

[](#backforward-cache)

- **Enable Back/Forward Cache** - Enable back/forward cache to store pages in browser memory temporarily for faster navigation. (Default: Yes)
- **Update Mini Cart on User Interaction**
    - Yes: Mini cart updates only after user interaction when page is restored from cache (Default)
    - No: Mini cart updates immediately on page restore
    - Recommended "Yes" to maintain optimal Page Speed and Core Web Vitals scores
- **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.

Important

bfcache availability varies based on your Full Page Cache engine and hosting. Some require additional setup.

**READ MORE: Configuring Back/Forward cache with 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.

```
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

**READ MORE: Configuring Back/Forward cache with 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**:

```
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**:

```
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

### Speculative Loading

[](#speculative-loading)

- **Enable Speculation Rules** - Enables speculative loading to preload pages before links are clicked, making perceived load times faster. (Default: Yes)
- **Mode** - Choose between prefetch and prerender modes. (Default: prefetch)
    - Prefetch: Downloads resources in advance
    - Prerender: Fully renders pages in advance (faster but may affect analytics data and UI changes)
- **Eagerness Level** - Controls how aggressively pages are preloaded. (Default: Moderate)
    - Conservative: Minimal preloading, only when very likely to be needed
    - Moderate: Balanced approach between performance and resource usage
    - Eager: Aggressive preloading for maximum user experience, at the cost of loading pages the user may never visit
- **Exclude URL Patterns** - URL patterns to never preload. One pattern per line. (Default: customer, login, logout, auth, cart, checkout, search, download, redirect, rewrite, store, productalert)
    - URL patterns are matched against the request URI. We recommend entering part or full route paths, like "customer" (to exclude all customer pages) or "customer/account/logout" (to specifically exclude logout).
- **Exclude File Extensions** - File extensions to never preload. (Default: pdf, zip)
- **Exclude Selectors** - CSS selectors for links to never preload. Enter one selector per line. (Default: .do-not-prerender)

### View Transitions

[](#view-transitions)

- **Enable View Transitions** - Toggle animated page changes for storefront. (Default: Yes)
- **Enable View Transitions for Admin** - Enable transitions in Admin; disable if using a theme with built-in transitions. (Default: Yes)
- **Apply on Back/Forward** - Show transitions when using browser navigation; can be disabled for faster restores. (Default: Yes)

Contributors
------------

[](#contributors)

Initial module, page transitions, and speculation rules contributed by [@rhoerr](https://github.com/rhoerr).

Back/forward cache support was contributed by [Oli Jaufmann and @JaJuMa](https://github.com/JaJuMa).

Credit for the default speculation rules to [David Lambauer and @run\_as\_root](https://run-as-root.sh/blog/improving-pagespeed-with-speculative-loading).

This module is sponsored and maintained by [Mage-OS](https://mage-os.org). Mage-OS makes it open source and freely available for use by any Magento 2.4+ or Adobe Commerce website.

###  Health Score

56

—

FairBetter than 97% of packages

Maintenance89

Actively maintained with recent releases

Popularity41

Moderate usage in the ecosystem

Community18

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 54.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~29 days

Recently: every ~53 days

Total

10

Last Release

52d ago

Major Versions

1.0.0 → 2.0.0-alpha12025-09-17

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/100189073?v=4)[Mage-OS](/maintainers/mage-os-ci)[@mage-os-ci](https://github.com/mage-os-ci)

---

Top Contributors

[![rhoerr](https://avatars.githubusercontent.com/u/13335952?v=4)](https://github.com/rhoerr "rhoerr (20 commits)")[![mage-os-ci](https://avatars.githubusercontent.com/u/100189073?v=4)](https://github.com/mage-os-ci "mage-os-ci (6 commits)")[![GrimLink](https://avatars.githubusercontent.com/u/4387541?v=4)](https://github.com/GrimLink "GrimLink (5 commits)")[![JaJuMa](https://avatars.githubusercontent.com/u/12202801?v=4)](https://github.com/JaJuMa "JaJuMa (4 commits)")[![5mehulhelp5](https://avatars.githubusercontent.com/u/3060337?v=4)](https://github.com/5mehulhelp5 "5mehulhelp5 (1 commits)")[![SamueleMartini](https://avatars.githubusercontent.com/u/40766441?v=4)](https://github.com/SamueleMartini "SamueleMartini (1 commits)")

---

Tags

adobecommercecwvecommerceextensionmage-osmage-os-labmagentomagento2performance

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/mage-os-module-theme-optimization/health.svg)

```
[![Health](https://phpackages.com/badges/mage-os-module-theme-optimization/health.svg)](https://phpackages.com/packages/mage-os-module-theme-optimization)
```

###  Alternatives

[fastly/magento2

Fastly CDN Module for Magento 2.4.x

1564.4M1](/packages/fastly-magento2)[loki/magento2-components

Core module for defining Alpine.js components with advanced AJAX features

1011.8k26](/packages/loki-magento2-components)[fishpig/magento2-wordpress-integration

Securely integrate WordPress and Magento 2.

83369.2k7](/packages/fishpig-magento2-wordpress-integration)[run-as-root/magento2-prometheus-exporter

Magento2 Prometheus Exporter

68357.9k](/packages/run-as-root-magento2-prometheus-exporter)[zwernemann/module-withdrawal

Magento 2 EU Withdrawal Button Module - Adds a withdrawal/revocation button for orders in compliance with EU Directive (EU) 2023/2673

244.8k2](/packages/zwernemann-module-withdrawal)[myparcelnl/magento

A Magento 2 module that creates MyParcel labels

1860.2k](/packages/myparcelnl-magento)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)