Skip to content
  • There are no suggestions because the search field is empty.

Running Convert with RequireJS and Other AMD Loaders

How to safely run Convert experiments on websites using RequireJS, AMD loaders, and other module-managed JavaScript environments

Author: Ahmed Abbas

THIS ARTICLE WILL HELP YOU:

Introduction

RequireJS and other Asynchronous Module Definition (AMD) loaders manage JavaScript modules by using a global define() function. They are common on Magento 2 storefronts, Dojo-based applications, and older enterprise front ends.

Convert's Web Testing tracking script is AMD-neutral: it does not register itself as an AMD module. Compatibility problems can still occur when custom variation code, project-level JavaScript, or a third-party library loaded by an experiment detects define.amd and registers a module that conflicts with the host application.

For AMD-based sites, review every external script loaded by your Convert code before launch.

Check Whether the Site Uses an AMD Loader

Open the browser console on the page where the experiment will run and enter:

typeof define === 'function' && !!define.amd

A result of true means an AMD loader is active on the page.

Treat this as a high-care implementation. Audit all JavaScript loaded by project-level code and variation code, including minified vendor bundles, before publishing the experiment.

Why UMD Bundles Can Cause Conflicts

Many libraries use a Universal Module Definition (UMD) wrapper so the same file can work with AMD, CommonJS, or a browser global.

A typical UMD bundle checks for define.amd. When the check succeeds, it may call one of the following:

define(factory); define([], factory); define('jquery', [], factory);

The first two examples register anonymous AMD modules. When a plain <script> element loads that file outside the AMD loader's normal module-loading process, RequireJS may be unable to associate the anonymous registration with the correct script. The result can be a Mismatched anonymous define() error or an incorrectly resolved module.

A named module can also be unsafe when its name collides with a module already owned by the page. For example, a third-party bundle that registers itself as jquery can replace the application's expected jQuery module even when the global window.jQuery still appears normal.

What Is Safe to Use in Variation Code

The following patterns are generally appropriate on an AMD-managed page:

  • Plain JavaScript that does not call define()
  • Immediately invoked function expressions (IIFEs) that keep variables scoped locally
  • Libraries built specifically for browser-global or CommonJS use without an AMD registration branch
  • AMD modules loaded through the site's own supported loader and module configuration
  • Named AMD modules whose names are unique, intentionally configured, and guaranteed not to collide with application modules

Before using a third-party bundle, search its source for define( and define.amd. Check the minified production file, not only the unminified source or package documentation.

Patterns to Avoid

Anonymous AMD registrations loaded through a plain script element

Avoid loading a bundle through <script src="..."> when it can execute define(factory) or define([], factory) on a page with an active AMD loader.

Module names owned by the host application

Do not register common names such as jquery, ko, or application-specific module IDs unless the host application's loader configuration explicitly expects that module.

Temporarily masking window.define

Do not use this asynchronous guard:

var originalDefine = window.define; window.define = undefined;  var script = document.createElement('script'); script.src = 'https://example.com/library.js';  script.onload = script.onerror = function () {   window.define = originalDefine; };  document.head.appendChild(script);

This pattern is dangerous because window.define remains unavailable for the entire asynchronous loading window. Any legitimate RequireJS module that finishes loading during that time can fail to register. The failure is timing-dependent, may disappear after a refresh or cache hit, and often surfaces later as a jQuery or application-module error.

If a library is not AMD-safe, use an AMD-neutral build, load it through the site's supported module loader, or replace it with a compatible library.

Project Settings to Review

jQuery setting

On a site that already provides and manages jQuery through RequireJS or another AMD loader, enable Do not include jQuery for the tracking-script generation used by the project.

Convert projects can show separate settings for the Legacy and Latest tracking scripts. Confirm which tracking script the project uses, then change the matching setting. The two controls have similar names, so verify the label carefully.

Do not disable Convert's bundled jQuery unless the page provides a compatible jQuery version before Convert runs. Disabling it on a page without jQuery can prevent an experiment from running.

Related article: Do not include jQuery into the tracking scripts

Visitor Insights and other optional scripts

Optional features and integrations can load additional JavaScript. On an AMD-based site, enable only the features required for the project and include their production bundles in the pre-launch audit.

Convert's current tracking script is AMD-neutral, but custom code and separately loaded libraries must still be reviewed independently.

Pre-Launch Checklist

  1. Run the AMD detection check on every relevant page template.
  2. Confirm whether the project uses the Latest or Legacy tracking script.
  3. Review the matching Do not include jQuery setting.
  4. Search all custom and vendor JavaScript for define( and define.amd.
  5. Reject anonymous AMD registrations loaded by plain script elements.
  6. Check named modules for collisions with the site's existing module IDs.
  7. Remove any code that temporarily sets window.define to undefined.
  8. Test uncached page loads, refreshes, and slow-network conditions.
  9. Verify critical actions such as navigation, Add to Cart, checkout, and form submission.
  10. Monitor the browser console for AMD, jQuery, and module-resolution errors.

Troubleshooting

Common symptoms include:

Mismatched anonymous define() module $ is not a function Cannot read properties of undefined Cannot set properties of undefined

These messages identify a module-resolution failure, but they do not identify the responsible file by themselves.

To isolate the source:

  1. Capture the complete console message and stack trace.
  2. Record the page URL, timestamp, browser, and whether the failure persists after refresh.
  3. List all scripts injected by project-level JavaScript and variation code.
  4. Disable external libraries one at a time while keeping the Convert tracking script installed.
  5. Inspect the actual production bundle for AMD registrations.
  6. Check whether require('jquery') returns the site's expected jQuery object and extensions.

For Magento 2 installation steps, see Integrate Convert Experiences with Magento 2.