wp-scripts 入門

@wordpress/scripts パッケージは構成ファイルとスクリプトのセットで、一般に wp-scripts と呼ばれます。主に JavaScript のビルド手順を必要とする WordPress プロジェクトの開発プロセスの標準化と簡素化を目的とします。

JavaScript のビルド手順とは、JavaScript のソースコードと関連アセットを本番環境に適した形式に変換、バンドル、最適化するプロセスを指します。これらのビルド手順は多くの場合、最新の JavaScript (ESNext と JSX) をほとんどのブラウザと互換性のあるバージョンに変換します。また、複数のファイルを1つにバンドルし、コードを最小化してファイルサイズを縮小し、コードを最適化するその他のさまざまなタスクを実行します。

ブロックエディター用にビルドする場合、通常は ESNext と JSX を使用します。ブロックエディターハンドブックのほとんどの例もこの構文で書かれています。したがってビルド手順の設定方法の学習が重要になりますが、webpack や Babel や ESLint のような必須ツールの構成は複雑です。ここで wp-scripts の出番です。

wp-scripts で以下を実行できます。

• コンパイル： Babel を使用して、モダンなJavaScript（ESNextとJSX）をほとんどのブラウザと互換性のあるコードに変換します。
• バンドル: webpack を使用して、複数の JavaScript ファイルを1つのバンドルにまとめ、パフォーマンスを向上します。
• コードの lint: ESLint の構成を提供し、コードの品質とコーディング標準への準拠を保証します。
• コードフォーマット: 自動コードスタイリングのために Prettier を組み込み、プロジェクト間で一貫したコードフォーマットを維持します。
• Sass コンパイル: Sass (.scss または .sass) ファイルを標準的な CSS に変換します。
• コードの最小化: JavaScript コードのサイズを縮小し、ページロードを高速化します。

このパッケージは、最新の WordPress 向けの JavaScript 開発に関連する初期設定、構成、定型コードの多くを抽象化します。開発者はブロックの構築とブロックエディターの拡張に集中できます。

@wordpress/create-block パッケージを使用すると、ブロックの作成と登録に必要なファイル構造の雛形を作成できます。また構成なしでモダンな JavaScript ビルドセットアップ（wp-scripts を使用）も入手でき、wp-scripts のインストールやアセットのエンキューを心配する必要はありません。詳しくは create-block 入門を参照してください。

コンピューターに Node.js と npm がインストールされていることを確認してください。インストールされていない場合は、Node.js 開発環境 ガイドを参照してください。

次に、プロジェクトフォルダを作成し、その中に package.json ファイル、build フォルダ、src フォルダを作成してください。src フォルダには index.js ファイルも作成する必要があります。

package.json ファイルを作成したことがなければ、ターミナルでプロジェクトフォルダに移動して npm init コマンドを実行してください。対話的にプロンプトが表示され、手順が説明されます。自由に構成できますが、「entry point」はbuild/index.js と入力してください。

もちろん、wp-scripts を使用したプロジェクトのセットアップ方法は多数ありますが、ブロックエディターハンドブックではこの方法を推奨しています。

最後に、wp-scripts パッケージを開発依存としてインストールします。

npm install @wordpress/scripts --save-dev

インストールが完了すると、プロジェクトフォルダーは次のようになるはずです。

example-project-folder/
├── build/
├── node_modules/ (自動生成)
├── src/
│   └── index.js
├── package-lock.json (自動生成)
└── package.json

インストールが完了したら、wp-scripts で提供されている定義済みのスクリプトを package.json ファイルの scripts セクションで参照して実行できます。以下はその例です。

{
    "scripts": {
        "start": "wp-scripts start",
        "build": "wp-scripts build"
    }
}

これらのスクリプトは npm run {スクリプト名} コマンドを使用して実行できます。

最もよく使うスクリプトはビルド手順を処理する start と build の2つです。すべてのオプションについては パッケージのドキュメント を参照してください。

ブロックで作業するときは、 npm run start コマンドを使用します。開発サーバーを起動し、コードの変更を検出するたびに、自動的にプロジェクトをリビルドします。注意: build/index.js にコンパイルされたコードは最適化されません。

プロジェクトをデプロイする準備ができたら、 npm run build コマンドを使用します。コードが最適化され、本番環境に適用できます。

ビルドが終了すると、コンパイルされた JavaScript ファイルが build/index.js として作成されます。

ビルドプロセスでは build/index.asset.php ファイルも作成され、中には依存関係の配列とバージョン番号 (cache busting、キャッシュ破棄のため) が含まれます。この wp-scripts ビルドプロセスなしでブロックを登録するには、手動で *.asset.php 依存ファイルを作成する必要があることに注意してください (例を参照)。

register_block_type を介してブロックを登録すると、block.json で定義されたスクリプトは自動的にエンキューされます (例を参照)。

エディター内でファイルを手動でエンキューするには、他の任意のコンテキストにおける詳細を エディター内でのアセットのエンキューガイドを参照できますが、ここでは典型的な実装を紹介します。

/**
 * Enqueue Editor assets.
 */
function example_project_enqueue_editor_assets() {
    $asset_file = include( plugin_dir_path( __FILE__ ) . 'build/index.asset.php');

    wp_enqueue_script(
        'example-editor-scripts',
        plugins_url( 'build/index.js', __FILE__ ),
        $asset_file['dependencies'],
        $asset_file['version']
    );
}
add_action( 'enqueue_block_editor_assets', 'example_project_enqueue_editor_assets' );

エディター内でファイルを手動でエンキューする例です。

start と build が最もよく使われるスクリプトですが、他にも wp-scripts には便利なツールが複数用意されています。ここではそのいくつかを紹介します。

開発者がコードの品質を向上できるように、wp-scriptsには ESLint や Prettier のようなツールがあらかじめ設定されています。ESLint は JavaScript がベストプラクティスと WordPress コーディング規約に準拠していることを確認します。Prettier はコードを自動的にフォーマットします。利用可能なスクリプトは以下の通りです。

{
    "scripts": {
        "format": "wp-scripts format",
        "lint:css": "wp-scripts lint-style",
        "lint:js": "wp-scripts lint-js",
    }
}

定期的にコードを lint し、フォーマットすることで、自分自身や他の開発者にとって機能的でわかりやすく、保守しやすいコードになります。

コードを書くだけでなく、機能を検証することも重要です。wp-scripts には、JavaScript のテストフレームワーク Jest と、エンドツーエンドとユニットテストの両方のスクリプトが含まれています。

{
    "scripts": {
        "test:e2e": "wp-scripts test-e2e",
        "test:unit": "wp-scripts test-unit-js"
    }
}

ユニットテストは関数などの個々のコード単位で検証し、意図したとおりに動作することを保証します。一方、エンドツーエンド (E2E) テストは、実際のユーザーシナリオをシミュレートしてプロジェクト全体を評価し、システムのすべての部分がシームレスに連動することを確認します。

wp-scripts はデフォルト設定で十分機能しますが、特殊な設定が必要な場合もあります。良いニュースとして wp-scripts は非常に拡張性に優れます。例えば、デフォルトの webpack の設定を拡張し、上書きでき、ローダーやプラグインを追加し、ビルドプロセスのほとんどすべての部分を変更できます。この柔軟性により、プロジェクトが成長したり、要件が変更されても、進化するニーズに wp-scripts を適用できます。

すべての構成オプションについては wp-scripts パッケージのドキュメント を参照してください。

• @wordpress/scripts (公式ドキュメント)
• webpack と WordPress パッケージの関係 (WordPress Developer Blog)

原文

最終更新日: 2023年12月2日