humanmade/asset-loader

Utilities to seamlessly consume Webpack-bundled assets in WordPress themes & plugins.

v0.7.1 2024-08-21 19:48 UTC

Requires

• composer/installers: ^1.0 || ^2.0

Requires (Dev)

• 10up/wp_mock: ^1.0.0
• automattic/vipwpcs: ^3.0
• dealerdirect/phpcodesniffer-composer-installer: ^0.7
• phpcompatibility/php-compatibility: dev-develop as 9.99.99
• phpcompatibility/phpcompatibility-wp: ^2.1
• phpcsstandards/php_codesniffer: ^3.5
• phpunit/phpunit: ^9.5
• staabm/annotate-pull-request-from-checkstyle: ^1.8
• wp-coding-standards/wpcs: ^3.0

GPL-2.0-or-later

README

This plugin exposes functions which may be used within other WordPress themes or plugins to aid in detecting and loading assets generated by Webpack, including those served from local webpack-dev-server instances.

Usage

This library is designed to work in conjunction with a Webpack configuration (such as those created with the presets in @humanmade/webpack-helpers) which generate an asset manifest file. This manifest associates asset bundle names with either URIs pointing to asset bundles on a running DevServer instance, or else local file paths on disk.

Asset_Loader provides a set of methods for reading in this manifest file and registering a specific resource within it to load within your WordPress website. The primary public interface provided by this plugin is a pair of methods, Asset_Loader\register_asset() and Asset_Loader\enqueue_asset(). To register a manifest asset call one of these methods inside actions like wp_enqueue_scripts or enqueue_block_editor_assets, in the same manner you would have called the standard WordPress wp_register_script or wp_enqueue_style functions.

<?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.
 *
 * @return void
 */
function enqueue_block_editor_assets() {
  Asset_Loader\enqueue_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_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' ],
    ]
  );
}

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.