When trying to get fine-grained control over your WordPress dependencies, aliasing assets like JavaScript and CSS can be useful. Whether you’re trying to simply create alternative handles for your resources, or you’re aiming to concatenate your asset pipeline, aliases are helpful to avoid breaking WordPress dependency management.

Dependency Aliasing Support in the WordPress core

Let’s explore how an alias is made. For both scripts and styles, the approach is the same, and (very quietly) documented in the WordPress core.

In class.wp-scripts.php:

		// A single item may alias a set of items, by having dependencies, but no source.
		if ( ! $obj->src ) {
			return true;
		}

Also refer to class.wp-styles.php:

	                // A single item may alias a set of items, by having dependencies, but no source.
	                if ( ! $obj->src ) {
	                        if ( $inline_style = $this->print_inline_style( $handle, false ) ) {
	                                $inline_style = sprintf( "<style id='%s-inline-css' type='text/css'>\n%s\n</style>\n", esc_attr( $handle ), $inline_style );
	                                if ( $this->do_concat ) {
	                                        $this->print_html .= $inline_style;
	                                } else {
	                                        echo $inline_style;
	                                }
	                        }
	                        return true;
	                }

Creating Your Own Script or Style Alias

In both circumstances, you’ll want to register your alias by calling wp_register_script or wp_register_style with an empty source. This ensures that usage of the alias does not load additional unwanted dummy or duplicate resources, and dependency trees and ordering are respected.

Simple Dependency Aliasing

For example, if you need to alias the script registered under the handle foolib-bar to be accessible as foolib-baz:

  add_action( 'wp_enqueue_scripts', function() {
    // function signature is wp_register_script( string $handle, string $src, array $deps = array(), string|bool|null $ver = false, bool $in_footer = false )
    wp_register_script( 'foolib-baz', null, array( 'foolib-bar' ), false, false );
  }, 10);

In this case, you can enqueue foolib-bar indirectly by enqueuing it under the alias foolib-baz.

WordPress Asset Concatenation through Dependency Aliasing

In the self-managed asset concatenation use case, consider a scenario where you are bundling the WordPress core jQuery JavaScript. You need any plugins or other scripts that depend on jQuery through their asset dependencies to be aware that your concatenated script provides the resource jquery. By aliasing the handle jquery to point to your own script’s handle as a dependency, you can satisfy the dependency without friction, and ensure that the core jQuery is not re-enqueued by any persistent plugins.

To alias an existing handle, first deregister the asset, then register your alias. For example, to indicate jquery is provided by foobundle:

  add_action( 'wp_enqueue_scripts', function() {
    // function signature is wp_register_script( string $handle, string $src, array $deps = array(), string|bool|null $ver = false, bool $in_footer = false )
    wp_deregister_script( 'jquery' );
    wp_register_script( 'jquery', null, array( 'foobundle' ), false, false );
  }, 10);

WordPress Script and Style Grouping with Aliases

One last helpful application of aliasing is grouping multiple related dependencies together. This is used within the WordPress core; for instance, jquery loads both jquery-core and jquery-migrate. Note that this type of grouping does not necessarily reflect an actual dependency, but can be used as a convenience method of loading several related assets or those belonging to different modules/components you want tied together.