What are Script Dependencies in WordPress?

Script dependencies in WordPress refer to the way WordPress manages the order and loading of JavaScript files required by themes, plugins, and blocks. This ensures that scripts that rely on other scripts are not loaded before their dependencies. It helps avoid errors or broken behavior caused by missing or improperly loaded scripts.

Registering and Enqueuing Scripts

To set and manage these dependencies, WordPress provides two main functions: wp_register_script and wp_enqueue_script.

wp_register_script is used to define a script, its location, version, load location (header or footer), and any dependencies it requires. This function does not load the script by itself.
wp_enqueue_script adds the script to the queue to be loaded. If a script was not registered earlier, it can be enqueued directly, including all its details in the same call.

Example:

php
wp_register_script(
    'custom-search',
    plugins_url( '/js/search.js', __FILE__ ),
    array( 'jquery' ),
    '1.0',
    true
);
wp_enqueue_script( 'custom-search' );

This code registers a script with the handle custom-search, sets jQuery as its dependency, and then enqueues it so that it’s actually loaded.

It is possible to skip registration and rely on wp_enqueue_script alone:

php
wp_enqueue_script(
    'custom-search',
    plugins_url( '/js/search.js', __FILE__ ),
    array( 'jquery' ),
    '1.0',
    true
);

This version both registers and enqueues the script in one step.

How Dependencies Work

The third parameter in both wp_register_script and wp_enqueue_script is an array of handles representing other scripts that must load before this one. WordPress parses these dependencies to determine the order of loading.

Here’s an example where one script depends on two others:

php
function custom_search_assets() {
    wp_enqueue_script(
        'custom-search',
        plugins_url( '/js/search.js', FILE ),
        array( 'jquery' ),
        '1.0',
        true
    );
}
add_action( 'wp_enqueue_scripts', 'custom_search_assets' );

This ensures jquery and custom-search are loaded before custom-search-spinner.

Hooks for Enqueuing Scripts

Depending on where the script is needed, different hooks are used:

wp_enqueue_scripts – used on the site’s front end.
admin_enqueue_scripts – used on admin dashboard pages.
login_enqueue_scripts – used on the login or registration pages.

These hooks allow you to load scripts only when needed. For example, use admin_enqueue_scripts to load code only in the WordPress admin panel.

Example:

php
add_action( 'wp_enqueue_scripts', 'custom_search_assets' );

This calls the custom_search_assets function only on front-end pages.

Gutenberg and Block Development

When building custom blocks, dependency management is handled with tools included in the @wordpress/scripts package. These tools help identify and bundle the correct script dependencies.

Install Packages

Install any packages your block uses:

bash
npm install @wordpress/components @wordpress/core-data

Import in Source Code

Reference packages in your JavaScript:

javascript
import { Button } from ‘@wordpress/components’;
import { useSelect } from ‘@wordpress/core-data’;

Generate Dependency File

When you build your plugin or theme scripts with wp-scripts, an index.assets.php file is created. This file includes the required dependencies and version number.

bash
wp-scripts build

The tool uses @wordpress/dependency-extraction-webpack-plugin to parse imports and create the dependency list automatically.

This PHP file can then be used in your enqueue code:

php
$asset_file = include plugin_dir_path( FILE ) . 'build/index.asset.php';
wp_enqueue_script(
    'my-block-script',
    plugins_url( 'build/index.js', FILE ),
    $asset_file['dependencies'],
    $asset_file['version'],
    true
);

The block will load the right dependencies in the proper order without hard-coding them.

Elementor Widget Scripts

With Elementor, scripts needed by a specific widget can be declared in the widget class. This is done using the get_script_depends method.

Example:

php
class Elementor_Test_Widget extends \Elementor\Widget_Base {
    public function get_script_depends(): array {
        return [ 'elementor-frontend', 'widget-custom-script' ];
    }
}

When the widget is used, Elementor ensures that both elementor-frontend and widget-custom-script are loaded.

Common Problems

Missing dependencies or incorrect enqueue order causes common issues. If a script needs jQuery but lists no dependencies, it may load before jQuery. This can lead to runtime errors, such as:

Uncaught TypeError: $ is not a function

Or:

someFunction is not defined

To avoid this, developers should list all required libraries in the dependency array.

Questions on forums often include how to load scripts at the right time, how to make sure scripts don’t run before jQuery, or how to fix undefined variable errors caused by premature execution.

Keeping Dependencies Updated

When working with JavaScript packages provided by WordPress, especially in block development, regular updates may be needed to stay in sync with WordPress core.

You can use the –dist-tag flag to match versions used by specific WordPress releases.

Example:

bash
wp-scripts packages-update –dist-tag=wp-6.0

This updates the installed packages to the versions matching WordPress 6.0, which helps test compatibility with that version.