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

このページでは ESNext と JSX 構文を利用する開発環境のセットアップについて説明します。ESNext は ECMAScript 5 (略称 ES5) 以上の仕様の機能を使用した JavaScript コードです。JSX は JavaScript のカスタム構文拡張で、より馴染みのあるタグ構文を使用して JavaScript を書くことができます。

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

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

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

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

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

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

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

クイックスタート

すぐに始めたいという方は以下の手順を省略し、Gutenberg 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

パッケージマネージャーをインストールしていない場合は、Node.js ダウンロードページ を参照してインストーラーとバイナリーを入手してください。

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

node パッケージマネージャー (npm)

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 コマンド 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"
}

wp-scripts ビルドのセットアップ

@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: 'layout',
    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']
);

完全なサンプルについては gutenberg-examples リポジトリー内の ESNext ブロック を参照してください。

まとめ

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

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

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

最終更新日: