(旧)JavaScript ビルド環境のセットアップ

(2023/12/24) この文書の原文は削除されました。以後は「ブロック開発の基本原理」以下を参照ください。便宜上、しばらく訳文を掲載しますが、内容は更新されず、一部古くなっていますので注意してお読みください。

ESNext は、ブラウザーのサポートする JavaScript よりも新しいバージョンで利用可能な構文や機能を使用して書かれた JavaScript です。サポートするブラウザーのバージョンは ECMAScript 5 (ES5) と参照されます。JSX は React プロジェクトで作成された JavaScript に対するカスタム構文拡張です。馴染みのある HTML タグに似た構文を使用して JavaScript を書くことができます。

標準の JavaScript と ESNext との一般的なコードの違いに関する説明と例については ESNext 構文ドキュメント を参照してください。

これらの構文を使用する開発環境をセットアップしましょう。このドキュメントではブロックエディターを始めとする Gutenberg プロジェクトと一緒に動作するプラグインの開発方法について説明します。Gutenberg 自身の開発については 入門 を参照してください。

ブラウザーは ESNext や JSX 構文を解釈したり実行することはできません。変換ステップを使用してすべてのブラウザが理解できるよう構文を変換する必要があります。

ESNext を使用し、さらに追加の変換手順を実行するのにはいくつかの理由があります。

• コードがシンプルになり、読みやすく、そして書きやすくなります。
• 変換ステップの途中で可能な限り多くのブラウザーをサポートするようにコードを最適化できます。
• ビルドステップを使用することで、コードを小さなモジュールやファイルに整理し、かつ、1つのダウンロードモジュールにバンドリングできます。

変換を実行するツールにはいくつかありますが WordPress では webpack と Babel を使用します。

webpack は JavaScript を処理するプラガブルなツールで、ブラウザー上で動作するコンパイル済みバンドルを作成します。Babel は JavaScript をある形式から別の形式に変換します。webpack のプラグインとして Babel を使用することで ESNext と JSX の両方を JavaScript に変換します。

@wordpress/scripts パッケージはこれらのライブラリーを標準化されたシンプルな開発に抽象化します。このため webpack や babel を細かく構成する必要はありません。構成の詳細については @wordpress/scripts パッケージのドキュメントを参照してください。

すぐに始めたいという方は以下の手順を省略し、Block Development Examples リポジトリー のサンプルを使用してください。Examples リポジトリーのそれぞれのサンプルの -esnext ディレクトリ下に ESNext や JSX の動作に必要なファイルが含まれています。

webpack も Babel も JavaScript で書かれており Node.js (node) を使用して動作します。Node.js はブラウザーの外での JavaScript 実行環境です。必要なファイルをコピーするだけでコマンドラインから JavaScript コードを実行できます。

はじめに開発環境に Node.js をセットアップする必要があります。手順はオペレーティングシステムによって異なりますが、パッケージマネージャーをインストールしていればセットアップは単純です。

• Ubuntu: apt install nodejs npm
• macOS: brew install node
• Windows: choco install node

パッケージマネージャーをインストールしていない場合は、nvm を使用した Node のセットアップについて 開発環境セットアップドキュメント を参照するか、または公式 Node.js ダウンロードページ を参照してインストーラーとバイナリーを入手してください。

注意: ビルドツールやプロセスはコマンドライン上で動作するため、ターミナルアプリケーションの基本的な使い方は覚える必要があります。テキストエディターの中には便利なビルトインターミナル機能があるものもあります。Visual Studio Code と PhpStorm は人気のあるエディターです。

node パッケージマネージャー (npm) は node に含まれる、JavaScript パッケージをインストールしたり管理するツールです。npm は専用のファイル package.json を生成し、処理します。package.json にはプロジェクトやプロジェクトの使用するパッケージ情報が含まれます。

新しい node プロジェクトを開始するには、まず作業用のディレクトリを作成します。

mkdir myguten-block
cd myguten-block

次に、ターミナルで npm init を実行して新しい package.json を作成します。出力される画面の指示に従ってください。

npm init

package name: (myguten-block) myguten-block
version: (1.0.0)
description: Test block
entry point: (index.js) build/index.js
test command:
git repository:
keywords:
author: mkaz
license: (ISC) GPL-2.0-only
About to write to /home/mkaz/src/wp/scratch/package.json:

{
  "name": "myguten-block",
  "version": "1.0.0",
  "description": "Test block",
  "main": "block.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "mkaz",
  "license": "GPL-2.0-only"
}


Is this OK? (yes) yes

次に必要なパッケージをインストールします。パッケージは npm コマンド npm install を使用してインストールします。コマンドにパラメータ --save-dev を指定すると package.json ファイル内に依存性のあるパッケージを書き出します。--save-exact パラメーターを指定すると npm は互換性のある複数のバージョンを含む範囲ではなく、正確なバージョンのみを依存の対象として書き出します。詳細については npm install ドキュメントを参照してください。

npm install --save-dev --save-exact @wordpress/scripts を実行してください。

インストール後、node_modules ディレクトリが作成され、モジュールと依存するパッケージがコピーされます。

package.json ファイルを参照すると次の新しいセクションが追加されています。

"devDependencies": {
  "@wordpress/scripts": "6.0.0"
}

@wordpress/scripts パッケージは webpack や Babel の依存性やデフォルトの構成を処理します。scripts パッケージはコンパイル対象のファイルが src/index.js にあることを期待し、コンパイルした結果を build/index.js に出力します。

以上を念頭に基本的なブロックを構成しましょう。以下の内容のファイル src/index.js を作成してください。

import { registerBlockType } from '@wordpress/blocks';

registerBlockType( 'myguten/test-block', {
	title: 'Basic Example',
	icon: 'smiley',
	category: 'design',
	edit: () => <div>Hola, mundo!</div>,
	save: () => <div>Hola, mundo!</div>,
} );

スクリプトを実行するよう npm を構成するには、package.json の scripts セクションを使用します。

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

これで次のコマンドでビルドを実行できます。 npm run build

ビルドが終わるとファイル build/index.js が作成されます。このファイルは、通常の WordPress での JavaScript ファイルと同様に管理画面にエンキューできます。このチュートリアルの JavaScript のロードを参照してください。エディターにブロックがロードされます。

@wordpress/scripts の build コマンドは本番モードで動作します。コードはダウンロード時間が短くなるよう圧縮されますが、結果、コードは読むことが難しくなります。start コマンドは開発モードで動作しコードを圧縮しません。プロセスは動作し続け、ソースファイルを変更するたびに再ビルドされます。

package.json の同じ scripts セクションに start コマンドを追加できます。

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

npm start を実行するとターミナルでウオッチャーが動作します。以降はテキストエディターでコードを編集し保管するごとに自動でビルドが実行されるため、編集、保存、リロードという通常の開発プロセスを回すことが出来ます。

注意: ターミナルに表示されるエラーには注意してください。編集ミスや構文のエラーがあるとビルドは失敗し、ターミナルにエラーが表示されます。

一般に node_modules フォルダーには大量のファイルが含まれ、バージョンが上がるたびにファイルが更新されるため node_modules/ はソースコントロールの対象から外します。リポジトリーのクローンから始める場合でも、package.json のあるフォルダーで npm install を実行すれば必要なパッケージがダウンロードされます。

同様に node_modules や構成ファイルをプラグインに含める必要はありません。webpack ビルド内部にバンドリングされます。プラグイン PHP の中では build/index.js ファイルを必ずエンキューしてください。このファイルが、ブロックの実行に必要なメインの JavaScript ファイルになります。

wp-scripts Version 5.0.0 以降を使用したビルドステップでは index.asset.php ファイルが生成され、中に依存性の配列とブロックのバージョンが記述されます。上のサンプルでは次のような内容になります。

array('dependencies' => array('wp-element', 'wp-polyfill'), 'version' => 'fc93c4a9675c108725227db345898bcc');

このアセットファイルを使用すると、エンキューするスクリプトの依存リストを自動で設定できます。手動で更新する必要はなくなり、依存性はブロック内で使用されるパッケージのインポートによって作成されます。

$asset_file = include( plugin_dir_path( __FILE__ ) . 'build/index.asset.php');

wp_register_script(
	'myguten-block',
	plugins_url( 'build/index.js', __FILE__ ),
	$asset_file['dependencies'],
	$asset_file['version']
);

完全なサンプルについては blocks in the block-development-examples リポジトリ を参照してください。

最初のセットアップは少々大変で時間がかかりますが、その後の機能や手間を考えれば十分、元は取れると思います。

セットアップを終えると、標準的なワークフローは以下のようになります。

1. 依存性のインストール: npm install
2. 開発ビルドの開始: npm start
3. 開発とテストの繰り返し
4. リリースビルドの作成: npm run build

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