エンタープライズアプリケーション向けデータグリッドとチャート
webpack
webpackとのパートナーシップを誇りに思います

v4 から v5 へ

このガイドは、webpackを直接使用する場合のwebpack 5への移行を支援することを目的としています。より高レベルのツールを使用してwebpackを実行している場合は、移行手順についてはそのツールを参照してください。

準備

Webpack 5は少なくともNode.js 10.13.0（LTS）が必要です。古いバージョンを使用している場合は、Node.jsをアップグレードしてください。

webpack 4と、そのプラグイン/ローダーのアップグレード

  1. webpack 4を最新バージョンにアップグレードします。

    • webpack >= 4を使用している場合、最新のwebpack 4バージョンへのアップグレードは、追加のガイダンスを必要としません。

    • 4より前のバージョンのwebpackを使用している場合は、webpack 4移行ガイドを参照してください。

  2. webpack-cliを最新バージョンにアップグレードします（使用する場合）。

  3. 使用しているすべてのプラグインとローダーを最新バージョンにアップグレードします。

    一部のプラグインとローダーでは、webpack 5との互換性のためにベータ版を使用する必要がある場合があります。アップグレードする際には、各プラグイン/ローダーのリリースノートをよく読んでください。最新バージョンはwebpack 5のみをサポートしており、v4では失敗する可能性があります。そのような場合は、webpack 4をサポートする最新バージョンに更新することをお勧めします。

ビルドにエラーや警告がないことを確認してください

webpack、webpack-cli、プラグイン、ローダーのアップグレードされたバージョンによって、新しいエラーや警告が発生することがあります。ビルド中に非推奨の警告に注意してください。

非推奨の警告のスタックトレースを取得するために、このようにwebpackを呼び出すことができます。どのプラグインとローダーが原因なのかを突き止められます。

node --trace-deprecation node_modules/webpack/bin/webpack.js

webpack 5はすべての非推奨機能を削除するため、続行するには、ビルド中にwebpackの非推奨警告がないことを確認してください。

modeを使用してください

対応するデフォルトが設定されるように、modeをproductionまたはdevelopmentに設定します。

古いオプションを更新する

次のオプションを新しいバージョンに更新します（使用している場合）。

  • optimization.hashedModuleIds: true → optimization.moduleIds: 'hashed'
  • optimization.namedChunks: true → optimization.chunkIds: 'named'
  • optimization.namedModules: true → optimization.moduleIds: 'named'
  • NamedModulesPlugin → optimization.moduleIds: 'named'
  • NamedChunksPlugin → optimization.chunkIds: 'named'
  • HashedModuleIdsPlugin → optimization.moduleIds: 'hashed'
  • optimization.noEmitOnErrors: false → optimization.emitOnErrors: true
  • optimization.occurrenceOrder: true → optimization: { chunkIds: 'total-size', moduleIds: 'size' }
  • optimization.splitChunks.cacheGroups.vendors → optimization.splitChunks.cacheGroups.defaultVendors
  • optimization.splitChunks.cacheGroups.test(module, chunks) → optimization.splitChunks.cacheGroups.test(module, { chunkGraph, moduleGraph })
  • Compilation.entries → Compilation.entryDependencies
  • serve → DevServerに置き換えられました。
  • Rule.query（v3以降非推奨）→ Rule.options/UseEntry.options
  • Rule.loaders → Rule.use

webpack 5との互換性をテストする

webpack 4の設定で次のオプションを設定し、ビルドが正しく機能するかどうかを確認してみてください。

module.exports = {
  // ...
  node: {
    Buffer: false,
    process: false,
  },
};

webpack 5用に設定をアップグレードする際には、これらのオプションを削除する必要があります。

webpackを5にアップグレードする

それでは、webpackをバージョン5にアップグレードしましょう。

  • npm: npm install webpack@latest

  • Yarn: yarn add webpack@latest

「webpack 4と、そのプラグイン/ローダーのアップグレード」の手順で、一部のプラグイン/ローダーを最新バージョンにアップグレードできなかった場合は、ここでアップグレードしてください。

設定のクリーンアップ

  • webpackの設定からoptimization.moduleIdsとoptimization.chunkIdsを削除することを検討してください。デフォルトの方が優れている可能性があります。なぜなら、productionモードでは長期的なキャッシングを、developmentモードではデバッグをサポートしているからです。

  • webpackの設定で[hash]プレースホルダーを使用している場合は、[contenthash]に変更することを検討してください。同じではありませんが、より効果的であることが証明されています。

  • YarnのPnPとpnp-webpack-pluginを使用している場合は、朗報です。今ではデフォルトでサポートされています。設定から削除する必要があります。

  • 正規表現を引数としてIgnorePluginを使用している場合、現在はoptionsオブジェクトを使用するようになりました。new IgnorePlugin({ resourceRegExp: /regExp/ })

  • node.fs: 'empty'のようなものを使用している場合は、resolve.fallback.fs: falseに置き換えてください。

  • Webpack Node.js APIでwatch: trueを使用している場合は、削除してください。呼び出すコンパイラメソッド（watch()の場合はtrue、run()の場合はfalse）によって示されるため、設定する必要はありません。

  • raw-loader、url-loader、またはfile-loaderを使用してアセットを読み込むためのrulesを定義している場合、近いうちに非推奨となるため、代わりにAsset Modulesを使用してください。

  • targetを関数に設定している場合は、falseに更新し、その関数をpluginsオプション内で適用してください。以下の例を参照してください。

    // for webpack 4
{
    target: WebExtensionTarget(nodeConfig)
}

// for webpack 5
{
    target: false,
    plugins: [
        WebExtensionTarget(nodeConfig)
    ]
}

  • output.libraryまたはoutput.libraryTargetが定義されている場合、プロパティ名を変更します。（output.libraryTarget → output.library.type、output.library → output.library.name）。例

    // for webpack 4
{
    output: {
      library: 'MyLibrary',
      libraryTarget: 'commonjs2'
    }
}

// for webpack 5
{
    output: {
      library: {
        name: 'MyLibrary',
        type: 'commonjs2'
      }
    }
}

インポートを使用してWebAssemblyを使用していた場合は、次の2段階のプロセスに従ってください。

  • Webpack 4と同じ動作を実現するには、experiments.syncWebAssembly: trueを設定して非推奨の仕様を有効にします。
  • Webpack 5への移行が成功したら、experimentsの値をexperiments: { asyncWebAssembly: true }に変更して、WASM統合の最新仕様を使用してください。

optimization.splitChunksを見直してください。

  • デフォルト値またはoptimization.splitChunks: { chunks: 'all' }を使用することをお勧めします。
  • カスタム設定を使用する場合、name: falseを削除し、name: string | functionをidHint: string | functionに置き換えます。
  • optimization.splitChunks.cacheGroups: { default: false, vendors: false }を設定することで、デフォルトを無効にすることができました。これはお勧めしませんが、Webpack 5で同じ効果を得たい場合は、optimization.splitChunks.cacheGroups: { default: false, defaultVendors: false }を使用してください。

デフォルトの削除を検討してください。

  • entry: './src/index.js'を使用している場合：これはデフォルトなので省略できます。
  • output.path: path.resolve(__dirname, 'dist')を使用している場合：これはデフォルトなので省略できます。
  • output.filename: '[name].js'を使用している場合：これはデフォルトなので省略できます。

IE 11などの古いブラウザをサポートする必要がある場合

  • プロジェクトでbrowserslistを有効にしている場合、Webpack 5はbrowserslistの設定を再利用して、ランタイムコードに対してどのコードスタイルを出力するかを決定します。

    必ず

    1. targetをbrowserslistに設定するか、targetを削除してWebpackが自動的にbrowserslistを設定できるようにしてください。
    2. browserslist設定にIE 11を追加してください。

  • browserslistがない場合、WebpackのランタイムコードはES2015構文（例：アロー関数）を使用してより小さいバンドルを作成します。そのため、ES2015構文をサポートしていないブラウザ（IE11など）に対してES5構文を使用するには、target: ['web', 'es5']を設定する必要があります。

  • Node.jsの場合、ビルドにはサポートされているNode.jsバージョンがtargetオプションに含まれ、Webpackはサポートされている構文を自動的に判断します（例：target: 'node8.6'）。

コードのクリーンアップ

/* webpackChunkName: '...' */の使用

意図を理解してください。

  • ここのチャンク名は公開することを意図しています。
  • 開発時のみの名前ではありません。
  • Webpackは本番モードと開発モードの両方でファイル名にこれを使用します。
  • Webpack 5は、webpackChunkNameを使用しなくても、開発モードで自動的に便利なファイル名を割り当てます。

JSONモジュールからの名前付きエクスポートの使用

これは新しい仕様ではサポートされておらず、警告が表示されます。代わりに

import { version } from './package.json';
console.log(version);

使用してください。

import pkg from './package.json';
console.log(pkg.version);

ビルドコードのクリーンアップ

  • const compiler = webpack(...);を使用する場合は、使用後にコンパイラを閉じます：compiler.close(callback);。
    • これは、自動的に閉じられるwebpack(..., callback)形式には適用されません。
    • ユーザーがプロセスを終了するまで監視モードでWebpackを使用する場合は、これはオプションです。監視モードのアイドルフェーズはこの種の作業に使用されます。

単一のビルドを実行し、アドバイスに従ってください

ビルドエラー/警告を注意深く読んでください。対応するアドバイスがない場合は、issueを作成してください。解決できるよう努めます。

少なくともレベル3または4を解決するまで、次の手順を繰り返してください。

  • レベル1：**スキーマ検証が失敗する**。

    設定オプションが変更されました。BREAKING CHANGE:のメモ、または代わりに使用するオプションのヒントを含む検証エラーが表示されるはずです。

  • レベル2：**Webpackがエラーで終了する**。

    エラーメッセージには、変更が必要なことが記載されています。

  • レベル3：**ビルドエラー**。

    エラーメッセージには、BREAKING CHANGE:のメモが含まれています。

  • レベル4：**ビルド警告**。

    警告メッセージには、改善できる点が記載されています。

  • レベル5：**ランタイムエラー**。

    これは困難です。問題を見つけるためにデバッグする必要があるでしょう。一般的なアドバイスはここでは難しいです。しかし、ランタイムエラーに関するいくつかの一般的なアドバイスを以下に示します。

    • processが定義されていません。
      • Webpack 5には、このNode.js変数のポリフィルが含まれなくなりました。フロントエンドコードでは使用しないでください。
      • ブラウザでの使用をサポートしたいですか？環境に応じて異なるコードを使用するには、exportsまたはimportsのpackage.jsonフィールドを使用してください。
        • また、古いバンドラをサポートするにはbrowserフィールドを使用してください。
        • 代替案：typeof processチェックを使用してコードブロックをラップします。これにより、バンドルサイズに悪影響を与えることに注意してください。
      • process.env.VARIABLEを使用して環境変数を使用したいですか？これらの変数を設定するには、DefinePluginまたはEnvironmentPluginを使用する必要があります。
        • 代わりにVARIABLEを使用することを検討し、typeof VARIABLE !== 'undefined'も確認してください。process.envはNode.js固有のものであり、フロントエンドコードでは避けるべきです。
    • autoを含むURLを指す404エラー。
      • すべてのエコシステムツールが、output.publicPath: "auto"による新しいデフォルトの自動publicPathに対応しているわけではありません。
        • 代わりに静的なoutput.publicPath: ""を使用してください。

  • レベル6：**非推奨警告**。

    多くの非推奨警告が表示される可能性があります。これは直接的な問題ではありません。プラグインはコアの変更に対応するのに時間がかかります。これらの非推奨事項をプラグインに報告してください。これらの非推奨事項は警告のみであり、小さな欠点（パフォーマンスの低下など）しかない場合でも、ビルドは機能します。

    • --no-deprecationフラグを使用してnodeを実行することで、非推奨警告を非表示にすることができます（例：node --no-deprecation node_modules/webpack/bin/webpack.js）。これは一時的な回避策としてのみ使用する必要があります。
    • プラグインとローダーの貢献者は、非推奨メッセージのアドバイスに従ってコードを改善できます。

  • レベル7：**パフォーマンスの問題**。

    通常、Webpack 5ではパフォーマンスが向上しますが、パフォーマンスが悪化するケースもあります。

    そして、状況を改善するためにできることがあります。

    • 時間がどこに使われているかをプロファイルします。
      • --profile --progressは、単純なパフォーマンスプロファイルを現在表示します。
      • node --inspect-brk node_modules/webpack/bin/webpack.js + chrome://inspect / edge://inspect（プロファイラタブを参照）。
        • これらのプロファイルをファイルに保存して、issueで提供できます。
        • 場合によっては、より良いスタックトレースを得るために--no-turbo-inliningフラグを使用してみてください。
    • 増分ビルドでのモジュールをビルドする時間は、Webpack 4のように安全でないキャッシングに戻すことで改善できます。
      • module.unsafeCache: true
      • ただし、これにより、コードベースへの一部の変更を処理する能力に影響を与える可能性があります。
    • 完全ビルド
      • 非推奨機能の後方互換性レイヤーは、通常、新しい機能と比較してパフォーマンスが劣ります。
      • 多くの警告を作成すると、無視された場合でもビルドのパフォーマンスに影響を与える可能性があります。
      • ソースマップは高価です。ドキュメントのdevtoolオプションを確認して、さまざまなオプションの比較を参照してください。
      • ウイルス対策ソフトがファイルシステムアクセスのパフォーマンスに影響を与える可能性があります。
      • 永続的なキャッシングは、反復的な完全ビルドを改善するのに役立ちます。
      • Module Federationを使用すると、アプリケーションを複数の小さなビルドに分割できます。

すべて動作しますか？

Webpack 5への移行に成功したことをツイートしてください。ツイートする

動作しませんか？

issueを作成して、移行中に発生した問題について教えてください。

このガイドに何か不足していますか？

プルリクエストを開いて、このガイドを使用する次のユーザーを支援してください。

内部の変更

タイプを追加すること、コードをリファクタリングすること、メソッド名を変更することなど、Webpack内部への変更は、興味のある人のためにここに記載されています。しかし、これらは一般的なユースケースの移行の一部として意図されていません。

  • Module.nameForCondition、Module.updateCacheModule、およびModule.chunkConditionは、もはやオプションではありません。

ローダーのgetOptionsメソッド

Webpack 5には、ローダーコンテキストで使用できる組み込みのthis.getOptionsメソッドが付属しています。これは、以前は優先されていたschema-utilsからgetOptionsメソッドを使用していたローダーにとって破壊的変更です。

  • this.getOptionsはWebpack 5から利用可能です。
  • JSON5の代わりに、クエリ文字列としてJSONをサポートします。?{arg:true} → ?{"arg":true}。JSON5の使用は、それぞれのローダーのドキュメントでJSONに賛成して非推奨と見なされ、文書化されるべきです。
  • loader-utilsは、クエリ文字列を解析するための特定の動作を持っています（true、false、nullはstringとしてではなく、プリミティブ値として解析されます）。これは、ネイティブのquerystring解析（Node.jsに付属）を使用する新しい組み込みthis.getOptionsメソッドではもう当てはまりません。this.getOptionsメソッドを使用してオプションを取得した後、ローダーのコードでこれらのケースのカスタム動作を追加することはまだ可能です。
  • 新しいthis.getOptionsメソッドではスキーマ引数はオプションですが、ローダーのオプションにスキーマ検証を追加することを強くお勧めします。スキーマのtitleフィールドを使用して、検証エラーメッセージをカスタマイズできます。たとえば、"title": "My Loader ooooptions"は、次のようにエラーを表示します。Invalid ooooptions object. My Loader has been initialised using an ooooptions object that does not match the API schema. - ooooptions.foo.bar.baz should be a string.
このページを編集·このページを印刷
« 前へ
移行
次へ »
v3 から v4 へ

10 貢献者

sokrasalemhilalkeichingerEugeneHlushkoMattGoldwaterrramaachenxsanjamesgeorge007getsnoopyyevhen-logosha