How to combine external JavaScript in WordPress

Combining external JavaScript in WordPress can streamline site performance and improve loading times. This process involves enqueuing multiple scripts into a single request, ensuring that they are loaded efficiently and in the correct order. If you’re looking for a WordPress plugin to combine external JavaScript, we’ll also cover that below.

Understanding WordPress handles for JavaScript

WordPress uses a system of handles to manage scripts. A handle is a unique identifier for each script used to register, enqueue, deregister, or dequeue scripts. Proper handle management is crucial for avoiding conflicts, especially when dealing with multiple plugins and themes that might use similar script names. Always prefix your handle names to ensure uniqueness.

wp_enqueue_script( 'handle-name', 'path-to-script', array('dependency-handle'), 'version', true );

Each parameter serves a specific purpose:

• handle-name: A unique name for the script that avoids conflicts with other enqueued scripts.
• path-to-script: The URL to the script.
• array('dependency-handle'): An array of handles upon which the script depends. This is important for loading scripts in the right order.
• version: Script version number, useful for cache busting.
• true: Determines where in the page the script is placed. Setting this to true means the script will be placed in the footer, which is typically better for performance as it doesn't block the rendering of the page.

Choosing the right place to enqueue scripts

While the footer is often the best place for scripts to avoid blocking the page render, there are scenarios where a script might need to be in the head—for example, when a script is required for styling or immediate functionality as the page loads. In such cases, understanding the Critical Rendering Path is essential to minimize the performance impact.

Consolidating external JavaScript files

Manual consolidation

Manually combining scripts involves a few more steps but gives you full control over the process:

1. Use developer tools or a text editor to identify and list all external JavaScript files you want to combine.
2. Minify each file using online tools like UglifyJS or Google's Closure Compiler to reduce file size.
3. Concatenate all minified files into a single file using a tool or a command-line utility like cat in Unix-based systems.
4. Upload the resulting file to your server, ideally in a location that's backed up and not overwritten by WordPress updates, such as a custom folder within wp-content.
5. Enqueue this new file in your WordPress theme's functions file.

Use of plugins

Several plugins streamline this process. WP Rocket and Autoptimize are popular choices. These plugins typically offer settings to control which scripts are combined and where they are loaded.

// Example using a plugin like WP Rocket
if ( function_exists( 'rocket_minify_files' ) ) {
    $handle = 'combined-scripts';
    $scripts_to_combine = [
        get_template_directory_uri() . '/js/first-script.js',
        get_template_directory_uri() . '/js/second-script.js',
        // more scripts here
    ];
    wp_enqueue_script( $handle, rocket_minify_files( $scripts_to_combine ), [], null, true );
}

Each plugin has its own method of combining scripts, so refer to the specific documentation for the best approach.

Handling dependencies

Properly managing script dependencies ensures that scripts relying on other libraries, such as jQuery or React, are loaded after these libraries have loaded. Failure to define dependencies correctly can lead to JavaScript errors and broken functionality.

Conditional loading

Scripts should be loaded only where they are needed. WordPress offers conditional tags that allow developers to target specific pages or sets of pages:

function load_conditional_scripts() {
    if ( is_page( 'contact' ) ) {
        wp_enqueue_script( 'contact-form-script', get_template_directory_uri() . '/js/contact-form.js', ['jquery'], '1.0.0', true );
    }
}
add_action( 'wp_enqueue_scripts', 'load_conditional_scripts' );

By loading scripts only on pages where they are necessary, you can significantly reduce unnecessary HTTP requests, improving overall site performance.

Testing and debugging

Use tools such as Google Chrome's DevTools to monitor network requests and JavaScript console for errors. Performance testing tools like Google PageSpeed Insights, GTmetrix, or Pingdom can give you insights into how well your optimizations are performing.

Using async and defer attributes

async and defer are attributes that can be added to script tags to control when the script is executed. async will load the script asynchronously with the rest of the page while defer will ensure the script executes after the document has been parsed but before the DOMContentLoaded event. Each has its use case, and care must be taken when scripts depend on each other.

Updating and maintenance

Whenever scripts are updated, or new features are added, it's crucial to regenerate the combined script file. Automation tools like Webpack, Gulp, or Grunt can watch for changes in your JavaScript files and automatically rebuild the combined file.

Localizing scripts

When combined scripts need to interact with PHP (like retrieving URLs or nonce values), wp_localize_script() is used to safely pass data from PHP to JavaScript.

wp_enqueue_script( 'combined-handle', get_template_directory_uri() . '/js/combined-scripts.js', [], '1.0.0', true );
wp_localize_script( 'combined-handle', 'myScriptData', [
    'homeUrl' => home_url(),
    'nonce' => wp_create_nonce('my_nonce'),
    // Additional data as needed
]);

JavaScript can access myScriptData.homeUrl and myScriptData.nonce, using the data set in PHP, allowing for dynamic interaction in the combined script.

By taking these additional steps into account, you can create a more comprehensive, efficient, and dynamic approach to combining external JavaScript in WordPress, enhancing performance and maintainability.