# mage-os/module-theme-optimization
> Page transitions and speculative loading rules for Magento
`composer require mage-os/module-theme-optimization`
Canonical URL: https://packagento.com/mage-os/module-theme-optimization
## At a glance
- **Vendor**: mage-os (https://packagento.com/mage-os.md)
- **Latest version**: 2.3.0 — released 2026-05-12
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers
## Installation
Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.
1. **Sign in or create an account** at https://packagento.com/customer/account/.
2. **Add the package to your account.** Open https://packagento.com/mage-os/module-theme-optimization and complete the free checkout. A licence is minted automatically.
3. **Create or pick a project, then activate the licence on it.**
- Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
- Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.
4. **Add the project credentials to your Magento codebase.**
Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:
```json
{
"http-basic": {
"packagento.com": {
"username": "ppk_live_...",
"password": "psk_live_..."
}
}
}
```
Add the Packagento Composer repository to `composer.json`:
```json
{
"repositories": [
{ "type": "composer", "url": "https://packagento.com" }
]
}
```
5. **Install and apply.**
```bash
composer require mage-os/module-theme-optimization:*
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush
```
## What it does
Page transitions and speculative loading rules for Magento
## README
[](https://packagist.org/packages/mage-os/module-theme-optimization)
[](https://packagist.org/packages/mage-os/module-theme-optimization)
[](https://packagist.org/packages/mage-os/module-theme-optimization)
## 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
* Magento 2.4.5+ or equivalent version of Adobe Commerce, Adobe Commerce Cloud, or Mage-OS
### Installation details
To install the module, run the following commands in SSH, from the Magento root directory:
```bash
composer require mage-os/module-theme-optimization
php bin/magento setup:upgrade
```
### 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
* **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.
>
> ```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
>
>
>
> 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**:
>
> ```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
>
_(README truncated for .md surface. Full README on https://packagento.com/mage-os/module-theme-optimization.)_
## Changelog
### [2.3.0] - 2026-05-11
#### Added
- PHP 8.4 and PHP 8.5 compatibility.
- Explicit `php` constraint in `composer.json` (`~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0`).
#### Changed
- Added `declare(strict_types=1)` to all PHP classes.
- Added explicit return types on all methods (including `Setup\Patch\Data\UpdateSpeculationRulesConfigPathPatch::apply()`, `getAliases()` and `getDependencies()`).
- Replaced `strpos($s, $needle) === 0` with `str_starts_with()` for clarity.
- Typed nullable parameters explicitly (e.g. `int|string|null $store`) to avoid the PHP 8.4 implicit nullable deprecation.
- Made constructor-promoted properties and helper methods `protected` instead of `private` for easier extension by downstream modules.
- Minor refactor: `unset` of loop reference variable after foreach-by-reference.
## Recent Versions
| Version | Released |
|---|---|
| 2.3.0 | 2026-05-12 |
| 2.2.1 | 2026-04-30 |
| 2.2.0 | 2025-11-01 |
| 2.1.0 | 2025-10-14 |
| 2.0.0 | 2025-10-10 |
| 2.0.0-rc1 | 2025-10-09 |
| 2.0.0-alpha3 | 2025-09-26 |
| 2.0.0-alpha2 | 2025-09-18 |
| 2.0.0-alpha1 | 2025-09-17 |
| 1.0.0 | 2025-08-19 |
## Dependencies
### Require
| Package | Constraint |
|---|---|
| magento/framework | ^103.0 |
| magento/module-store | * |
| php | ~8.1.0\|\|~8.2.0\|\|~8.3.0\|\|~8.4.0\|\|~8.5.0 |
### Require (dev)
| Package | Constraint |
|---|---|
| phpunit/phpunit | ^9.5\|\|^10.0 |
## Quality
Latest release (2.3.0) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.
### Compatibility
Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.
| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | Pass |
### Code Quality
Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.
#### Static Analysis
Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.
| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Fail | 7 | 5 errors, 2 warnings (ruleset: Magento2) |
| PHPMD | Warning | 2 | 2 rule violations (TooManyMethods:1, TooManyPublicMethods:1) |
| Cpd | Pass | 0 | |
| Composer validate | Info | 1 | valid; 1 advisory note (composer validate --strict) |
#### PHPStan
Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.
| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | Pass |
### Tests
Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.
#### Unit Tests
| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 2 | 2 | – | – |
| 2.4.8 | – | Pass | not tested | – |
| 2.4.9 | – | – | Pass | Pass |
#### Integration Tests
| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |
### Security
Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.
| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 | |
| Malware scan | Pass | 0 | |
## Licence and pricing
Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.
Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.
## Install via Claude Code or any MCP client
The Packagento MCP server can run the licence + project + Composer steps above in one tool call:
```
purchase_and_install_packages(
composer_names=["mage-os/module-theme-optimization"],
project_id="proj_xxx"
)
```
This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.
## Vendor
mage-os is a Magento 2 vendor on Packagento. See https://packagento.com/mage-os.md for their full catalogue.