インストール
モジュールをインストールします
npm install @wordpress/dependency-extraction-webpack-plugin --save-dev
注意: このパッケージは、長期サポートステータスのあるNode.jsバージョンを必要とします(アクティブLTSまたはメンテナンスLTSリリースを確認)。また、webpack 5.0.0以上が必要です。古いバージョンとは互換性がありません。
使用法
Webpack
このプラグインは、他のwebpackプラグインと同様に使用します:
// webpack.config.js
const DependencyExtractionWebpackPlugin = require( '@wordpress/dependency-extraction-webpack-plugin' );
module.exports = {
// …snip
plugins: [ new DependencyExtractionWebpackPlugin() ],
};
注意: プラグインの複数インスタンスはサポートされておらず、予期しない結果を生じる可能性があります。@wordpress/scripts
から独自のDependencyExtractionWebpackPlugin
でwebpack構成を拡張する予定がある場合は、プラグインのデフォルトインスタンスを削除してください:
const defaultConfig = require( '@wordpress/scripts/config/webpack.config' );
const webpackConfig = {
...defaultConfig,
plugins: [
...defaultConfig.plugins.filter(
( plugin ) =>
plugin.constructor.name !== 'DependencyExtractionWebpackPlugin'
),
new DependencyExtractionWebpackPlugin( {
injectPolyfill: true,
requestToExternal( request ) {
/* My externals */
},
} ),
],
};
スクリプトとの動作
webpackバンドルの各エントリポイントには、エンキューすべきWordPressスクリプト依存関係を宣言するアセットファイルが含まれます。このファイルには、ファイルコンテンツに基づいて計算されたユニークなバージョンハッシュも含まれています。
例えば:
// Source file entrypoint.js
import { Component } from 'react';
// Webpack will produce the output output/entrypoint.js
/* bundled JavaScript output */
// Webpack will also produce output/entrypoint.asset.php declaring script dependencies
<?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のドキュメントを参照してください。
const webpackConfig = {
...defaultConfig,
// These lines are necessary to enable module compilation at time-of-writing:
output: { module: true },
experiments: { outputModule: true },
plugins: [
...defaultConfig.plugins.filter(
( plugin ) =>
plugin.constructor.name !== 'DependencyExtractionWebpackPlugin'
),
new DependencyExtractionWebpackPlugin( {
// With modules, use `requestToExternalModule`:
requestToExternalModule( request ) {
if ( request === 'my-registered-module' ) {
return request;
}
},
} ),
],
};
webpackバンドルの各エントリポイントには、エンキューすべきWordPressスクリプトモジュール依存関係を宣言するアセットファイルが含まれます。このファイルには、ファイルコンテンツに基づいて計算されたユニークなバージョンハッシュも含まれています。
例えば:
// Source file entrypoint.js
import { store, getContext } from '@wordpress/interactivity';
// Webpack will produce the output output/entrypoint.js
/* bundled JavaScript output */
// Webpack will also produce output/entrypoint.asset.php declaring script dependencies
<?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
モジュールが隠され、依存関係リストに含まれなくなります。
オプション
動作をカスタマイズするために、コンストラクタにオブジェクトを渡すことができます。例えば:
module.exports = {
plugins: [
new DependencyExtractionWebpackPlugin( { injectPolyfill: true } ),
],
};
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
は、デフォルトの外部処理よりも優先されます。未処理のリクエストは、useDefaults
がfalse
に設定されていない限り、デフォルトによって処理されます。
/**
* Externalize 'my-module'
*
* @param {string} request Requested module
*
* @return {(string|undefined)} Script global
*/
function requestToExternal( request ) {
// Handle imports like `import myModule from 'my-module'`
if ( request === 'my-module' ) {
// Expect to find `my-module` as myModule in the global scope:
return 'myModule';
}
}
module.exports = {
plugins: [ new DependencyExtractionWebpackPlugin( { requestToExternal } ) ],
};
requestToExternalModule
注意: このオプションはスクリプトモジュールでのみ利用可能です。スクリプトの使用については、requestToExternal
を参照してください。
- タイプ: 関数
構成で提供された`````requestToExternalModule`````は、デフォルトの外部処理よりも優先されます。未処理のリクエストは、`````useDefaults`````が`````false`````に設定されていない限り、デフォルトによって処理されます。
``````bash
/**
* Externalize 'my-module'
*
* @param {string} request Requested script module
*
* @return {(string|boolean|undefined)} Script module ID
*/
function requestToExternalModule( request ) {
// Handle imports like `import myModule from 'my-module'`
if ( request === 'my-module' ) {
// Import should be of the form `import { something } from "myModule";` in the final bundle.
return 'myModule';
}
// If the script module ID in source is the same as the external script module, `true` can be returned.
return request === 'external-module-id-no-change-required';
}
module.exports = {
plugins: [
new DependencyExtractionWebpackPlugin( { requestToExternalModule } ),
],
};
`
requestToHandle
注意: このオプションはスクリプトモジュールでは利用できません。対応するモジュール構成はありません。
- タイプ: 関数
プラグインによって処理されるすべての外部モジュールは、WordPressスクリプト依存関係であると見なされ、依存関係リストに追加されます。requestToHandle
は、依存関係リストに含まれるスクリプトハンドルをカスタマイズすることを可能にします。
文字列が返されない場合、スクリプトハンドルはリクエストと同じであると見なされます。
構成で提供されたrequestToHandle
は、デフォルトよりも優先されます。未処理のリクエストは、useDefaults
がfalse
に設定されていない限り、デフォルトによって処理されます。
/**
* Map 'my-module' request to 'my-module-script-handle'
*
* @param {string} request Requested module
*
* @return {(string|undefined)} Script global
*/
function requestToHandle( request ) {
// Handle imports like `import myModule from 'my-module'`
if ( request === 'my-module' ) {
// `my-module` depends on the script with the 'my-module-script-handle' handle.
return 'my-module-script-handle';
}
}
module.exports = {
plugins: [ new DependencyExtractionWebpackPlugin( { requestToHandle } ) ],
};
requestToExternalとrequestToHandle
関数requestToExternal
とrequestToHandle
は、このモジュールが任意のモジュールを処理できるようにします。
`````requestToHandle`````は、同じモジュールリクエストをスクリプトハンドルにマッピングし、`````entrypoint.asset.php`````ファイルに含まれる文字列です。
<a name="wordpress"></a>
### WordPress
スクリプトを通常通りエンキューし、スクリプト依存関係を動的に読み取ります:
``````bash
$script_path = 'path/to/script.js';
$script_asset_path = 'path/to/script.asset.php';
$script_asset = file_exists( $script_asset_path )
? require( $script_asset_path )
: array( 'dependencies' => array(), 'version' => filemtime( $script_path ) );
$script_url = plugins_url( $script_path, __FILE__ );
wp_enqueue_script( 'script', $script_url, $script_asset['dependencies'], $script_asset['version'] );
`
またはモジュールを使用して(スクリプトモジュールAPIはWordPress > 6.5でのみ利用可能です):
$module_path = 'path/to/module.js';
$module_asset_path = 'path/to/module.asset.php';
$module_asset = file_exists( $module_asset_path )
? require( $module_asset_path )
: array( 'dependencies' => array(), 'version' => filemtime( $module_path ) );
$module_url = plugins_url( $module_path, __FILE__ );
wp_register_script_module( 'my-module', $module_url, $module_asset['dependencies'], $module_asset['version'] );
wp_enqueue_script_module( 'my-module' );
このパッケージへの貢献
これはGutenbergプロジェクトの一部である個別のパッケージです。このプロジェクトはモノレポとして整理されています。特定の目的を持つ複数の自己完結型ソフトウェアパッケージで構成されています。このモノレポ内のパッケージは、[https://www.npmjs.com/]に公開され、[https://make.wordpress.org/core/]や他のソフトウェアプロジェクトで使用されています。
このパッケージやGutenberg全体への貢献について詳しく知りたい場合は、プロジェクトの主要な貢献者ガイドをお読みください。