Magento - how to include javascript file on a page by page basis

Magento - how to include javascript file on a page by page basis

August 4, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Magento - how to include javascript file on a page by page basis

Including JavaScript Files Page by Page in Magento

As a senior developer working on custom Magento modules, you often need to include specific JavaScript files only on certain pages like product view or list pages. While it’s straightforward to include scripts in the layout XML file, doing so globally isn’t always the best approach for performance and maintainability.

Why Include Scripts on a Page-Level Basis?

By including your JavaScript files at a page level, you ensure that they are only loaded when required. This reduces unnecessary HTTP requests and improves overall site speed. It also keeps your layout XML clean and organized by avoiding global script additions.

Including Scripts in Your Custom Module

To include JavaScript files specifically on product view or list pages, you’ll need to create a layout update file within your custom module. Here’s how:

  1. Create the Layout Update File In your module directory (e.g., app/code/Vendor/Module), navigate to the view/frontend/layout folder. If it doesn’t exist, create it.

  2. Define Your Layout XML

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <update handle="catalog_product_view"/>
</page>

This layout update file references the existing catalog product view page handle. By updating this handle, we can add our specific JavaScript files without affecting other pages.

  1. Add Your Script
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <update handle="catalog_product_view">
        <referenceBlock name="head.scripts">
            <block type="Vendor_Module/js/action" template="Vendor_Module::script.phtml"/>
        </referenceBlock>
    </update>
</page>

In this example, the script.phtml file contains our JavaScript code. This file should be located in your module’s view directory (app/code/Vendor/Module/view/frontend/templates).

  1. Create Your JavaScript File

Your script.phtml file might look something like this:

<script>
    require([
        'jquery',
        'Vendor_Module/js/my-library'
    ], function($, myLibrary) {
        myLibrary.init();
    });
</script>

This example uses RequireJS to load the jQuery library and a custom JavaScript file named my-library.js located in your module’s js folder.

Conclusion

By following this approach, you can efficiently include JavaScript files specifically on product view or list pages within your Magento 2 custom modules. This method promotes better code organization, improved performance, and easier maintenance compared to global layout script additions.

At Laravel Company, we specialize in developing high-performance e-commerce solutions using Magento, including optimized JavaScript inclusion strategies like the one outlined here. Don’t hesitate to reach out if you need help implementing this or any other Magento development task.

Remember, the key is to keep your layout XML clean and load only the necessary scripts based on the specific page being viewed. This approach ensures your site remains fast and efficient for both users and search engines.

Catalog Performance Extensions Themes

Our network