wp_enqueue_script_module()が便利！ WordPressでES Modulesを読み込む方法

はじめに

WordPressでフロントのJavaScriptを組むとき、昔ながらの wp_enqueue_script() だけでは管理しづらい場面が増えてきました。特に、機能をモジュール分割しているプロジェクトでは「依存関係をどう表現するか」が悩みやすいポイントです。

そんなときに使いやすいのが Script Modules API です。wp_register_script_module() と wp_enqueue_script_module() を使うと、ES Modules前提の読み込みをWordPress流に整理できます。

この記事では、まず基本の登録と読み込みから始めて、実務でよくある「モジュール依存と遅延読み込み」を含むパターンまでまとめます。

機能やライブラリの概要

Script Modules API は、WordPressでES Modulesを扱うためのAPI群です。関数リファレンスでは、主に次の2つを使います。

  • wp_register_script_module()
    モジュールID、URL、依存関係、バージョンなどを登録する
  • wp_enqueue_script_module()
    登録済みモジュールを実際にページへ出力する

このAPIの良いところは、モジュールの依存をWordPress側で管理できる点です。
import タイプを static / dynamic で指定できるので、必要な分だけ読み込む設計にも寄せやすくなります。

基本の使い方

まずは、1つのモジュールを登録して読み込む基本形です。最小構成のプラグイン例で見てみます。

PHP
<?php
/**
 * Plugin Name: Site Demo Script Modules Sample
 */

add_action( 'wp_enqueue_scripts', function () {
    $base_url = plugin_dir_url( __FILE__ ) . 'assets/js/';

    wp_register_script_module(
        'site-demo/site-header',
        $base_url . 'site-header.js',
        array(),
        '1.0.0'
    );

    wp_enqueue_script_module( 'site-demo/site-header' );
} );
JavaScript
// assets/js/site-header.js
const header = document.querySelector(".site-header")

if (header) {
  header.classList.add("is-module-ready")
}

この形なら、従来のスクリプト読み込みと同じ感覚で始められます。違いは「モジュールID」を中心に設計できることです。あとから依存を増やすときも整理しやすくなります。

便利な使いどころ

Script Modules API は、次のようなプロジェクトで特に効きます。

  • 機能ごとに assets/js/*.js を分割している
  • 画面ごとに必要な処理だけ読み込みたい
  • テーマとプラグインでJSの責務を分けたい
  • 同じ処理を複数テンプレートから再利用したい

特に、モジュール依存を明示できる点が実務向きです。
コードを読む人が「どのファイルがどの機能に依存しているか」を追いやすくなり、保守時の事故が減ります。

応用コード

ここでは、utils を静的依存として常に読み込みつつ、分析処理だけ動的依存にする例を紹介します。初期表示コストを抑えたい場面で使いやすいパターンです。

PHP
<?php
add_action( 'wp_enqueue_scripts', function () {
    $base_url = plugin_dir_url( __FILE__ ) . 'assets/js/';

    wp_register_script_module(
        'site-demo/utils',
        $base_url . 'utils.js',
        array(),
        '1.0.0'
    );

    wp_register_script_module(
        'site-demo/header-analytics',
        $base_url . 'header-analytics.js',
        array(),
        '1.0.0'
    );

    wp_register_script_module(
        'site-demo/site-header',
        $base_url . 'site-header.js',
        array(
            array(
                'id'     => 'site-demo/utils',
                'import' => 'static',
            ),
            array(
                'id'     => 'site-demo/header-analytics',
                'import' => 'dynamic',
            ),
        ),
        '1.0.0'
    );

    wp_enqueue_script_module( 'site-demo/site-header' );
} );
JavaScript
// assets/js/site-header.js
import { clamp } from "./utils.js"

const progress = clamp(window.scrollY / 300, 0, 1)
document.documentElement.style.setProperty("--header-progress", String(progress))

if (progress > 0.2) {
  import("./header-analytics.js").then((module) => {
    module.trackHeaderShrink()
  })
}

この構成では、utils は初回ロードで確実に使えるようにし、header-analytics は条件を満たしたときだけ読み込みます。
機能を増やしても「常時必要な処理」と「遅延でよい処理」を切り分けやすいのがメリットです。

注意点

  • ハンドルではなくモジュールIDを設計する
    命名が曖昧だと依存関係が追いづらくなります。plugin-or-theme/feature 形式で統一すると管理しやすいです。
  • フック位置を誤らない
    フロント用は wp_enqueue_scripts、管理画面用は admin_enqueue_scripts など、用途に応じたフックを使い分けるのが安全です。
  • 動的依存を増やしすぎない
    遅延読み込みは便利ですが、分割しすぎると逆に把握しづらくなります。まずは分析系や補助機能から切り出すのが無難です。

まとめ

Script Modules API は、WordPressでES Modulesを運用するための実務向けの土台です。wp_register_script_module() と wp_enqueue_script_module() を使うだけで、依存の見通しがかなり良くなります。

特に、テーマやプラグインのJavaScriptが増えてきたプロジェクトでは効果が出やすいです。まずは1機能をモジュール化して読み込みを整理し、次に静的依存と動的依存の分離へ進める流れがおすすめです。

ポイント

  • WordPressでES Modulesを扱うなら Script Modules API が整理しやすい
  • static と dynamic を使い分けると初期表示の負荷を調整しやすい
  • モジュールID命名ルールを先に決めると長期運用が安定する

参考リンク

read next