インストール

モジュールをインストールします

  1. npm install @wordpress/dependency-extraction-webpack-plugin --save-dev

注意: このパッケージは、長期サポートステータスのあるNode.jsバージョンを必要とします(アクティブLTSまたはメンテナンスLTSリリースを確認)。また、webpack 5.0.0以上が必要です。古いバージョンとは互換性がありません。

使用法

Webpack

このプラグインは、他のwebpackプラグインと同様に使用します:

  1. // webpack.config.js
  2. const DependencyExtractionWebpackPlugin = require( '@wordpress/dependency-extraction-webpack-plugin' );
  3. module.exports = {
  4. // snip
  5. plugins: [ new DependencyExtractionWebpackPlugin() ],
  6. };

注意: プラグインの複数インスタンスはサポートされておらず、予期しない結果を生じる可能性があります。@wordpress/scriptsから独自のDependencyExtractionWebpackPluginでwebpack構成を拡張する予定がある場合は、プラグインのデフォルトインスタンスを削除してください:

  1. const defaultConfig = require( '@wordpress/scripts/config/webpack.config' );
  2. const webpackConfig = {
  3. ...defaultConfig,
  4. plugins: [
  5. ...defaultConfig.plugins.filter(
  6. ( plugin ) =>
  7. plugin.constructor.name !== 'DependencyExtractionWebpackPlugin'
  8. ),
  9. new DependencyExtractionWebpackPlugin( {
  10. injectPolyfill: true,
  11. requestToExternal( request ) {
  12. /* My externals */
  13. },
  14. } ),
  15. ],
  16. };

スクリプトとの動作

webpackバンドルの各エントリポイントには、エンキューすべきWordPressスクリプト依存関係を宣言するアセットファイルが含まれます。このファイルには、ファイルコンテンツに基づいて計算されたユニークなバージョンハッシュも含まれています。

例えば:

  1. // Source file entrypoint.js
  2. import { Component } from 'react';
  3. // Webpack will produce the output output/entrypoint.js
  4. /* bundled JavaScript output */
  5. // Webpack will also produce output/entrypoint.asset.php declaring script dependencies
  6. <?php return array('dependencies' => array('react'), 'version' => 'dd4c2dc50d046ed9d4c063a7ca95702f');

デフォルトでは、次のモジュールリクエストが処理されます:

リクエスト グローバル スクリプトハンドル
@babel/runtime/regenerator regeneratorRuntime wp-polyfill
@wordpress/* wp['*'] wp-*
jquery jQuery jquery
lodash-es lodash lodash
lodash lodash lodash
moment moment moment
react-dom ReactDOM react-dom
react React react

注意: このプラグインは、webpack externalsによって提供される機能と重複しています。このプラグインは、バンドルコンパイルからスクリプトハンドルを抽出することを目的としており、スクリプト依存関係のリストを手動で維持する必要がありません。スクリプト依存関係のリストを抽出する必要がない場合は、externalsオプションを直接使用してください。

このプラグインはexternalsと互換性がありますが、競合する可能性があります。例えば、webpack構成に{ externals: { '@wordpress/blob': 'wp.blob' } }を追加すると、プラグインから@wordpress/blobモジュールが隠され、依存関係リストに含まれなくなります。

スクリプトモジュールとの動作

警告: スクリプトモジュールのサポートは、現時点では実験的と見なされています。

このセクションでは、ECMAScriptモジュールをバンドルし、WordPress Script Modules APIで使用するのに適したアセットファイルを生成するためのこのパッケージの動作について説明します。

このプラグインのいくつかのオプションが変更され、webpackはスクリプトモジュールを出力するための構成を必要とします。最新の詳細については、

webpackのドキュメントを参照してください。

  1. const webpackConfig = {
  2. ...defaultConfig,
  3. // These lines are necessary to enable module compilation at time-of-writing:
  4. output: { module: true },
  5. experiments: { outputModule: true },
  6. plugins: [
  7. ...defaultConfig.plugins.filter(
  8. ( plugin ) =>
  9. plugin.constructor.name !== 'DependencyExtractionWebpackPlugin'
  10. ),
  11. new DependencyExtractionWebpackPlugin( {
  12. // With modules, use `requestToExternalModule`:
  13. requestToExternalModule( request ) {
  14. if ( request === 'my-registered-module' ) {
  15. return request;
  16. }
  17. },
  18. } ),
  19. ],
  20. };

webpackバンドルの各エントリポイントには、エンキューすべきWordPressスクリプトモジュール依存関係を宣言するアセットファイルが含まれます。このファイルには、ファイルコンテンツに基づいて計算されたユニークなバージョンハッシュも含まれています。

例えば:

  1. // Source file entrypoint.js
  2. import { store, getContext } from '@wordpress/interactivity';
  3. // Webpack will produce the output output/entrypoint.js
  4. /* bundled JavaScript output */
  5. // Webpack will also produce output/entrypoint.asset.php declaring script dependencies
  6. <?php return array('dependencies' => array('@wordpress/interactivity'), 'version' => 'dd4c2dc50d046ed9d4c063a7ca95702f');

デフォルトでは、次のスクリプトモジュールリクエストが処理されます:

リクエスト
@wordpress/interactivity

(@wordpress/interactivityは現在利用可能な唯一のWordPressスクリプトモジュールです。)

注意: このプラグインは、webpack externalsによって提供される機能と重複しています。このプラグインは、バンドルコンパイルからスクリプトモジュール識別子を抽出することを目的としており、スクリプトモジュール依存関係のリストを手動で維持する必要がありません。スクリプトモジュール依存関係のリストを抽出する必要がない場合は、externalsオプションを直接使用してください。

このプラグインはexternalsと互換性がありますが、競合する可能性があります。例えば、webpack構成に{ externals: { '@wordpress/blob': 'wp.blob' } }を追加すると、プラグインから@wordpress/blobモジュールが隠され、依存関係リストに含まれなくなります。

オプション

動作をカスタマイズするために、コンストラクタにオブジェクトを渡すことができます。例えば:

  1. module.exports = {
  2. plugins: [
  3. new DependencyExtractionWebpackPlugin( { injectPolyfill: true } ),
  4. ],
  5. };
outputFormat
  • タイプ: 文字列
  • デフォルト: php

生成されたアセットファイルの出力形式。利用可能なオプションは2つあります: ‘php’または’json’。

outputFilename
  • タイプ: 文字列 | 関数
  • デフォルト: null

生成されたアセットファイルのファイル名。Webpackのoutput.filenameオプションと同じ値を受け入れます。

combineAssets
  • タイプ: ブール値
  • デフォルト: false

デフォルトでは、各エントリポイントに対して1つのアセットファイルが作成されます。このフラグがtrueに設定されると、アセットに関するすべての情報が出力ディレクトリに生成される単一のassets.(json|php)ファイルに結合されます。

combinedOutputFile
  • タイプ: 文字列
  • デフォルト: null

このオプションは、combineAssetsオプションが有効な場合にのみ有用です。生成された単一アセットファイルのカスタム出力ファイルを提供できます。出力ディレクトリに対して相対的なパスを提供することが可能です。

useDefaults
  • タイプ: ブール値
  • デフォルト: true

useDefaults: falseを渡してデフォルトのリクエスト処理を無効にします。

injectPolyfill
  • タイプ: ブール値
  • デフォルト: false

wp-polyfillを各エントリポイントの依存関係リストに含めるよう強制します。これは、各エントリポイントにimport '@wordpress/polyfill';を追加するのと同じです。

注意: このオプションはスクリプトモジュールでは利用できません。

externalizedReport
  • タイプ: ブール値 | 文字列
  • デフォルト: false

すべての外部依存関係をJSON形式の配列として報告します。これは、さらなる手動または自動検査に使用できます。

ファイル名を提供するか、trueに設定してデフォルトのexternalized-dependencies.jsonに報告します。

requestToExternal

注意: このオプションはスクリプトモジュールでは利用できません。モジュールの使用については、requestToExternalModuleを参照してください。

  • タイプ: 関数

requestToExternalはモジュール処理をカスタマイズすることを可能にします。この関数は、モジュールリクエスト文字列を受け入れ、使用するグローバル変数を表す文字列を返すことができます。文字列の配列を使用して、オブジェクトパスを介してグローバルにアクセスすることができます。例えば、wp.i18n[ 'wp', 'i18n' ]として表されることがあります。

構成で提供されたrequestToExternalは、デフォルトの外部処理よりも優先されます。未処理のリクエストは、useDefaultsfalseに設定されていない限り、デフォルトによって処理されます。

  1. /**
  2. * Externalize 'my-module'
  3. *
  4. * @param {string} request Requested module
  5. *
  6. * @return {(string|undefined)} Script global
  7. */
  8. function requestToExternal( request ) {
  9. // Handle imports like `import myModule from 'my-module'`
  10. if ( request === 'my-module' ) {
  11. // Expect to find `my-module` as myModule in the global scope:
  12. return 'myModule';
  13. }
  14. }
  15. module.exports = {
  16. plugins: [ new DependencyExtractionWebpackPlugin( { requestToExternal } ) ],
  17. };
requestToExternalModule

注意: このオプションはスクリプトモジュールでのみ利用可能です。スクリプトの使用については、requestToExternalを参照してください。

  • タイプ: 関数
  1. 構成で提供された`````requestToExternalModule`````は、デフォルトの外部処理よりも優先されます。未処理のリクエストは、`````useDefaults``````````false`````に設定されていない限り、デフォルトによって処理されます。
  2. ``````bash
  3. /**
  4. * Externalize 'my-module'
  5. *
  6. * @param {string} request Requested script module
  7. *
  8. * @return {(string|boolean|undefined)} Script module ID
  9. */
  10. function requestToExternalModule( request ) {
  11. // Handle imports like `import myModule from 'my-module'`
  12. if ( request === 'my-module' ) {
  13. // Import should be of the form `import { something } from "myModule";` in the final bundle.
  14. return 'myModule';
  15. }
  16. // If the script module ID in source is the same as the external script module, `true` can be returned.
  17. return request === 'external-module-id-no-change-required';
  18. }
  19. module.exports = {
  20. plugins: [
  21. new DependencyExtractionWebpackPlugin( { requestToExternalModule } ),
  22. ],
  23. };
  24. `
requestToHandle

注意: このオプションはスクリプトモジュールでは利用できません。対応するモジュール構成はありません。

  • タイプ: 関数

プラグインによって処理されるすべての外部モジュールは、WordPressスクリプト依存関係であると見なされ、依存関係リストに追加されます。requestToHandleは、依存関係リストに含まれるスクリプトハンドルをカスタマイズすることを可能にします。

文字列が返されない場合、スクリプトハンドルはリクエストと同じであると見なされます。

構成で提供されたrequestToHandleは、デフォルトよりも優先されます。未処理のリクエストは、useDefaultsfalseに設定されていない限り、デフォルトによって処理されます。

  1. /**
  2. * Map 'my-module' request to 'my-module-script-handle'
  3. *
  4. * @param {string} request Requested module
  5. *
  6. * @return {(string|undefined)} Script global
  7. */
  8. function requestToHandle( request ) {
  9. // Handle imports like `import myModule from 'my-module'`
  10. if ( request === 'my-module' ) {
  11. // `my-module` depends on the script with the 'my-module-script-handle' handle.
  12. return 'my-module-script-handle';
  13. }
  14. }
  15. module.exports = {
  16. plugins: [ new DependencyExtractionWebpackPlugin( { requestToHandle } ) ],
  17. };
requestToExternalとrequestToHandle

関数requestToExternalrequestToHandleは、このモジュールが任意のモジュールを処理できるようにします。

  1. `````requestToHandle`````は、同じモジュールリクエストをスクリプトハンドルにマッピングし、`````entrypoint.asset.php`````ファイルに含まれる文字列です。
  2. <a name="wordpress"></a>
  3. ### WordPress
  4. スクリプトを通常通りエンキューし、スクリプト依存関係を動的に読み取ります:
  5. ``````bash
  6. $script_path = 'path/to/script.js';
  7. $script_asset_path = 'path/to/script.asset.php';
  8. $script_asset = file_exists( $script_asset_path )
  9. ? require( $script_asset_path )
  10. : array( 'dependencies' => array(), 'version' => filemtime( $script_path ) );
  11. $script_url = plugins_url( $script_path, __FILE__ );
  12. wp_enqueue_script( 'script', $script_url, $script_asset['dependencies'], $script_asset['version'] );
  13. `

またはモジュールを使用して(スクリプトモジュールAPIはWordPress > 6.5でのみ利用可能です):

  1. $module_path = 'path/to/module.js';
  2. $module_asset_path = 'path/to/module.asset.php';
  3. $module_asset = file_exists( $module_asset_path )
  4. ? require( $module_asset_path )
  5. : array( 'dependencies' => array(), 'version' => filemtime( $module_path ) );
  6. $module_url = plugins_url( $module_path, __FILE__ );
  7. wp_register_script_module( 'my-module', $module_url, $module_asset['dependencies'], $module_asset['version'] );
  8. wp_enqueue_script_module( 'my-module' );

このパッケージへの貢献

これはGutenbergプロジェクトの一部である個別のパッケージです。このプロジェクトはモノレポとして整理されています。特定の目的を持つ複数の自己完結型ソフトウェアパッケージで構成されています。このモノレポ内のパッケージは、[https://www.npmjs.com/]に公開され、[https://make.wordpress.org/core/]や他のソフトウェアプロジェクトで使用されています。

このパッケージやGutenberg全体への貢献について詳しく知りたい場合は、プロジェクトの主要な貢献者ガイドをお読みください。