Performance

이 옵션을 사용하면 webpack이 정해진 파일 제한을 초과하는 애셋과 엔트리 포인트에 대해 알릴 방법을 제어 할 수 있습니다. 이 기능은 webpack 성능 버짓의 아이디어에서 영감을 받았습니다.

webpack 5.110.0부터 이 옵션은 애셋 크기뿐 아니라 번들과 설정의 구조를 살펴보는 선택적 검사도 제공합니다. 중복 패키지, 사용되지 않는 모듈, 한 번도 일치하지 않는 규칙, 아무것도 지연하지 않는 import() 호출 등을 검사합니다. 모든 검사의 기본값은 false이며, 전체를 한 번에 활성화하려면 performance.all을 참고하세요.

`performance`

object

성능 힌트가 표시되는 방법을 설정합니다. 예를 들어 애셋이 250kb를 초과하면, webpack이 이를 알리는 경고를 표시합니다.

Available checks

크기 제한(maxAssetSize 및 maxEntrypointSize) 외에도 webpack은 다음 검사를 제공합니다. 검사 대상을 기준으로 분류했습니다.

영역	검사
중복으로 전달되는 항목	`duplicatePackages`, `duplicateModules`
사용되지 않지만 전달되는 항목	`unusedModules`, `unusedAssets`, `missingSideEffects`, `dynamicExports`, `scopeHoistingBailouts`, `legacyJavascript`
청크 로드 방식	`asyncChunkWaterfalls`, `redundantDynamicImports`, `tinyChunks`, `unsplitVendors`, `splitChunksCapped`, `conflictingResourceHints`
청크 용량을 차지하는 항목	`largeModules`, `inlinedAssets`, `sourceMaps`, `broadContexts`
코드 위험 요소	`evalUsage`, `pureAnnotations`, `topLevelThis`, `mixedExports`
설정	`unusedConfig`, `osDependentRules`
빌드 자체	`cacheEffectiveness`, `hotspots`, `circularDependencies`

대부분은 performance.hints를 통해 보고되므로 hints가 false이면 출력되지 않습니다.

아무것도 일치하지 않는 규칙이나 철자가 틀린 external은 크기 문제가 아니라 설정 오류이므로 설정 검사는 hints의 영향을 받지 않습니다. unusedConfig, osDependentRules, conflictingResourceHints는 해당 검사가 활성화되어 있으면 항상 경고로 보고됩니다.

Renamed checks

5.110.0에서 도입된 검사 7개는 5.111.0에서 더 적은 수의 옵션으로 통합되었으며 기존 이름은 제거되었습니다. webpack은 알 수 없는 설정 속성을 허용하지 않으므로, 기존 이름을 계속 사용하는 설정은 무시되지 않고 Invalid configuration object 오류와 함께 유효성 검사에 실패합니다. 다음과 같이 이름을 변경하세요.

5.111.0에서 제거됨	대신 사용할 옵션
`performance.unusedAliases`	`performance.unusedConfig`
`performance.unusedDefines`	`performance.unusedConfig`
`performance.unusedExternals`	`performance.unusedConfig`
`performance.unusedRules`	`performance.unusedConfig`
`performance.unusedReexports`	`performance.unusedModules`
`performance.embeddedSourceMaps`	`performance.sourceMaps`
`performance.entrypointOverlap`	`performance.duplicateModules`

이제 네 가지 설정 검사가 하나의 옵션을 공유하므로 unusedConfig로 전환하면 기존 이름이 가리키던 검사 하나뿐 아니라 모두 활성화됩니다. 아직 확인하고 싶지 않은 항목까지 보고된다면 performance.hints를 false로 설정하세요.

performance.all

5.110.0+

boolean = false

개별적으로 설정하지 않은 모든 검사의 fallback 값입니다. webpack 자체 기본값보다 우선하므로 all: true는 전체 검사를 활성화하며, 명시적으로 설정한 개별 검사는 그대로 우선합니다.

export default {
  // ...
  performance: {
    hints: "warning",
    all: true,
    // `all`로 활성화되지만 이 항목은 비활성화 유지
    hotspots: false,
  },
};

all은 hints, maxAssetSize, maxEntrypointSize에 적용되지 않습니다.

performance.analyzableBailouts

5.111.0+

boolean = false

output.module 빌드에서 webpack의 런타임 형식을 유지한 참조를 보고하며, 각 참조가 리터럴 import() 또는 new URL()로 작성되지 못한 이유를 명시합니다. 이유는 모듈별로 나열하는 대신 그룹화하여 집계하며, ESM 출력 외부에서는 분석 가능하다고 주장하는 것이 없으므로 검사가 조용히 진행됩니다.

ESM 빌드는 일반적으로 각 청크와 애셋의 이름을 명시적으로 지정하므로, 다른 번들러, CDN의 모듈 프리로더 또는 import-map 생성기가 webpack 런타임을 실행하지 않고도 참조를 따라갈 수 있습니다. 무언가가 이를 방지하면 webpack은 __webpack_require__.e(id) 또는 __webpack_require__.p로 구성된 URL로 폴백하는데, 이는 정확하지만 webpack 외에는 불투명합니다. 이 검사 이전에는 그 폴백이 기본적으로 아무것도 표시하지 않는 stats.optimizationBailout을 통해서만 보고되었습니다.

각 이유의 의미와 해결 방법:

이유	변경 사항
`output.chunkFormat`이 `module`이 아님	청크가 네이티브 `import()`를 통해 전혀 읽히지 않습니다. `"module"`으로 설정하세요.
`output.importFunctionName`	호출 사이트가 `import()` 대신 명명된 함수입니다. `"import"`로 유지하세요.
worker가 `import` 이외의 것으로 청크를 로드함	`output.workerChunkLoading`을 `"import"`로 설정하거나 엔트리의 `chunkLoading`을 동일하게 설정하세요.
`devtool`이 모듈을 `eval()`로 감쌈	`import.meta`는 거기서 파싱되지 않으며, `eval()` 문자열 내에 작성된 지정자는 webpack이 작성하더라도 렉서에 보이지 않습니다. 출력이 분석 가능해야 할 때는 비`eval` devtool을 사용하세요.
`__webpack_public_path__`가 재할당됨	경로는 런타임에만 알 수 있으므로 리터럴을 쓸 수 없습니다. 대신 `output.publicPath`를 설정하세요.
`output.publicPath`가 기준이 필요함	상대 공개 경로는 각 청크에서 다르게 읽힙니다. 루트 절대 또는 절대 경로나 `"auto"`는 어디서나 동일하게 읽힙니다.
엔트리의 `baseUri`가 일치하지 않거나 절대 경로가 아님	모듈을 공유하는 엔트리에 동일한 절대 `baseUri`를 지정하세요.
핫 업데이트가 이름을 변경할 수 있음	HMR이 켜진 동안에만 해당됩니다. 프로덕션 출력에는 영향이 없습니다.

export default {
  // ...
  output: { module: true },
  performance: {
    hints: "warning",
    analyzableBailouts: true,
  },
};

performance.assetFilter

(assetFilename: string, source: Source, assetInfo: AssetInfo) => boolean

이 속성을 통해 webpack은 성능 힌트를 계산하는 데 사용되는 파일을 제어할 수 있습니다. 기본 함수는 소스맵처럼 assetInfo.development 플래그가 설정된 애셋을 제외합니다.

function assetFilter(assetFilename, source, assetInfo) {
  return !assetInfo.development;
}

다음과 같이 함수를 전달하여 속성을 재정의할 수 있습니다.

export default {
  // ...
  performance: {
    assetFilter(assetFilename) {
      return assetFilename.endsWith(".js");
    },
  },
};

위의 예에서는 .js 파일에 대한 성능 힌트만 제공합니다.

performance.asyncChunkWaterfalls

5.110.0+

boolean = false

앞선 청크가 도착해 실행된 뒤에야 다음 청크를 요청할 수 있는 import() 호출 체인을 보고합니다. 따라서 하위 항목이 시작되기 전에 체인의 각 단계에서 순차적인 round trip 비용이 발생합니다.

하위 모듈을 엔트리에서 가져오거나 하나의 webpackPrefetch hint를 지정하면 함께 가져올 수 있습니다.

performance.broadContexts

5.110.0+

boolean = false

filter가 없어 아무 곳에서도 요청하지 않는 파일까지 디렉터리 아래의 모든 파일을 번들링하는 require.context 호출을 보고합니다. sync context는 모두 함께 번들링하고 lazy context는 각 파일에 자체 청크를 할당합니다.

pattern 범위를 좁히거나 ContextReplacementPlugin을 사용하면 실제로 접근 가능한 항목으로 context를 제한할 수 있습니다.

performance.cacheEffectiveness

5.110.0+

boolean = false

cache가 모듈 그래프를 얼마나 재사용했는지와 재사용할 수 없는 모듈을 보고합니다. cache가 준비된 상태인데도 다시 빌드한 모듈 수와 원인을 경고하므로 cold cache와 매 빌드마다 무효화되는 cache를 구분할 수 있습니다.

performance.circularDependencies

5.110.0+

boolean = false

서로를 동기적으로 가져오는 모듈 그룹을 보고합니다. cycle로 인해 그룹의 모듈 중 하나 이상이 평가 시점에 부분적으로 초기화된 binding을 확인하게 되며 일부 export inlining이 제한됩니다.

export inlining에 필요하므로 이 옵션과 관계없이 mode: "production"에서 검사를 실행합니다. 이 옵션은 발견한 cycle의 보고 여부만 결정합니다.

performance.conflictingResourceHints

5.110.0+

boolean = false

같은 위치에서 prefetch와 preload를 모두 요청한 청크를 보고합니다. 두 directive는 반대 의미입니다. preload는 청크를 즉시 높은 우선순위로 가져오고 prefetch는 나중에 필요할 경우를 위해 idle 우선순위로 요청합니다. 페이지에 지금 필요한 항목에는 webpackPreload를, 나중에 필요할 수 있는 항목에는 webpackPrefetch를 사용하고 둘을 함께 사용하지 마세요.

이 검사는 hints의 영향을 받지 않습니다.

performance.duplicateModules

5.110.0+

boolean = false

둘 이상의 청크에 내보낸 모듈과 추가 복사본의 byte 비용을 보고하고, 각 비용을 발생시키는 엔트리 포인트를 표시합니다. 일반적으로 optimization.splitChunks를 사용해 공유 모듈을 자체 청크로 이동할 수 있음을 의미하며, 복사본이 서로 다른 엔트리 포인트에 있다면 chunks: "all"을 사용합니다.

performance.duplicatePackages

5.110.0+

boolean = false

서로 다른 버전 또는 같은 버전의 여러 복사본으로 두 번 이상 포함된 패키지를 보고합니다. 두 경우 모두 번들에 전체 복사본 비용이 추가되며, React나 store instance처럼 상태를 유지하는 패키지의 복사본이 여러 개이면 런타임 오류도 발생합니다.

export default {
  // ...
  performance: {
    hints: "warning",
    duplicatePackages: true,
  },
};

performance.dynamicExports

5.110.0+

boolean = false

export를 정적으로 읽을 수 없는 모듈(예: 조건문 안에서 module.exports에 할당하는 CommonJS 모듈)을 보고합니다. 이러한 모듈을 가져오는 코드는 tree shaking할 수 없습니다.

performance.evalUsage

5.110.0+

boolean = false

eval을 직접 호출하는 모듈을 보고합니다. 직접 호출한 eval은 scope의 모든 이름을 읽고 쓸 수 있어 모듈 선언의 이름을 바꾸거나 제거할 수 없으므로 minification, scope hoisting, tree shaking이 모두 중단됩니다. new Function은 local scope를 사용하지 않으므로 이러한 영향이 없습니다.

performance.hints

'error' | 'warning' | 'stats' false

힌트를 켜거나 끕니다. 또한 힌트가 발견되면 webpack에 오류나 경고를 표시하도록 합니다.

performance.hints의 기본값은 mode에 따라 다릅니다.

모드	기본값
`"production"`	`'warning'`
`"development"`	`false`
`"none"`	`false`

생성된 에셋의 크기가 250KB를 초과하는 경우:

export default {
  // ...
  performance: {
    hints: false,
  },
};

힌트 경고 또는 오류가 표시되지 않습니다

export default {
  // ...
  performance: {
    hints: "warning",
  },
};

큰 애셋을 알리는 경고가 표시됩니다. 개발 환경에서는 이처럼 사용하는 것을 권장합니다.

export default {
  // ...
  performance: {
    hints: "error",
  },
};

큰 애셋을 알려주는 오류가 표시됩니다. 크기가 너무 커서 웹 페이지 성능에 영향을 미치는 프로덕션 번들을 배포하는 것을 방지하기 위해, 프로덕션 빌드 시에는 hints: "error"를 사용하는 것이 좋습니다.

export default {
  // ...
  performance: {
    hints: "stats",
  },
};

5.110.0+

hint를 수집하여 stats를 통해서만 노출합니다. 경고나 오류로 계산하지 않으므로 빌드는 성공 상태를 유지하고 경고를 실패로 처리하는 CI 단계도 실패하지 않습니다. 모든 발견 항목을 빌드 출력으로 만들지 않고 위 검사의 보고서만 확인할 때 사용하세요.

performance.hotspots

5.110.0+

boolean = false

main thread를 점유하는 loader, plugin, hook을 보고하며 대기 시간이 아닌 각 항목 자체 코드의 실행 시간을 측정합니다. 동기 실행 구간만 계산하므로 await 후 재개된 작업은 포함하지 않습니다. 총합보다 실행 순서가 중요하면 ProfilingPlugin으로 같은 작업을 trace로 기록할 수 있습니다.

performance.inlinedAssets

5.110.0+

boolean = false

절약한 요청보다 base64 비용과 cache 손실이 더 큰 data URL 인라인 애셋을 보고합니다. data URL은 대체하는 파일보다 약 1/3 더 크고 독립적으로 cache할 수 없으며 주변 코드가 변경될 때마다 다시 다운로드됩니다. Rule.parser.dataUrlCondition.maxSize는 인라인 처리할 만큼 작은 파일의 기준을 정합니다.

performance.largeModules

5.110.0+

boolean = false

포함된 청크의 대부분을 차지하는 단일 모듈을 보고합니다. 청크의 나머지 항목을 모두 합쳐도 해당 모듈보다 작으므로 optimization.splitChunks로 분리하거나 on-demand로 로드하거나 교체해야 실제 크기를 줄일 수 있습니다.

performance.legacyJavascript

5.110.0+

boolean = false

target이 이미 네이티브로 지원하는 언어 기능을 구현하는 polyfill 패키지와 해당 byte 비용을 보고합니다.

performance.maxAssetSize

number = 250000

애셋은 webpack에서 내보낸 파일입니다. 이 옵션은 webpack이 개별 애셋 크기(단위:bytes)를 기준으로 성능 힌트를 내보낼 시기를 제어합니다.

export default {
  // ...
  performance: {
    maxAssetSize: 100000,
  },
};

webpack 5.110.0부터 경고에 크기 제한을 초과한 애셋 내부의 가장 큰 모듈도 표시하므로 파일뿐 아니라 분할할 대상을 확인할 수 있습니다.

performance.maxEntrypointSize

number = 250000

엔트리 포인트는 특정 항목의 초기 로드 시간 동안 사용될 모든 애셋을 나타냅니다. 이 옵션은 webpack이 최대 엔트리 포인트 크기(단위:bytes)를 기준으로 성능 힌트를 내보낼 시기를 제어합니다.

export default {
  // ...
  performance: {
    maxEntrypointSize: 400000,
  },
};

webpack 5.110.0부터 제한을 초과한 엔트리 포인트가 runtime도 포함하면, runtime이 함께 다시 다운로드되지 않도록 optimization.runtimeChunk를 권장합니다.

performance.missingSideEffects

5.110.0+

boolean = false

package.json에 sideEffects를 선언하지 않아 사용되지 않는 코드를 번들에 유지하는 패키지와 해당 byte 비용을 보고합니다.

performance.mixedExports

5.110.0+

boolean = false

CommonJS library에서 named export와 default를 함께 내보내는 엔트리를 보고합니다. 이 경우 require()를 호출한 consumer는 namespace 객체를 받아 default 값 자체가 아니라 .default로 접근해야 합니다. default 또는 named export 중 하나만 내보내면 모호하지 않으며 output.library.export로 하나를 선택할 수도 있습니다.

performance.osDependentRules

5.110.0+

boolean = false

경로 구분자를 hardcode하여 특정 운영체제에서만 일치하는 module.rules 조건을 보고합니다. 예를 들어 test: /src\/components\//는 Linux와 macOS에서는 일치하지만 Windows에서는 일치하지 않습니다.

이 검사는 hints의 영향을 받지 않습니다. 운영체제와 관계없이 일치하는 glob 조건도 참고하세요.

performance.pureAnnotations

5.110.0+

boolean = false

parser가 읽지 않는 위치의 /*#__PURE__*/ annotation을 보고합니다. annotation은 호출, new, tagged template 바로 앞에 있을 때만 읽으며 다른 위치에서는 일반 주석으로 처리되어 제거하려던 코드가 유지됩니다.

performance.redundantDynamicImports

5.110.0+

boolean = false

호출 위치에서 모듈이 이미 로드되어 아무것도 지연하지 않으면서 promise와 청크 경계 비용만 발생시키는 import() 호출을 보고합니다.

performance.scopeHoistingBailouts

5.110.0+

boolean = false

optimization.concatenateModules가 importer의 scope에 병합하지 못해 자체 wrapper를 유지하는 모듈과 그 원인을 보고합니다. 모듈을 하나씩 나열하지 않고 원인별로 묶어 개수를 표시합니다.

performance.sourceMaps

5.111.0+

boolean = false

효용보다 비용이 큰 source map을 보고합니다. 이 옵션은 두 가지 항목을 검사합니다. devtool이 map을 JavaScript 자체에 기록하는 production 빌드에서는 페이지를 로드하는 모든 사용자가 대상 코드보다 몇 배 큰 map까지 다운로드합니다. 별도의 .map 파일은 devtools를 여는 사용자만 가져오며, hidden-source-map은 오류 보고 서비스에 업로드할 map을 생성하면서도 client에는 전송하지 않습니다.

두 번째는 loader가 map을 반환하지 않고 변환한 모듈입니다. 이 경우 webpack은 loader의 출력을 디스크에 있는 파일처럼 취급하여 위치를 매핑합니다. 따라서 loader가 열 줄을 삽입하면 오류나 경고 없이 stack trace가 실제 위치에서 열 줄씩 어긋나는 map이 전달됩니다. loader가 this.callback(null, code, map)으로 map을 전달하도록 하세요.

performance.splitChunksCapped

5.110.0+

boolean = false

maxInitialRequests 또는 maxAsyncRequests 제한에 이미 도달하여 optimization.splitChunks가 거부한 분할을 보고합니다. 모듈이 원래 위치에 남아 cache group이 적용되지 않은 상태이며, 제한을 높이면 병렬 요청 수가 늘어나는 대신 분할할 수 있습니다.

performance.tinyChunks

5.110.0+

boolean = false

on-demand로 로드되지만 optimization.splitChunks.minSize보다 작아 지연하는 byte보다 요청 비용이 큰 청크를 보고합니다.

performance.topLevelThis

5.110.0+

boolean = false

ES module 최상위에서 this를 읽는 모듈을 보고합니다. 이 위치의 값은 모듈 객체나 전역 객체가 아니라 undefined입니다. javascript/auto는 import 또는 export 하나만 있어도 파일을 ES module로 판단하므로 CommonJS에서 작동하던 파일이 번들링 후 아무 값도 읽지 못할 수 있습니다. 전역 객체에는 globalThis, 모듈 정보에는 import.meta를 사용하거나 .cjs 확장자로 CommonJS를 유지하세요.

performance.unsplitVendors

5.110.0+

boolean = false

node_modules 코드와 애플리케이션 코드를 섞은 초기 청크를 보고합니다. 애플리케이션이 변경될 때마다 의존성에도 새 hash가 부여되어 재방문자가 다시 다운로드합니다. optimization.splitChunks로 의존성을 자체 청크로 이동할 수 있습니다.

performance.unusedAssets

5.111.0+

boolean = false

아무도 binding을 읽지 않는 import로 인해 내보낸 애셋 파일을 보고합니다. 이 경우 해당 byte가 불필요하게 전달됩니다. 단순히 import "./icon.png"로 가져온 경우에는 보고하지 않습니다. binding이 없다면 파일을 내보내는 것 자체가 import의 유일한 목적일 수 있기 때문입니다.

performance.unusedConfig

5.111.0+

boolean = false

어떤 빌드에서도 사용하지 않은 설정을 보고합니다. 아무 요청과도 일치하지 않은 resolve.alias 항목, 참조되지 않은 DefinePlugin key, 가져오지 않은 externals, 한 번도 일치하지 않은 module.rules가 해당합니다. 각 발견 항목은 고유한 메시지를 유지하므로 보고서에서 네 가지 중 어느 항목인지 확인할 수 있습니다.

철자가 틀린 external은 실제 요청이 대신 번들링되고 크기 제한으로도 원인을 설명할 수 없어 특히 큰 비용을 유발합니다. Plugin도 규칙을 추가하므로 보고된 규칙이 반드시 사용자가 작성한 것은 아닙니다.

performance.unusedModules

5.111.0+

boolean = false

export를 아무도 사용하지 않는데도 번들링된 모듈을 보고하고, 각 모듈이 유지된 원인을 표시합니다. re-export는 전형적인 barrel file 비용입니다. index.js의 export * from "./x"는 인접 모듈만 가져온 경우에도 ./x를 번들에 포함합니다. 또 다른 원인은 side effect 구문입니다. 이 경우 모듈은 평가될 때 수행하는 작업 때문에 유지되며, 보고서에 해당 구문과 위치가 표시됩니다.

Edit this page·

« Previous

InfrastructureLogging

Other Options

7 Contributors

Translators

dkstyle