Asset Loader

This plugin exposes functions which may be used within other WordPress themes or plugins to register and enqueue bundled script assets. It supports both wp-scripts-generated builds and custom Webpack configurations that output a JSON asset manifest.

Usage

Script Asset API (wp-scripts)

This plugin's primary public interface is for loading scripts built with wp-scripts. Use these functions for any wp-scripts-generated bundle that is not already auto-registered by register_block_type_from_metadata(). Dependencies and version information are read automatically from the .asset.php file generated alongside each bundle.

<?php
namespace My_Plugin\Scripts;

use Asset_Loader;

add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\\enqueue_block_editor_assets' );

function enqueue_block_editor_assets() {
    // Register and enqueue a wp-scripts bundle in one step.
    Asset_Loader\enqueue_script_asset(
        'my-plugin-editor',
        plugin_dir_path( __DIR__ ) . 'build/editor/index.js'
    );
}

add_action( 'wp_enqueue_scripts', __NAMESPACE__ . '\\enqueue_frontend_assets' );

function enqueue_frontend_assets() {
    // You can pass additional dependencies beyond those in asset.php.
    Asset_Loader\enqueue_script_asset(
        'my-plugin-frontend',
        plugin_dir_path( __DIR__ ) . 'build/frontend/index.js',
        [ 'some-other-script-handle' ]
    );
}

The wp-scripts build does not output an asset file for CSS assets or hash their filenames, so we recommend to use the standard wp_register_style and wp_enqueue_style functions directly for style assets unrelated to a particular block.

Manifest Asset API (custom Webpack)

For projects using a custom Webpack configuration that outputs a JSON asset manifest (such as those created with the presets in @humanmade/webpack-helpers), use Asset_Loader\register_manifest_asset() and Asset_Loader\enqueue_manifest_asset(). The manifest associates asset bundle names with either URIs pointing to asset bundles on a running DevServer instance, or else local file paths on disk.

<?php
namespace My_Theme\Scripts;

use Asset_Loader;

add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\\enqueue_block_editor_assets' );

/**
 * Enqueue the JS and CSS for blocks in the editor.
 */
function enqueue_block_editor_assets() {
  Asset_Loader\enqueue_manifest_asset(
    // In a plugin, this would be `plugin_dir_path( __FILE__ )` or similar.
    get_stylesheet_directory() . '/build/asset-manifest.json',
    // The handle of a resource within the manifest. For static file fallbacks,
    // this should also match the filename on disk of a build production asset.
    'editor.js',
    [
      'handle'       => 'optional-custom-script-handle',
      'dependencies' => [ 'wp-element', 'wp-editor' ],
    ]
  );

  Asset_Loader\enqueue_manifest_asset(
    // In a plugin, this would be `plugin_dir_path( __FILE__ )` or similar.
    get_stylesheet_directory() . '/build/asset-manifest.json',
    // Enqueue CSS for the editor.
    'editor.css',
    [
      'handle'       => 'custom-style-handle',
      'dependencies' => [ 'some-style-dependency' ],
    ]
  );
}

Block Extensions API

Use register_block_extension() to attach additional scripts and styles to an already-registered block type (core or third-party) via a block.json file, without registering a new block.

<?php
use Asset_Loader;

add_action( 'init', function() {
    // Extend core/paragraph with a custom viewScript and style.
    // The block.json at this path should have "name": "core/paragraph"
    // and declare assets using file:./relative paths.
    Asset_Loader\register_block_extension(
        plugin_dir_path( __FILE__ ) . 'build/blocks/core/paragraph/block.json'
    );
} );

Documentation

For complete documentation, including contributing process, visit the docs site.

License

This plugin is free software. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.