To v5 from v4

이 가이드는 webpack을 직접 사용할 때 webpack 5로 마이그레이션 하는 데 도움이 되는 것을 목표로 합니다. webpack을 실행하기 위해 더 높은 수준의 도구를 사용하는 경우 그 도구의 마이그레이션 지침을 참고하세요.

Preparations

Webpack 5는 Node.js 10.13.0 (LTS) 이상의 버전이 필요합니다. 따라서 여전히 이전 버전을 실행 중인 경우 Node.js를 업그레이드해야 합니다.

Upgrade webpack 4 and its plugins/loaders

1. webpack 4의 사용 가능한 최신 버전으로 업그레이드하세요.

   • webpack >= 4를 사용하는 경우 최신 webpack 4 버전으로 업그레이드할 때 추가 지침이 필요하지 않습니다.

   • webpack 버전 4 미만을 사용하는 경우 webpack 4 마이그레이션 가이드를 참고하세요.

2. webpack-cli 을 사용한다면 사용 가능한 최신 버전으로 업그레이드하세요.

3. 사용한 모든 플러그인과 로더를 사용 가능한 최신 버전으로 업그레이드하세요.

Codemods

webpack v4에서 v5로 업그레이드하는 것을 지원하기 위해 Codemod는 대부분의 마이그레이션 프로세스를 자동화하는 데 도움이 되는 오픈 소스 커뮤니티 codemod를 제공합니다.

이것들은 공식 webpack codemods가 아니며, 마이그레이션을 간소화하는 것을 목표로 하지만 모든 경우를 포괄하지는 않을 수 있습니다. 업그레이드를 완전히 완료하려면 추가 수동 단계를 수행해야 할 수도 있습니다.

webpack v5 마이그레이션 codemods를 실행합니다.

npx codemod@latest webpack/v5/migration-recipe

이렇게 하면 Codemod 레지스트리에서 다음 codemod가 실행됩니다.

• webpack/v5/set-target-to-false-and-update-plugins
• webpack/v5/migrate-library-target-to-library-object
• webpack/v5/json-imports-to-default-imports

이러한 각 codemod는 webpack v5 마이그레이션 가이드에 나열된 변경 사항을 자동화합니다. 사용 가능한 webpack v5 codemod의 전체 목록은 Codemod 레지스트리를 참고하세요.

Make sure your build has no errors or warnings

webpack, webpack-cli, 플러그인 그리고 로더를 업그레이드하면서 새로운 오류와 경고가 있을 수 있습니다. 빌드 중 사용 중단 경고를 주시하세요.

이 방법으로 webpack을 호출하여 어떤 플러그인과 로더가 책임이 있는지 파악하기 위해 사용 중단 경고에 대한 스택 추적을 얻을 수 있습니다.

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

webpack 5는 이제는 사용되지 않는 기능을 모두 제거하므로 계속 진행하려면 빌드 중에 webpack 사용 중단 경고가 없는지 확인하세요.

Make sure to use mode

mode를 production 또는 develop으로 설정하여 해당 기본값이 설정되어 있는지 확인하세요.

Update outdated options

다음 옵션을 새 버전으로 업데이트합니다. (사용되는 경우)

• 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를 위해 serve가 제거되었습니다.
• Rule.query (v3부터 사용 중단됨) → Rule.options/UseEntry.options
• Rule.loaders → Rule.use

Test webpack 5 compatibility

webpack 4 설정에서 다음 옵션을 설정하고 빌드가 여전히 올바르게 작동하는지 확인하세요.

export default {
  // ...
  node: {
    Buffer: false,
    process: false,
  },
};

webpack 5의 설정을 업그레이드할 때 이 옵션을 다시 제거해야 합니다.

Upgrade webpack to 5

이제 webpack을 버전 5로 업그레이드해 봅시다.

• npm: npm install webpack@latest

• Yarn: yarn add webpack@latest

• pnpm: pnpm add webpack@latest

만약 "Webpack 4 및 플러그인/로더 업그레이드" 단계에서 일부 플러그인/로더를 최신 버전으로 업그레이드하지 못했다면, 지금이라도 업그레이드하는 것을 잊지 마세요.

Clean up configuration

• webpack 설정에서 optimization.moduleIds 및 optimization.chunkIds 제거를 고려하세요. 기본값은 production 모드에서 장기 캐싱을 지원하고 development 모드에서 디버깅을 지원하기 때문에 더 나을 수 있습니다.

• webpack 설정에서 [hash] placeholder를 사용할 때 [contenthash]로 변경하는 것이 좋습니다. 동일하지는 않지만, 더 효과적인 것으로 입증되었습니다.

• Yarn의 PnP 및 pnp-webpack-plugin을 사용하는 경우 좋은 소식이 있습니다. 이제 기본적으로 지원됩니다. 설정에서 제거해야 합니다.

• 정규 표현식과 함께 IgnorePlugin을 인수로 사용하는 경우 이제 options object를 사용합니다. 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를 사용하여 애셋들을 load 하기 위해 정의된 rules가 있는 경우 가까운 장래에 사용되지 않을 것이므로 Asset Modules 을 대신 사용하세요.

• target이 함수로 설정되어 있으면 false로 업데이트하고 plugins option 내에서 해당 함수를 적용하세요. 아래 예를 참고하세요.

  Copy

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

  Note: Codemod for this change:

  Copy

  npx codemod webpack/v5/set-target-to-false-and-update-plugins

  (여기에서 registry를 확인하세요.)

• output.library 또는 output.libraryTarget이 정의된 경우 속성 이름을 변경합니다 (output.libraryTarget -> output.library.type, output.library -> output.library.name). 예를 들면 다음과 같습니다.

  Copy

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

  Note: Codemod for this change:

  Copy

  npx codemod webpack/v5/migrate-library-target-to-library-object

  (여기에서 registry를 확인하세요.)

import를 통해 WebAssembly를 사용하는 경우 다음 두 단계 프로세스를 따라야 합니다.

• webpack 4에서와 동일한 동작을 얻으려면 experiments.syncWebAssembly: true를 설정하여 이제는 사용되지 않는 사양을 활성화합니다.
• webpack 5로 성공적으로 마이그레이션 한 후 WASM 통합을 위한 최신 사양을 사용하려면 experiments 값을 experiments: { asyncWebAssembly: true }으로 변경합니다.

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'는 생략할 수 있습니다. 이것이 기본값입니다.

Need to support an older browser like IE 11?

• 프로젝트에 대해 browserslist를 활성화한 경우 webpack 5는 browserslist 설정을 재사용하여 런타임 코드에 대해 내보낼 코드 스타일을 결정합니다.

  확실히 할 것들.

  1. target을 browserslist으로 설정하거나 webpack이 자동으로 browserslist을 설정하도록 target을 제거합니다.
  2. IE 11을 browserslist 설정에 추가합니다.

• browserslist가 없으면 webpack의 런타임 코드는 ES2015 구문(예: 화살표 함수)을 사용하여 더 작은 번들을 빌드합니다. 따라서 ES2015 구문을 지원하지 않는 브라우저(예: IE11)에 ES5 구문을 사용하려면 target: ['web', 'es5']를 설정해야 합니다.

• Node.js의 경우 빌드에는 target option에 지원되는 Node.js 버전이 포함되며 webpack은 지원되는 구문을 자동으로 파악합니다. 예를 들어 target: 'node8.6'와 같이 사용합니다.

Cleanup the code

Using /* webpackChunkName: '...' */

사용 의도를 이해해야 합니다.

• 여기서 chunk's name은 public 용입니다.
• 오직 개발을 위한 이름이 아닙니다.
• Webpack은 이를 사용하여 production 및 development 모드에서 파일 이름을 지정합니다.
• Webpack 5는 webpackChunkName을 사용하지 않는 경우에도 development 모드에서 유용한 파일 이름을 자동으로 할당합니다.

Using named exports from JSON modules

이것은 새 사양에서 지원되지 않으며 경고가 표시됩니다.

import { version } from "./package.json";

console.log(version);

위 코드 대신 아래 코드를 사용하세요.

import pkg from "./package.json";

console.log(pkg.version);

Note: Codemod for this change:

Copy

npx codemod webpack/v5/json-imports-to-default-imports

(자세한 내용은 레지스트리 링크를 참고하세요.)

Cleanup the build code

• const compiler = webpack(...);을 사용할 때 컴파일러를 사용한 후에는 반드시 컴파일러를 닫아야 합니다. compiler.close(callback);.
  • 이것은 자동으로 닫히는 webpack(..., callback) 양식에는 적용되지 않습니다.
  • 사용자가 프로세스를 종료할 때까지 감시 모드에서 webpack을 사용하는 경우 선택 사항입니다. 이런 종류의 작업에는 감시 모드의 유휴 단계가 사용됩니다.

Run a single build and follow advice

빌드 오류/경고를 주의 깊게 읽어보세요. 해당하는 조언이 없는 경우 issue를 생성해 주시면 해결해 드리겠습니다.

최소한 레벨 3 또는 4를 풀 때까지 다음 단계를 반복합니다.

• Level 1: Schema validation fails.

  Configuration options가 변경되었습니다. BREAKING CHANGE: 메모 또는 대신 사용해야 하는 옵션에 대한 힌트에 유효성 검사 오류가 있어야 합니다.

• Level 2: Webpack exits with an error.

  오류 메시지는 변경해야 할 사항을 알려야 합니다.

• Level 3: Build Errors.

  오류 메시지에는 BREAKING CHANGE: 메모가 있어야 합니다.

• Level 4: Build Warnings.

  경고 메시지는 무엇을 개선할 수 있는지 알려야 합니다.

• Level 5: Runtime Errors.

  이것은 까다롭습니다. 문제를 찾으려면 디버그해야 할 것입니다. 일반적인 조언은 여기에서 어렵습니다. 그러나 런타임 오류와 관련하여 아래에 몇 가지 일반적인 조언을 나열합니다.

  • process는 정의되지 않았습니다.
    • webpack 5는 더 이 Node.js 변수에 대한 폴리필을 포함하지 않습니다. 프론트엔드 코드에서 사용하지 마세요.
    • 브라우저 사용을 지원하고 싶으신가요? 환경에 따라 다른 코드를 사용하려면 export 또는 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: ""를 사용하세요.
  • 정의되지 않은 속성을 읽을 수 없습니다('call' 읽기)
    • 런타임 중에 이 오류가 발생하면 ModuleConcatenationPluginê³¼ 관련이 있을 수 있습니다. 해당 플러그인을 사용 중인지 확인하고, 설정 파일의 plugins 섹션에 플러그인을 포함시켰으며 해당 설정이 production 모드로 설정되어 있는지 확인하세요. 플러그인 목록에서 해당 플러그인(예: new webpack.optimize.ModuleConcatenationPlugin())을 제거하세요. webpack 5에서는 해당 플러그인이 프로덕션 모드에서 기본적으로 활성화되어 있으며, 두 번 포함될 수 있습니다.
    • 일반적으로 각 플러그인을 비활성화하고 빌드를 테스트하는 것은 문제의 원인을 파악하는 좋은 방법입니다.
    • 자세한 내용은 이 문제를 참고하세요.

• Level 6: Deprecation Warnings.

  사용 중단 경고가 많을 수 있습니다. 이것은 직접적인 문제가 아닙니다. 플러그인은 핵심 변경 사항을 따라잡을 시간이 필요합니다. 이러한 지원 중단을 플러그인에 보고하세요. 이러한 지원 중단은 경고일 뿐이며 빌드는 여전히 약간의 단점(예: 성능 저하)으로만 작동합니다.

  • --no-deprecation 플래그와 함께 node를 실행하여 사용 중단 경고를 숨길 수 있습니다(예: node --no-deprecation node_modules/webpack/bin/webpack.js). 이것은 일시적인 해결 방법일 뿐입니다.
  • 플러그인 및 로더 기여자는 사용 중단 메시지의 조언을 따라 코드를 개선할 수 있습니다.

• Level 7: Performance issues.

  일반적으로 webpack 5에서는 성능이 향상되지만, 성능이 나빠지는 경우도 있습니다.

  그리고 상황을 개선하기 위해 다음과 같이 할 수 있습니다.

  • 시간이 어디에서 소요되었는지 설명합니다.
    • --profile --progress는 이제 간단한 성능 프로필을 표시합니다.
    • node --inspect-brk node_modules/webpack/bin/webpack.js + chrome://inspect / edge://inspect (프로파일러 탭 참고).
      • 이러한 프로필을 파일에 저장하고 이슈에 제공할 수 있습니다.
      • 어떤 경우에는 더 나은 스택 추적을 위해 --no-turbo-inlining 플래그를 사용해 보세요.
  • 증분 빌드에서 모듈을 빌드하는 시간은 webpack 4에서와 같이 안전하지 않은 캐싱으로 되돌리면 개선될 수 있습니다.
    • module.unsafeCache: true
    • 그러나 이것은 코드 기반의 일부 변경 사항을 처리하는 기능에 영향을 미칠 수 있습니다.
  • Full build
    • 이제는 사용되지 않는 기능에 대한 이전 버전과의 호환성 계층은 일반적으로 새 기능에 비해 성능이 저하됩니다.
    • 경고를 많이 생성하면 무시하더라도 빌드 성능에 영향을 줄 수 있습니다.
    • Source Maps는 비용이 많이 듭니다. 문서에서 devtool 옵션을 확인하여 다양한 옵션을 비교하세요.
    • 바이러스 백신 보호는 파일 시스템 액세스 성능에 영향을 줄 수 있습니다.
    • 영구 캐싱은 반복적인 전체 빌드를 개선하는 데 도움이 될 수 있습니다.
    • 모듈 연합을 사용하면 애플리케이션을 여러 개의 작은 빌드로 분할할 수 있습니다.

Everything works?

webpack 5로 성공적으로 마이그레이션 했다고 트윗해주세요. Tweet it

It is not working?

issue를 만들고 마이그레이션 중에 발생한 문제에 대해 알려주세요.

Something missing in this guide?

Pull Request를 만들어 이 가이드를 사용하는 다음 사람을 도와주세요.

Changes to internals

유형 추가, 코드 리팩토링 및 메서드 이름 변경과 같은 webpack 내부의 변경 사항은 관심 있는 모든 사람을 위해 여기에 나열됩니다. 그러나 일반적인 사용 사례 마이그레이션의 일부로 의도한 것은 아닙니다.

• Module.nameForCondition, Module.updateCacheModule 및 Module.chunkCondition은 더 이상 선택 사항이 아닙니다.

getOptions method for Loaders

Webpack 5는 로더 컨텍스트에서 사용할 수 있는 내장 this.getOptions 메서드와 함께 제공됩니다. 이것은 이전에 선호하는 schema-utils에서 getOptions 메소드를 사용했던 로더에 대한 주요 변경 사항입니다.

• this.getOptions는 webpack 5부터 사용할 수 있습니다.
• JSON5 대신 쿼리 문자열로 JSON을 지원합니다. ?{arg:true} → ?{"arg":true}. JSON5를 사용하는 것은 해당 로더의 문서에서 이제는 사용되지 않는 것으로 간주하고 문서화되어야 합니다.
• loader-utils에는 쿼리 문자열 구문 분석을 위한 특정 동작이 있습니다(true, false 및 null은 string로 구문 분석되지 않고 원시 값으로 구문 분석됨). 기본 querystring 구문 분석(Node.js와 함께 제공됨) 을 사용하는 새로운 내장 this.getOptions 메서드의 경우에는 그렇지 않습니다. this.getOptions 메소드를 사용하여 옵션을 가져온 후 로더의 코드에서 이러한 경우에 대한 사용자 정의 동작을 추가하는 것은 여전히 가능합니다.
• 새로운 this.getOptions 메서드에 대해 스키마 인수는 선택 사항이지만 로더 옵션에 대한 스키마 유효성 검사를 추가하는 것이 좋습니다. 스키마의 title 필드는 유효성 검사 오류 메시지를 사용자 정의하는 데 사용할 수 있습니다. 예를 들면 "title": "My Loader ooptions"는 다음과 같은 방식으로 오류를 표시합니다. 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.