Magento 2 Page Speed Documentation

  • Installation

    You can install the module for Magento 2 using Composer or you can manually install it using FTP.


    Run the following commands in your Magento 2 root directory to install the module using Composer.

    # Add the FishPig Composer repo
    composer config repositories.fishpig composer
    # Install the module using Composer
    composer require fishpig/magento2-pagespeed:*
    # Enable the module in Magento 2
    php bin/magento module:enable FishPig_PageSpeed
    # Run the Magento upgrade system
    php bin/magento setup:upgrade

    You can download the latest version of the module by logging in to your account and selecting Account > Projects.

    Extract the ZIP file and upload the files to your Magento site at the directory below:


    When creating the folders, ensure you use the correct capitalisation.

    To complete the installation, run the following commands in a terminal.

    # Enable the module in Magento 2
    bin/magento module:enable FishPig_PageSpeed
    # Run the Magento upgrade system
    bin/magento setup:upgrade

    ↑ Back to Top

  • JavaScript

    Magento 2 uses the RequireJS JavaScript library and is seen as very JavaScript heavy. A standard Magento 2 stock install has around 200 JavaScript files per page. Using PageSpeed, this can be reduced by around 50% and the overall size of the JavaScript content can be reduced (minify) significantly.

    Minify JavaScript

    JavaScript minification happens automatically (you don't have to recompile or run a command) and is applied to external files and inline code blocks. For external files, the .js extension is changed to .min.js and the result cached (so that it only happens once). For inline code blocks (ie. script tags), this cannot be cached but should be cached by your FPC.

    Defer Javascript

    Deferring JavaScript means moving it to the bottom of the page. This is useful because it stops the JavaScript from blocking and allows other items to be downloaded.

    To stop a specific piece of JavaScript being moved to the bottom of the page, simply add a HTML id parameter to the element.


    JavaScript Merging & Bundling

    JavaScript Merging

    The merging option provided by the module is just a shortcut to the default Magento 2 JS merging option. While this option is limited to only JavaScript files added in the HTML head (which is a very small number of JS files), there's generally no harm in enabling this.

    JavaScript Bundling

    JavaScript bundling means combining JavaScript files into separate bundles to decrease the number of HTTP requests per page. On a stock Magento 2 installation, there is roughly 200 JavaScript files to download. By bundling these files together, the number of HTTP requests can be reduced significantly, saving bytes and time.

    PageSpeed uses it's own algorithm that statically analyses the requirejs-config.js file to determine what JavaScript files are included on every page and the dependencies of those files. It then bundles all of these files into a single file.

    On a stock Magento 2 installation, this reduces the number of JS files (and HTTP requests) by around 100. This is a significant amount!

    As these files are included on every page, there is no extra JavaScript content download than is actually needed. This makes this system highly efficient as no a single byte of JavaScript is downloaded that isn't required and nothing is downloaded twice.

    Debug JavaScript Bundling

    You can see what JavaScript files are included in the bundle and what are downloaded individually by enabling the Bundle Debug option. Once enabled, this information is logged to the browser developer console, under the Info filter.

    This data includes the module ID and this will be useful in the Include Extra Files section below.

    Include Extra Files

    This option allows you to specify extra files that aren't included via requirejs-config.js but feature on every page. If you enable this option, a list of suggested files will be included for you. These files are very often included in the HTML via script tags on every page. An example of this would be the Magento cookies library. This is included right at the top of the HTML body on every page. By including this here, the cookie file (and it's dependencies) are included in the bundle, saving several http requests.

    To add your own files to this list, you need to use the module ID in RequireJS. If you aren't sure of this, enable the Bundle Debug option (see above) and this will provide the list of module IDs loaded on every page in the developer console.

    ↑ Back to Top

  • CSS

    PageSpeed will minify external CSS files as well as inline code blocks (style tags). You can enable and disable these features individually but it is generally recommended to keep both enabled.

    Defer CSS (Move to Bottom)

    Moving CSS to the bottom of the page will delay the execution of the CSS and cause the page to be unstyled, which isn't good for usability. It is therefore not recommend to enable this option. If you do enable this option, you will want to use the Magento 2 Critical CSS feature. This allows you to define a small amount of CSS to load right away so that the site (above the fold) looks styled and the remaining CSS will be deferred.

    This is a great feature but can be difficult to setup and get right so for most users, leaving this disabled will be the correct choice.

    ↑ Back to Top

  • HTML

    HTML minification can be a great way to reduce your overall page size by removing white space that isn't required to render your page.

    Minify Inline HTML

    This refers to HTML templates stored in a script tag to be used by JavaScript.

    Minify External HTML

    This refers to HTML templates accessed via AJAX.

    Remove Base URL

    This option will remove the base URL from your URLs and make them relative. This reduces the overall page size without affecting the functionality of your site.

    Remove Default Input Type

    Removes type=text from HTML input elements. This works because 'text' is the default value so if it's not specified, this is used. The only reason you might want to disable this is you have CSS rules that target type=text on inputs to style them in a specific way.

    ↑ Back to Top

  • Images

    Responsive Images

    PageSpeed will automatically create responsive images based on a set of pre-defined breakpoints. This list of breakpoints can be modified via the configuration, but the default value will serve fine for 99% of installations and does not need to be changed.

    This feature can reduce image sizes by up to 80% for mobile users without affecting the visual quality of the images.

    Webp Images

    Webp is a modern image format created by Google that allows for small and optimised images to be created. PageSpeed will automatically find and convert your images and provide a fallback for browsers that do not support Webp. This happens automatically and is fully compatible with all full page caches, including Varnish.

    Lazy Load Images

    PageSpeed's lazy loading image feature allows for dynamic loading of images based on the current scroll position. This means that images only download as they enter the current window. This feature is compatible with the responsive image feature.

    Lazy Load Iframes (YouTube)

    LazyLoading also works for iframes so any YouTube video that you embed will also be lazily loaded.

    ↑ Back to Top

  • CLI Commands

    Fix Duplicate Product Images

    If you have ever ran a GT Metrix speed report then you have probably seen the Serve resources from a consistent URL error message. This happens if products share the same images because Magento 2 does not detect duplicate images and creates a new copy with a different name. This can lead to many copies of one image being served for different products.

    Fixing this is a large manual task so we created a handy CLI command that will do it for you.

    # Calculate number of duplicate images
    bin/magento fishpig:pagespeed:duplicate-product-images
    # List duplicate images
    bin/magento fishpig:pagespeed:duplicate-product-images --list
    # Clean duplicate images from the database
    bin/magento fishpig:pagespeed:duplicate-product-images --clean
    # Clean duplicate images from the database and delete from server
    bin/magento fishpig:pagespeed:duplicate-product-images --clean --delete

    ↑ Back to Top