Introduction

컴파일 절차를 커스터마이즈 하기 위해 다양한 인터페이스를 사용할 수 있습니다. 인터페이스 간에 겹치는 기능도 존재합니다. 예를 들면, 구성 옵션은 CLI 플래그를 통해 사용할 수 있지만 다른 옵션은 단일 인터페이스를 통해서만 존재합니다. 아래의 정보가 시작하는 데 도움을 줄 것입니다.

CLI

명령 줄 인터페이스(CLI)는 빌드를 구성하고 상호작용하는 데 사용됩니다. 특히 초기 프로토타이핑이나 프로파일링의 경우 유용합니다. 대부분의 경우 CLI는 설정 파일과 --env 같은 몇 가지 플래그를 사용하여 프로세스를 시작하는 데 사용됩니다.

CLI에 대해 더 알아보세요!

Module

webpack을 사용하여 모듈을 처리할 때 메소드나 변수같이 다양한 지원되는 모듈 구문을 이해하는 것이 중요합니다.

모듈에 대해 더 알아보세요!

Node

대부분의 사용자는 설정 파일과 CLI를 함께 사용하는 것만으로도 충분하지만, Node 인터페이스를 통해 컴파일을 보다 세밀하게 제어할 수 있습니다. 여기에는 다중 설정 전달과 프로그래밍 방식으로 실행 또는 감시, 통계 수집이 포함됩니다.

Node API에 대해 더 알아보세요!

Loaders

로더는 모듈의 소스 코드에 적용되는 변환입니다. 소스 코드를 매개 변수로 받고 변환이 적용된 해당 코드의 새 버전을 반환하는 함수로 작성됩니다.

로더에 대해 더 알아보세요!

Plugins

플러그인 인터페이스를 통해 컴파일 프로세스에 직접 접근할 수 있습니다. 플러그인은 컴파일 동안 서로 다른 지점에서 실행되는 수명주기 훅에 핸들러를 등록할 수 있습니다. 각각의 훅이 실행될 때 플러그인은 현재 컴파일 상태에 대한 모든 액세스 권한을 갖습니다.

플러그인에 대해 더 알아보세요!

Command Line Interface

이 설정을 적절하게 사용하고 쉽게 배포하려면 webpack.config.js로 webpack을 설정 할 수 있습니다. CLI로 전송된 모든 파라미터는 설정 파일의 해당 파라미터에 매핑됩니다.

webpack 및 CLI를 아직 설치하지 않은 경우 설치 가이드를 읽어보세요.

Commands

webpack-cli는 webpack을 더 쉽게 사용할 수 있도록 다양한 명령을 제공합니다. 기본적으로 webpack은 다음과 같은 명령어를 제공합니다.

Build

webpack을 실행합니다. (기본 명령어, 생략 가능).

npx webpack build [options]

example

npx webpack build --config ./webpack.config.js --stats verbose

Init

create-webpack-app을 사용하여 새 webpack 프로젝트를 초기화하는 데 사용됩니다.

npx create-webpack-app [generation-path] [options]

예시

npx create-webpack-app ./my-app --force --template=default

별칭으로:

npx create-webpack-app init ./my-app --force --template=default

Generation Path

설정을 생성할 위치입니다. 기본값은 process.cwd()입니다.

Options

-t, --template

string = 'default'

생성할 템플릿의 이름입니다.

-f, --force

boolean

질문 없이 프로젝트를 생성합니다. 활성화하면 각 질문에 대한 기본 답변을 사용합니다.

Templates supported

• --template=default - 기본 설정을 갖춘 템플릿입니다.
• --template=react - React 설정을 사용한 템플릿입니다.
• --template=vue - Vue 설정을 사용한 템플릿입니다.
• --template=svelte - Svelte 설정을 사용한 템플릿입니다.

Loader

로더를 스캐폴드합니다.

npx create-webpack-app loader [output-path] [options]

example

npx create-webpack-app loader ./my-loader --template=default

Output Path

출력 디렉터리 경로, 예) ./loader-name.

Options

-t, --template

string = 'default'

템플릿의 유형입니다.

Plugin

플러그인을 스캐폴드합니다.

npx create-webpack-app plugin [output-path] [options]

example

npx create-webpack-app plugin ./my-plugin --template=default

Output Path

출력 디렉터리 경로, 예) ./plugin-name.

Options

-t, --template

string = 'default'

템플릿의 유형입니다.

Info

시스템에 대한 정보를 출력합니다.

npx webpack info [options]

예시

npx webpack info --output json --additional-package postcss

Options for info

-a, --additional-package

string

출력에 패키지를 추가합니다.

예시

npx webpack info --additional-package postcss

-o, --output

'json' | 'markdown'

지정된 형식으로 출력을 가져옵니다.

예시

npx webpack info --output markdown

Configtest

webpack 설정을 검증합니다.

npx webpack configtest [config-path]

예시

npx webpack configtest ./webpack.config.js

Config Path

webpack 설정 파일의 경로입니다. 기본값은 ./webpack.config.js입니다.

Serve

webpack dev server를 실행합니다.

npx webpack serve [options]

example

npx webpack serve --static --open

Watch

webpack을 실행하고 파일 변경을 감지합니다.

npx webpack watch [options]

example

npx webpack watch --mode development

Flags

기본적으로 webpack은 다음 플래그와 함께 제공됩니다.

Negated Flags

Core Flags

CLI v4와 webpack v5부터 CLI는 webpack 코어에서 전체 설정 스키마를 가져옵니다. 커맨드 라인에서 거의 모든 설정 옵션을 조정할 수 있습니다.

CLI v4를 통한 webpack v5에서 지원하는 모든 코어 플래그 목록입니다. - 링크

예를 들어, 프로젝트에서 성능 힌트를 활성화하려면 설정에서 이 옵션을 사용할 수 있습니다. 코어 플래그를 사용하면 아래와 같이 할 수 있습니다.

npx webpack --performance-hints warning

Usage

With configuration file

npx webpack [--config webpack.config.js]

설정 파일의 옵션은 configuration을 참고하세요.

Without configuration file

npx webpack --entry <entry> --output-path <output-path>

예시

npx webpack --entry ./first.js --entry ./second.js --output-path /build

entry

프로젝트 빌드를 위한 엔트리 포인트 파일명 또는 명명된 파일명 모음입니다. 복수의 엔트리를 전달할 수 있습니다 (모든 항목은 시작 시 로드됩니다). 다음은 CLI를 통해 엔트리 파일을 지정하는 여러 가지 방법입니다.

npx webpack --entry-reset ./first-entry.js

npx webpack --entry-reset --entry ./first-entry.js

npx webpack --entry-reset ./first-entry.js ./other-entry.js

npx webpack --entry-reset --entry ./first-entry.js ./other-entry.js

output-path

저장할 번들 파일의 경로입니다. 설정 옵션의 output.path에 매핑됩니다.

예시

프로젝트 구조가 다음과 같다고 가정해봅니다.

.
├── dist
├── index.html
└── src
    ├── index.js
    ├── index2.js
    └── others.js

npx webpack ./src/index.js --output-path dist

이 명령어는 소스 코드와 엔트리를 함께 index.js로 번들합니다. 출력 번들 파일의 경로는 dist입니다.

asset main.js 142 bytes [compared for emit] [minimized] (name: main)
./src/index.js 30 bytes [built] [code generated]
./src/others.js 1 bytes [built] [code generated]
webpack 5.1.0 compiled successfully in 187 ms

npx webpack ./src/index.js ./src/others2.js --output-path dist/

이것은 두 파일을 별도의 엔트리 포인트로 포함하는 번들을 생성합니다.

asset main.js 142 bytes [compared for emit] [minimized] (name: main)
./src/index.js 30 bytes [built] [code generated]
./src/others2.js 1 bytes [built] [code generated]
./src/others.js 1 bytes [built] [code generated]
webpack 5.1.0 compiled successfully in 198 ms

Default Configurations

CLI는 프로젝트 경로에서 일부 기본 설정을 찾습니다. 아래는 CLI에서 찾는 설정 파일입니다.

오름차순으로 우선 조회합니다.

예시 - 설정 파일 조회 순서는 webpack.config.js > .webpack/webpack.config.js > .webpack/webpackfile.js입니다.

'webpack.config',
'.webpack/webpack.config',
'.webpack/webpackfile',

각 기본 이름은 지원되는 확장자(JavaScript 및 TypeScript 변형(.js, .mjs, .cjs, .ts, .cts, .mts), .coffee와 같은 기타 지원 언어, 그리고 webpack-cli 7.1.0부터는 데이터 포맷 .json5, .yaml/.yml 및 .toml)에 대해 해석됩니다.

Common Options

help

CLI에서 사용 가능한 기본 명령 및 플래그 나열

webpack help [command] [option] 및 webpack [command] --help 모두 유효합니다.

npx webpack --help

# or

npx webpack help

CLI에서 지원하는 모든 명령 및 플래그를 나열

npx webpack --help=verbose

특정 명령어 또는 옵션에 대한 도움말 보기

npx webpack help --mode

version

'webpack', 'webpack-cli', 'webpack-dev-server' 및 기타 패키지의 버전 번호를 출력합니다.

사용 중인 webpack 및 webpack-cli의 버전을 검사하려면 다음 명령을 실행하세요.

npx webpack --version

# or

npx webpack version

다음 결과가 출력됩니다.

webpack 5.31.2
webpack-cli 4.6.0

webpack-dev-server가 설치된 경우 해당 버전도 출력합니다.

webpack 5.31.2
webpack-cli 4.6.0
webpack-dev-server 3.11.2

config

설정 파일을 사용하여 소스 빌드

기본값 중 하나인 webpack.config.js가 아닌 다른 configuration 파일을 지정합니다.

npx webpack --config example.config.js

config-name

설정 파일이 여러 설정을 내보내는 경우 --config-name을 사용하여 실행할 설정을 지정할 수 있습니다.

아래와 같은 webpack.config.js를 생각해 봅시다.

export default [
  {
    output: {
      filename: "./dist-first.js",
    },
    name: "first",
    entry: "./src/first.js",
    mode: "development",
  },
  {
    output: {
      filename: "./dist-second.js",
    },
    name: "second",
    entry: "./src/second.js",
    mode: "development",
  },
  {
    output: {
      filename: "./dist-third.js",
    },
    name: "third",
    entry: "./src/third.js",
    mode: "none",
    stats: "verbose",
  },
];

second 설정만 실행합니다.

npx webpack --config-name second

여러 값을 전달할 수도 있습니다.

npx webpack --config-name first --config-name second

merge

--merge의 도움으로 두 개 이상의 서로 다른 webpack 설정을 병합할 수 있습니다.

npx webpack --config ./first.js --config ./second.js --merge

extends

--extends를 사용하여 기존 webpack 설정을 확장할 수 있습니다.

npx webpack --extends ./base.webpack.config.js

설정 확장에서 자세한 내용을 읽어보세요.

json

webpack 결과를 JSON으로 출력

npx webpack --json

통계를 출력하는 대신 json으로 저장

npx webpack --json stats.json

다른 모든 경우에 webpack은 번들, 청크 및 타이밍 세부 정보를 보여주는 일련의 통계를 출력합니다. 이 옵션을 사용하면 출력이 JSON 객체가 될 수 있습니다. webpack의 분석 도구, chrisbateman의 webpack-visualizer 또는 th0r의 webpack-bundle-analyzer 에서 이 응답이 수락됩니다. 이러한 분석 도구는 JSON을 가져와서 빌드의 모든 세부 정보를 그래픽 형식으로 제공합니다.

Environment Options

webpack 설정이 함수를 내보낼 때"environment"를 설정에 전달할 수 있습니다.

env

npx webpack --env production    # env.production = true

--env 인수는 복수의 값을 허용합니다.

위에 표시된 사용자 정의 env 외에도 env 하위에는 webpack 설정 내에서 사용되는 몇 가지 내장 기능이 있습니다.

번들 코드 내에서는 이러한 내장 환경 변수에 접근할 수 없는 점을 알아두세요.

export default (env, argv) => ({
  mode: env.WEBPACK_SERVE ? "development" : "production",
});

config-node-env

설정에 따라 process.env.NODE_ENV를 설정하세요.

npx webpack --config-node-env production   # process.env.NODE_ENV = 'production' in `webpack.config.js`

설정에서 mode 옵션이 지정되지 않은 경우 --config-node-env 옵션을 사용하여 mode를 설정할 수 있습니다. 예를 들어, --config-node-env production을 사용하면 process.env.NODE_ENV와 mode가 모두 'production'으로 설정됩니다.

설정이 함수를 내보내는 경우, 함수가 반환된 후 --config-node-env 값이 mode에 할당됩니다. 즉, mode는 함수 인수(env 및 argv)에서 사용할 수 없습니다. 그러나 --config-node-env의 값은 함수 내에서 argv.configNodeEnv로 접근 가능하며 그에 따라 사용할 수 있습니다.

export default (env, argv) => {
  console.log(argv.configNodeEnv); // --config-node-env production이 사용되는 경우 'production'
  return {
    // 당신의 설정
  };
};

Configuration Options

Analyzing Bundle

webpack-bundle-analyzer를 사용하여 webpack에서 내보낸 출력 번들을 분석할 수 있습니다. --analyze 플래그를 사용하여 CLI를 통해 호출 할 수 있습니다.

npx webpack --analyze

Progress

webpack 컴파일 진행 상황을 확인하려면 --progress 플래그를 사용합니다.

npx webpack --progress

진행 단계에 대한 프로필 데이터를 수집하려면 --progress 플래그에 profile을 값으로 전달할 수 있습니다.

npx webpack --progress=profile

Pass CLI arguments to Node.js

Node.js 프로세스에 직접 인수를 전달하려면 NODE_OPTIONS 옵션을 사용할 수 있습니다.

예를 들어, Node.js 프로세스의 메모리 제한을 4GB로 늘리려면 아래와 같이 사용합니다.

NODE_OPTIONS="--max-old-space-size=4096" webpack

또한 Node.js 프로세스에 복수의 옵션을 전달할 수 있습니다.

NODE_OPTIONS="--max-old-space-size=4096 -r /path/to/preload/file.js" webpack

Exit codes and their meanings

CLI Environment Variables

WEBPACK_CLI_FORCE_LOAD_ESM_CONFIG=true npx webpack --config ./webpack.config.esm

WEBPACK_PACKAGE

CLI에서 사용자 정의 webpack 버전을 사용합니다. package.json에서 다음 내용을 고려합니다.

{
  "webpack": "^4.0.0",
  "webpack-5": "npm:webpack@^5.32.0",
  "webpack-cli": "^4.5.0"
}

webpack v4.0.0을 사용하려면 아래 명령을 사용합니다.

npx webpack

webpack v5.32.0을 사용하려면 아래 명령을 사용합니다.

WEBPACK_PACKAGE=webpack-5 npx webpack

Troubleshooting

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for ./webpack.config.ts

TypeScript에서 기본 ESM을 사용하는 경우 이와 같은 오류가 발생할 수 있습니다 (예: package.json의 type: "module").

webpack-cli는 CommonJS와 ESM 형식의 설정을 모두 지원하며, 처음에는 import()를 사용하여 설정을 로드하려고 시도하고, 실패하면 require()를 사용하여 설정을 로드하려고 시도합니다. 하지만 import() 메서드는 ts-node에서 로더 훅을 활성화하지 않으면 작동하지 않습니다(자세한 내용은 TypeStrong/ts-node#1007 참고).

위의 오류를 수정하려면 다음 명령을 사용하세요.

NODE_OPTIONS="--import=data:text/javascript,import { register } from 'node:module'; import { pathToFileURL } from 'node:url'; register('ts-node/esm', pathToFileURL('./'));" npx webpack --entry ./src/index.js --mode production

자세한 내용은 TypeScript로 webpack 설정 작성에 대한 문서를 참고하세요.

Node Interface

webpack은 Node.js 런타임에서 직접 사용할 수 있는 Node.js API를 제공합니다.

Node.js API는 모든 보고 및 오류 처리가 수동으로 처리되어야 하므로, webpack이 컴파일 부분만 수행하고 빌드 또는 개발 프로세스는 사용자 정의하는 경우 유용합니다. 이러한 이유로 stats 설정 옵션은 webpack() 호출에 영향을 미치지 않습니다.

Installation

webpack Node.js API 사용을 시작하려면 먼저 webpack을 설치하세요.

npm install --save-dev webpack

다음으로 Node.js 스크립트에서 webpack 모듈을 가져옵니다.

import webpack from "webpack";

webpack()

가져온 webpack 함수는 webpack 설정 객체를 제공하며 콜백 함수가 제공되면 webpack 컴파일러를 실행합니다.

import webpack from "webpack";

webpack({}, (err, stats) => {
  if (err || stats.hasErrors()) {
    // ...
  }
  // 프로세싱 완료
});

Compiler Instance

webpack 러너 함수에 콜백을 전달하지 않으면 webpack Compiler 인스턴스를 반환합니다. 이 인스턴스를 사용하여 webpack 러너를 수동으로 트리거 하거나, 빌드하고 변경 사항을 감시할 수 있습니다. CLI와 비슷합니다. Compiler 인스턴스는 다음 메소드를 제공합니다.

• .run(callback)
• .watch(watchOptions, handler)

특정 작업을 위임하기 위해 자식 컴파일러를 생성할 수 있지만, 일반적으로 마스터 Compiler 인스턴스는 하나만 생성됩니다. Compiler는 궁극적으로 라이프 사이클을 계속 실행하기 위해 최소한의 기능만을 수행하는 함수입니다. 이는 등록된 플러그인에 모든 로딩, 번들링 및 쓰기 작업을 위임합니다.

Compiler 인스턴스의 hooks 속성은 Compiler 라이프 사이클의 훅 이벤트에 플러그인을 등록하는 데 사용됩니다. WebpackOptionsDefaulter 및 WebpackOptionsApply 유틸리티는 webpack에서 모든 내장 플러그인으로 Compiler 인스턴스를 설정하는 데 사용됩니다.

Compiler 인스턴스의 platform 속성은 target에서 해석된 타겟 환경을 설명합니다. 이는 플랫폼 플래그(web, browser, webworker, node, electron, nwjs, deno, bun 및 universal)의 읽기 전용 객체이며, 각 플래그는 true, false 또는 플랫폼이 중립으로 남아있을 때 null입니다. 플러그인과 로더는 이를 읽어 빌드 타겟에 적응할 수 있습니다. webpack 5.108.0부터 platform.universal은 target: "universal" 및 동등한 target: ["web", "node"]에 대해 true입니다.

그런 다음 run 메소드를 사용하여 모든 컴파일 작업을 시작합니다. 완료되면 지정된 callback 함수가 실행됩니다. 최종 통계 및 오류 로깅은 이 callback 함수에서 수행되어야 합니다.

Run

Compiler 인스턴스에서 run 메소드를 호출하는 것은 위에서 언급한 빠른 실행 메소드와 매우 유사합니다.

import webpack from "webpack";

const compiler = webpack({
  // ...
});

compiler.run((err, stats) => {
  // ...

  compiler.close((closeErr) => {
    // ...
  });
});

Watching

watch 메소드를 호출하면 webpack 러너를 트리거 하지만, 곧이어 변경 사항을 감시합니다 (webpack --watch CLI와 유사합니다). webpack이 변경사항을 감지하는 즉시 다시 실행합니다. Watching 인스턴스를 반환합니다.

watch(watchOptions, callback);

import webpack from "webpack";

const compiler = webpack({
  // ...
});

const watching = compiler.watch(
  {
    // 예시
    aggregateTimeout: 300,
    poll: undefined,
  },
  (err, stats) => {
    // watch/build 결과를 여기에 출력...
    console.log(stats);
  },
);

Watching 옵션은 여기에 자세히 설명되어 있습니다.

Close Watching

watch 메소드는 .close(callback) 메소드를 노출하는 Watching 인스턴스를 반환합니다. 이 메소드를 호출하면 감시가 종료됩니다.

watching.close((closeErr) => {
  console.log("Watching Ended.");
});

Invalidate Watching

watching.invalidate를 사용하면 감시 프로세스를 중지하지 않고 현재 컴파일 라운드를 수동으로 무효화할 수 있습니다.

watching.invalidate();

Stats Object

webpack() callback의 두 번째 인수로 전달되는 stats 객체는 코드 컴파일 프로세스에 대한 좋은 정보 소스입니다. 여기에는 다음이 포함됩니다.

• 오류 및 경고(있는 경우)
• 타이밍
• 모듈 및 청크 정보

webpack CLI는 이 정보를 사용하여 보기 좋은 형식으로 사용자의 콘솔에 출력을 표시합니다.

이 stats 객체는 다음 메소드를 노출합니다.

stats.hasErrors()

컴파일하는 동안 오류가 있었는지 확인하는 데 사용할 수 있습니다. true 또는 false를 반환합니다.

stats.hasWarnings()

컴파일하는 동안 경고가 있었는지 확인하는 데 사용할 수 있습니다. true 또는 false를 반환합니다.

stats.toJson(options)

컴파일 정보를 JSON 객체로 반환합니다. options는 문자열(사전 설정) 또는 보다 세분화된 제어를 위한 객체일 수 있습니다.

stats.toJson("minimal");

stats.toJson({
  assets: false,
  hash: true,
});

사용 가능한 모든 옵션과 사전 설정은 통계 문서에 설명되어 있습니다.

다음은 이 함수의 출력 예시입니다.

stats.toString(options)

컴파일 정보의 형식화된 문자열을 반환합니다. (CLI 출력과 유사합니다.)

옵션은 stats.toJson(options)과 동일하지만 한 가지 추가 사항이 있습니다.

stats.toString({
  // 콘솔 색상 추가
  colors: true,
});

다음은 stats.toString() 사용법의 예시입니다.

import webpack from "webpack";

webpack(
  {
    // ...
  },
  (err, stats) => {
    if (err) {
      console.error(err);
      return;
    }

    console.log(
      stats.toString({
        chunks: false, // 빌드를 훨씬 조용하게 만듭니다.
        colors: true, // 콘솔에 색상을 표시합니다.
      }),
    );
  },
);

MultiCompiler

MultiCompiler 모듈을 사용하면 webpack이 별도의 컴파일러에서 복수의 설정을 실행할 수 있습니다. webpack NodeJS API에 있는 options 파라미터가 옵션의 배열일 경우, webpack은 별도의 컴파일러를 적용하고 모든 컴파일러가 실행된 후 callback을 호출합니다.

import webpack from "webpack";

webpack(
  [
    { entry: "./index1.js", output: { filename: "bundle1.js" } },
    { entry: "./index2.js", output: { filename: "bundle2.js" } },
  ],
  (err, stats) => {
    process.stdout.write(`${stats.toString()}`);
  },
);

MultiCompiler hooks

MultiCompiler는 child compiler의 hook을 하나로 노출하므로 plugin이 각 child 대신 전체 집합을 tap할 수 있습니다.

webpack 5.110.0부터 done hook에는 실제 빌드가 실행된 compiler도 설정 순서대로 전달됩니다. watch mode에서 변경은 일반적으로 일부 child만 무효화하고 나머지는 이전 stats를 보고하므로 plugin은 이를 통해 새 항목을 구분할 수 있습니다.

import webpack from "webpack";

const compiler = webpack([config1, config2]);

compiler.hooks.done.tap("MyPlugin", (multiStats, changedCompilers) => {
  for (const child of changedCompilers) {
    console.log(`${child.name} rebuilt`);
  }
});

첫 빌드에서는 모든 child가 변경된 것으로 보고됩니다. 같은 릴리스에 추가된 shutdown을 사용하면 각 child의 shutdown을 tap하지 않고 전체 집합에서 한 번 리소스를 해제할 수 있습니다.

Error Handling

오류를 잘 처리하려면 다음 세 가지 유형의 오류를 고려해야 합니다.

• 치명적인 webpack 오류 (잘못된 구성 등)
• 컴파일 오류 (모듈 누락, 구문 오류 등)
• 컴파일 경고

다음은 이 모든 작업을 수행하는 예시입니다.

import webpack from "webpack";

webpack(
  {
    // ...
  },
  (err, stats) => {
    if (err) {
      console.error(err.stack || err);
      if (err.details) {
        console.error(err.details);
      }
      return;
    }

    const info = stats.toJson();

    if (stats.hasErrors()) {
      console.error(info.errors);
    }

    if (stats.hasWarnings()) {
      console.warn(info.warnings);
    }

    // 결과 로그...
  },
);

Custom File Systems

기본적으로 webpack은 파일을 읽고 디스크에 쓰는데 일반 파일 시스템을 사용합니다. 그러나 다른 종류의 파일시스템(메모리, webDAV 등)을 사용하여 입력 또는 출력 동작을 변경할 수 있습니다. 이를 위해 inputFileSystem 또는 outputFileSystem을 변경할 수 있습니다. 예를 들어 기본 outputFileSystem을 memfs으로 변경해서 디스크 대신 메모리에 파일을 쓸 수 있습니다.

import { Volume, createFsFromVolume } from "memfs";
import webpack from "webpack";

const fs = createFsFromVolume(new Volume());
const compiler = webpack({/* 옵션 */});

compiler.outputFileSystem = fs;
compiler.run((err, stats) => {
  // 출력 나중에 읽기
  const content = fs.readFileSync("...");
  compiler.close((closeErr) => {
    // ...
  });
});

webpack은 컴파일러에서 세 가지 파일 시스템을 구분합니다.

intermediateFileSystem은 기본적으로 Node의 fs를 사용합니다. outputFileSystem만 교체해도 캐시와 레코드는 여전히 디스크에 쓰므로, 빌드가 디스크에 전혀 접근하지 않도록 해야 할 때 이를 설정하세요.

이것이 webpack-dev-server와 다른 여러 패키지에서 사용하는 webpack-dev-middleware가 파일을 숨기면서도 브라우저까지 계속 제공할 수 있는 방법입니다!

Stats Data

webpack으로 소스 코드를 컴파일 할 때, 사용자는 모듈에 대한 통계가 포함된 JSON 파일을 생성할 수 있습니다. 이러한 통계는 애플리케이션의 디펜던시 그래프를 분석하고 컴파일 속도를 최적화하는데 사용할 수 있습니다. 파일은 일반적으로 다음 CLI 커맨드로 생성됩니다.

npx webpack --profile --json=compilation-stats.json

--json=compilation-stats.json 플래그는 디펜던시 그래프 및 기타 다양한 빌드 정보가 포함된 compilation-stats.json을 내보내야 함을 webpack에게 나타냅니다. 일반적으로, --profile 플래그도 추가되어 모듈별 컴파일 통계가 포함된 각 modules 객체에 profile 섹션이 추가됩니다.

Structure

출력 JSON 파일의 최상위 구조는 매우 간단하지만 몇 가지 중첩된 데이터 구조도 있습니다. 각 중첩 구조에는 이 문서를 보다 유용하게 사용할 수 있도록 아래에 전용 섹션이 있습니다. 아래의 최상위 구조 내의 링크를 클릭하면 관련 섹션 및 문서로 이동할 수 있습니다.

{
  "version": "5.9.0", // 컴파일에 사용된 webpack 버전
  "hash": "11593e3b3ac85436984a", // 컴파일 특정 해시
  "time": 2469, // 컴파일 시간 밀리초
  "publicPath": "auto",
  "outputPath": "/", // webpack 출력 디렉터리 경로
  "assetsByChunkName": {
    // 내보낸 애셋 매핑에 대한 청크 이름
    "main": ["web.js?h=11593e3b3ac85436984a"],
    "named-chunk": ["named-chunk.web.js"],
    "other-chunk": ["other-chunk.js", "other-chunk.css"]
  },
  "assets": [
    // [애셋 객체](#asset-objects) 목록
  ],
  "chunks": [
    // [청크 객체](#chunk-objects) 목록
  ],
  "modules": [
    // [모듈 객체](#module-objects) 목록
  ],
  "entrypoints": {
    // [엔트리 객체](#entry-objects) 목록
  },
  "errors": [
    // [에러 객체](#errors-and-warnings) 목록
  ],
  "errorsCount": 0, // 오류 개수
  "warnings": [
    // [경고 객체](#errors-and-warnings) 목록
  ],
  "warningsCount": 0 // 경고 개수
}

Asset Objects

각 assets 객체는 컴파일에서 내보낸 output 파일을 나타냅니다. 모두 유사한 구조를 따릅니다.

{
  "chunkNames": [], // 이 애셋에 포함된 청크
  "chunks": [10, 6], // 이 애셋에 포함된 청크 ID
  "comparedForEmit": false, // 애셋이 출력 파일 시스템의 동일한 파일과 비교되었는지 여부
  "emitted": true, // 애셋이 `output` 디렉터리에 도달했는지 여부
  "name": "10.web.js", // `output` 파일 이름
  "size": 1058, // 파일 크기(바이트)
  "info": {
    "immutable": true, // 애셋을 장기간 캐시 할 수 있는지 여부를 나타내는 플래그(해시 포함)
    "size": 1058, // 바이트 단위 크기, 애셋을 내보낸 뒤에만 사용 가능
    "development": true, // 애셋이 개발용으로만 사용되고 사용자 대면 애셋에 포함되지 않는지 여부를 나타내는 플래그
    "hotModuleReplacement": true, // 애셋이 기존 애플리케이션(HMR) 업데이트를 위한 데이터를 제공하는지 여부를 나타내는 플래그
    "sourceFilename": "originalfile.js", // 애셋이 소스 파일에서 생성된 경우의 sourceFilename(변환될 수 있음)
    "javascriptModule": true // true, 애셋이 Javascript 및 EMS인 경우
  }
}

Chunk Objects

각 chunks 객체는 청크로 알려진 모듈 그룹을 나타냅니다. 각 객체는 다음의 구조를 따릅니다.

{
  "entry": true, // 청크에 webpack 런타임이 포함되었는지 여부
  "files": [
    // 이 청크를 포함하는 파일 이름 문자열의 배열
  ],
  "filteredModules": 0, // 위의 [top-level structure](#structure) 설명 참고
  "id": 0, // 이 청크의 ID
  "initial": true, // 이 청크가 초기 페이지 로드 시 로드되는지 아니면 [on demand](/guides/lazy-loading) 시 로드되는지 여부
  "modules": [
    // [모듈 객체](#module-objects) 목록
    "web.js?h=11593e3b3ac85436984a"
  ],
  "names": [
    // 이 청크에 포함된 청크 이름 목록
  ],
  "origins": [
    // 아래 설명 참고...
  ],
  "parents": [], // 상위 청크 ID
  "rendered": true, // 청크가 코드 제너레이션을 거쳤는지 여부
  "size": 188057 // 청크 크기(바이트)
}

chunks 객체에는 주어진 청크가 어떻게 생성되었는지 설명하는 origins 목록도 포함됩니다. 각 origins 객체는 다음 스키마를 따릅니다.

{
  "loc": "", // 이 청크를 생성한 코드 라인
  "module": "(webpack)\\test\\browsertest\\lib\\index.web.js", // 모듈 경로
  "moduleId": 0, // 모듈 ID
  "moduleIdentifier": "(webpack)\\test\\browsertest\\lib\\index.web.js", // 모듈 경로
  "moduleName": "./lib/index.web.js", // 모듈에 대한 상대 경로
  "request": "./lib/index.web.js" // 청크 그룹을 생성한 요청
}

Module Objects

컴파일된 애플리케이션의 실제 모듈에 대한 설명이 없으면 이런 통계가 무슨 의미가 있겠습니까? 의존성 그래프의 각 모듈은 다음 구조로 표시됩니다.

{
  "assets": [
    // [애셋 객체](#asset-objects) 목록
  ],
  "built": true, // 이번 컴파일에서 모듈이 빌드([로더](/concepts/loaders) 및 파싱)되었음을 의미
  "cacheable": true, // 모듈이 캐시 가능한지 여부
  "chunks": [
    // 모듈을 포함하는 청크 ID
  ],
  "codeGenerated": true, // 이번 컴파일에서 모듈이 코드 생성을 거쳤음을 의미
  "errors": 0, // 모듈을 리졸브하거나 처리할 때 발생한 오류 수
  "failed": false, // 모듈에서 컴파일 실패 여부
  "id": 0, // 모듈의 ID ([`module.id`](/api/module-variables/#moduleid-commonjs)와 유사)
  "identifier": "(webpack)\\test\\browsertest\\lib\\index.web.js", // 내부적으로 사용되는 고유 ID
  "name": "./lib/index.web.js", // 실제 파일 경로
  "optional": false, // 모듈에 대한 모든 요청에는 `try... catch` 블록이 있습니다(ESM와 관련 없음)
  "profile": {
    // [`--profile` flag](/api/cli/#profiling)에 해당하는 모듈별 컴파일 통계 (밀리초 단위)
    "building": 73, // 로드 및 파싱
    "dependencies": 242, // 의존성 구축
    "factory": 11 // 의존성 해석
  },
  "reasons": [
    // 아래 설명 참고...
  ],
  "size": 3593, // 모듈 예상 크기(바이트)
  "source": "// Should not break it...\r\nif(typeof...", // 문자열화된 원시 소스
  "warnings": 0 // 모듈을 해석하거나 처리할 때 경고의 수
}

모든 모듈에는 해당 모듈이 의존성 그래프에 포함된 이유를 설명하는 reasons 객체 목록도 포함되어 있습니다. 각 "reason"은 위의 청크 객체 섹션에서 본 origins와 유사합니다.

{
  "loc": "33:24-93", // 모듈을 포함하게 만든 코드의 라인
  "module": "./lib/index.web.js", // [context](/configuration/entry-context/#context) 기반 모듈의 상대 경로
  "moduleId": 0, // 모듈 ID
  "moduleIdentifier": "(webpack)\\test\\browsertest\\lib\\index.web.js", // 모듈 경로
  "moduleName": "./lib/index.web.js", // 모듈의 더 읽기 쉬운 이름 ("pretty-printing"에 사용됨)
  "type": "require.context", // [type of request](/api/module-methods) 사용
  "userRequest": "../../cases" // `import` 또는 `require` 요청에 사용되는 원시 문자열
}

Entry Objects

"main": {
  "name": "main",
  "chunks": [
    179
  ],
  "assets": [
    {
      "name": "main.js",
      "size": 22
    }
  ],
  "filteredAssets": 0,
  "assetsSize": 22,
  "auxiliaryAssets": [],
  "filteredAuxiliaryAssets": 0,
  "auxiliaryAssetsSize": 0,
  "children": {},
  "childAssets": {},
  "isOverSizeLimit": false
}

Errors and Warnings

errors 및 warnings 프로퍼티에는 각각 객체 목록이 포함되어 있습니다. 각 객체에는 메시지, 스택 추적 및 다양한 프로퍼티가 포함되어 있습니다.

{
  "moduleIdentifier": "C:\\Repos\\webpack\\test\\cases\\context\\issue-5750\\index.js",
  "moduleName": "(webpack)/test/cases/context/issue-5750/index.js",
  "loc": "3:8-47",
  "message": "Critical dependency: Contexts can't use RegExps with the 'g' or 'y' flags.",
  "moduleId": 29595,
  "moduleTrace": [
    {
      "originIdentifier": "C:\\Repos\\webpack\\test\\cases|sync|/^\\.\\/[^/]+\\/[^/]+\\/index\\.js$/",
      "originName": "(webpack)/test/cases sync ^\\.\\/[^/]+\\/[^/]+\\/index\\.js$",
      "moduleIdentifier": "C:\\Repos\\webpack\\test\\cases\\context\\issue-5750\\index.js",
      "moduleName": "(webpack)/test/cases/context/issue-5750/index.js",
      "dependencies": [
        {
          "loc": "./context/issue-5750/index.js"
        }
      ],
      "originId": 32582,
      "moduleId": 29595
    },
    {
      "originIdentifier": "C:\\Repos\\webpack\\testCases.js",
      "originName": "(webpack)/testCases.js",
      "moduleIdentifier": "C:\\Repos\\webpack\\test\\cases|sync|/^\\.\\/[^/]+\\/[^/]+\\/index\\.js$/",
      "moduleName": "(webpack)/test/cases sync ^\\.\\/[^/]+\\/[^/]+\\/index\\.js$",
      "dependencies": [
        {
          "loc": "1:0-70"
        }
      ],
      "originId": 8198,
      "moduleId": 32582
    }
  ],
  "details": "at RequireContextDependency.getWarnings (C:\\Repos\\webpack\\lib\\dependencies\\ContextDependency.js:79:5)\n    at Compilation.reportDependencyErrorsAndWarnings (C:\\Repos\\webpack\\lib\\Compilation.js:1727:24)\n    at C:\\Repos\\webpack\\lib\\Compilation.js:1467:10\n    at _next2 (<anonymous>:16:1)\n    at eval (<anonymous>:42:1)\n    at C:\\Repos\\webpack\\node_modules\\neo-async\\async.js:2830:7\n    at Object.each (C:\\Repos\\webpack\\node_modules\\neo-async\\async.js:2850:39)\n    at C:\\Repos\\webpack\\lib\\FlagDependencyExportsPlugin.js:219:18\n    at C:\\Repos\\webpack\\node_modules\\neo-async\\async.js:2830:7\n    at Object.each (C:\\Repos\\webpack\\node_modules\\neo-async\\async.js:2850:39)\n    at C:\\Repos\\webpack\\lib\\FlagDependencyExportsPlugin.js:40:16\n    at Hook.eval [as callAsync] (<anonymous>:38:1)\n    at Hook.CALL_ASYNC_DELEGATE [as _callAsync] (C:\\Repos\\tapable\\lib\\Hook.js:18:14)\n    at Compilation.finish (C:\\Repos\\webpack\\lib\\Compilation.js:1462:28)\n    at C:\\Repos\\webpack\\lib\\Compiler.js:909:18\n    at processTicksAndRejections (internal/process/task_queues.js:75:11)\n",
  "stack": "ModuleDependencyWarning: Critical dependency: Contexts can't use RegExps with the 'g' or 'y' flags.\n    at Compilation.reportDependencyErrorsAndWarnings (C:\\Repos\\webpack\\lib\\Compilation.js:1732:23)\n    at C:\\Repos\\webpack\\lib\\Compilation.js:1467:10\n    at _next2 (<anonymous>:16:1)\n    at eval (<anonymous>:42:1)\n    at C:\\Repos\\webpack\\node_modules\\neo-async\\async.js:2830:7\n    at Object.each (C:\\Repos\\webpack\\node_modules\\neo-async\\async.js:2850:39)\n    at C:\\Repos\\webpack\\lib\\FlagDependencyExportsPlugin.js:219:18\n    at C:\\Repos\\webpack\\node_modules\\neo-async\\async.js:2830:7\n    at Object.each (C:\\Repos\\webpack\\node_modules\\neo-async\\async.js:2850:39)\n    at C:\\Repos\\webpack\\lib\\FlagDependencyExportsPlugin.js:40:16\n    at Hook.eval [as callAsync] (<anonymous>:38:1)\n    at Hook.CALL_ASYNC_DELEGATE [as _callAsync] (C:\\Repos\\tapable\\lib\\Hook.js:18:14)\n    at Compilation.finish (C:\\Repos\\webpack\\lib\\Compilation.js:1462:28)\n    at C:\\Repos\\webpack\\lib\\Compiler.js:909:18\n    at processTicksAndRejections (internal/process/task_queues.js:75:11)\n"
}

webpack-dev-server API

webpack-dev-server는 Node.js 런타임에서 직접 사용할 수 있는 Node.js API를 제공합니다.

Installation

webpack-dev-server Node.js API를 사용하려면, 먼저 webpack 과 webpack-dev-server를 설치하세요.

npm install --save-dev webpack webpack-dev-server

그런 다음 Node.js 스크립트에 모듈이 필요합니다.

import webpack from "webpack";
import WebpackDevServer from "webpack-dev-server";

start

webpack-dev-server 인스턴스에 서버를 시작하도록 지시합니다.

server.js

import webpack from "webpack";
import WebpackDevServer from "webpack-dev-server";
import webpackConfig from "./webpack.config.js";

const compiler = webpack(webpackConfig);
const devServerOptions = { ...webpackConfig.devServer, open: true };
const server = new WebpackDevServer(devServerOptions, compiler);

const runServer = async () => {
  console.log("Starting server...");
  await server.start();
};

runServer();

그런 다음 아래 명령으로 서버를 실행합니다.

node server.js

startCallback(callback)

webpack-dev-server 인스턴스에 서버를 시작한 후 콜백 함수를 실행하도록 지시합니다.

server.js

import webpack from "webpack";
import WebpackDevServer from "webpack-dev-server";
import webpackConfig from "./webpack.config.js";

const compiler = webpack(webpackConfig);
const devServerOptions = { ...webpackConfig.devServer, open: true };
const server = new WebpackDevServer(devServerOptions, compiler);

server.startCallback(() => {
  console.log("Successfully started server on http://localhost:8080");
});

그런 다음 아래 명령으로 서버를 실행합니다.

node server.js

stop

webpack-dev-server 인스턴스에 서버를 중지하도록 지시합니다.

server.js

import webpack from "webpack";
import WebpackDevServer from "webpack-dev-server";
import webpackConfig from "./webpack.config.js";

const compiler = webpack(webpackConfig);
const devServerOptions = { ...webpackConfig.devServer, open: true };
const server = new WebpackDevServer(devServerOptions, compiler);

const runServer = async () => {
  console.log("Starting server...");
  await server.start();
};

const stopServer = async () => {
  console.log("Stopping server...");
  await server.stop();
};

runServer();

setTimeout(stopServer, 5000);

그런 다음 아래 명령으로 서버를 실행합니다.

node server.js

stopCallback(callback)

webpack-dev-server 인스턴스에 서버를 중지하고 콜백 함수를 실행하도록 지시합니다.

server.js

import webpack from "webpack";
import WebpackDevServer from "webpack-dev-server";
import webpackConfig from "./webpack.config.js";

const compiler = webpack(webpackConfig);
const devServerOptions = { ...webpackConfig.devServer, open: true };
const server = new WebpackDevServer(devServerOptions, compiler);

server.startCallback(() => {
  console.log("Successfully started server on http://localhost:8080");
});

const stopServer = () =>
  server.stopCallback(() => {
    console.log("Server stopped.");
  });

setTimeout(stopServer, 5000);

그런 다음 아래 명령으로 서버를 실행합니다.

node server.js

apply(compiler)

webpack-dev-server는 constructor에 compiler를 명시적으로 전달하지 않고도 webpack plugin으로 사용할 수 있습니다. 서버는 compiler lifecycle과 통합되어 watch mode에서 첫 번째 compilation이 완료되면 시작되고, 다시 compilation될 때 여러 번 시작되지 않으며, compiler가 닫히면 깔끔하게 종료됩니다. MultiCompiler 구성도 지원하므로 각 설정이 자체 plugin server를 실행할 수 있습니다.

server.js

import webpack from "webpack";
import WebpackDevServer from "webpack-dev-server";

const compiler = webpack({
  // ...
  mode: "development",
  plugins: [new WebpackDevServer({ port: 8080 })],
});

compiler.watch({}, (error) => {
  if (error) {
    console.error(error);
  }
});

기존 compiler에 apply를 직접 호출할 수도 있습니다.

const server = new WebpackDevServer({ port: 8080 });

server.apply(compiler);

findIp(gatewayOrFamily, isInternal)

해석된 로컬 IP 주소를 동기적으로 반환하며, 일치하는 주소를 찾지 못하면 undefined를 반환합니다.

• gatewayOrFamily: IP family ("v4" | "v6") 또는 gateway IP 주소입니다. gateway 주소를 전달하면 같은 subnet에 속한 로컬 interface의 주소를 반환합니다.
• isInternal: 선택 사항입니다. false로 설정하면 외부에서 접근 가능한(LAN) 주소만 고려하고, true로 설정하면 내부 주소(예: loopback)만 고려합니다. 생략하면 둘 다 고려합니다.

server.js

import WebpackDevServer from "webpack-dev-server";

const localIPv4 = WebpackDevServer.findIp("v4", false);
const localIPv6 = WebpackDevServer.findIp("v6", false);

console.log("Local IPv4 address:", localIPv4);
console.log("Local IPv6 address:", localIPv6);

Hot Module Replacement

Hot Module Replacement가 HotModuleReplacementPlugin을 통해 활성화된 경우, 해당 인터페이스는 import.meta.webpackHot프로퍼티 뿐만 아니라 module.hot프로퍼티 아래 노출됩니다. strict ESM에서는 import.meta.webpackHot만 사용할 수 있습니다.

일반적으로, 사용자는 인터페이스에 접근할 수 있는지 확인한 후, 작업을 시작합니다. 예를 들어, 업데이트된 모듈을 accept 하는 방법은 다음과 같습니다.

if (module.hot) {
  module.hot.accept("./library.js", () => {
    // 업데이트된 라이브러리 모듈로 작업을 수행하세요...
  });
}

// or
if (import.meta.webpackHot) {
  import.meta.webpackHot.accept("./library.js", () => {
    // 업데이트된 라이브러리 모듈로 작업을 수행하세요…
  });
}

지원되는 메소드는 다음과 같습니다...

Module API

accept

주어진 dependencies에 대한 업데이트를 수락하고 해당 업데이트에 반응하기 위해 callback을 실행합니다. 또한, 선택적 에러 핸들러를 연결할 수 있습니다.

module.hot.accept(
  dependencies, // 문자열 또는 문자열 배열
  callback, // 의존성이 업데이트될 때 실행할 함수
  errorHandler, // (err, {moduleId, dependencyId}) => {}
);

// 또는
import.meta.webpackHot.accept(
  dependencies, // 문자열 또는 문자열 배열
  callback, // 의존성이 업데이트될 때 실행할 함수
  errorHandler, // (err, {moduleId, dependencyId}) => {}
);

ESM import를 사용하면 dependencies에서 가져온 모든 심볼이 자동으로 업데이트됩니다. 참고: 의존성 문자열은 import의 from 문자열과 정확히 일치해야 합니다. 경우에 따라 callback을 생략할 수 있습니다. callback에서 require()를 사용하는 것은 여기에서 의미가 없습니다.

CommonJS를 사용할 때 callback에서 require()를 사용해서 의존성을 수동으로 업데이트해야 합니다. callback을 생략하는 경우도 있습니다.

errorHandler for accept

(err, {moduleId, dependencyId}) => {}

• err: ESM 의존성을 사용할 때 두 번째 인수 또는 의존성 실행 중에 콜백에 의해 발생한 에러.
• moduleId: 현재 모듈 id.
• dependencyId: (첫 번째) 변경된 의존성의 모듈 id.

accept (self)

자체적으로 업데이트를 수락합니다.

module.hot.accept(
  errorHandler, // 새 버전을 평가할 때 에러를 처리하는 함수
);

// 또는
import.meta.webpackHot.accept(
  errorHandler, // 새 버전을 평가할 때 에러를 처리하는 함수
);

모듈 또는 의존성이 업데이트되면, 부모에게 알리지 않고 이 모듈을 폐기하고 재평가 할 수 있습니다. 이것은 이 모듈에 내보내기가 없는 경우(또는 내보내기가 다른 방식으로 업데이트되는 경우) 의미가 있습니다.

이 모듈(또는 의존성)의 평가에서 예외가 발생하면 errorHandler가 실행됩니다.

errorHandler for self accept

(err, {moduleId, module}) => {}

• err: 새 버전을 평가할 때 발생한 에러.
• moduleId: 현재 모듈 id.
• module: 현재 모듈 인스턴스.
  • module.hot: 에러가 발생한 모듈 인스턴스의 HMR API를 사용하도록 허용합니다. 일반적인 시나리오는 스스로 그것을 다시 수락하는 것입니다. 또한 데이터를 전달하기 위해 dispose 핸들러를 추가하는 것이 좋습니다. 에러가 발생한 모듈은 이미 부분적으로 실행되었을 수 있음으로, 일관성 없는 상태가 되지 않도록 주의하세요. module.hot.data를 사용하여 부분 상태를 저장할 수 있습니다.
  • module.exports: 오버라이드할 수 있지만, 프로덕션 모드에서 프로퍼티 이름이 손상될 수 있음으로 주의하세요.

decline

주어진 dependencies에 대한 업데이트를 거부하여 'decline' 코드로 업데이트가 실패하도록 합니다.

module.hot.decline(
  dependencies, // 문자열 또는 문자열 배열
);

// 또는
import.meta.webpackHot.decline(
  dependencies, // 문자열 또는 문자열 배열
);

업데이트 불가능으로 의존성에 플래그를 지정합니다. 이것은 의존성 내보내기 변경을 처리할 수 없거나 처리가 아직 구현되지 않은 경우 의미가 있습니다. HMR 관리 코드에 따라, 이러한 의존성(또는 허용되지 않는 의존성)에 대한 업데이트로 인해 일반적으로 전체 페이지가 다시 로드됩니다.

decline (self)

자체적으로 업데이트를 거부합니다.

module.hot.decline();

// 또는
import.meta.webpackHot.decline();

업데이트 불가능으로 모듈에 플래그를 지정합니다. 이는 이 모듈에 되돌릴 수 없는 사이드 이펙트가 있거나, 이 모듈에 대해 HMR 처리가 아직 구현되지 않은 경우 의미가 있습니다. HMR 관리 코드에 따라, 이러한 모듈(또는 허용되지 않은 의존성)에 대한 업데이트로 인해 일반적으로 전체 페이지가 다시 로드됩니다.

dispose (or addDisposeHandler)

현재 모듈 코드가 교체될 때 실행되는 핸들러를 추가합니다. 이것은 요청하거나 생성한 영구 리소스를 제거하는 데 사용해야 합니다. 업데이트된 모듈에 상태를 전송하려면, 주어진 data 파라미터에 추가하세요. 이 객체는 업데이트 후 module.hot.data에서 사용할 수 있습니다.

module.hot.dispose((data) => {
  // 데이터를 정리하고 업데이트된 모듈로 전달합니다.
});

// 또는
import.meta.webpackHot.dispose((data) => {
  // 데이터를 정리하고 업데이트된 모듈로 전달합니다.
});

invalidate

이 메서드를 호출하면 현재 모듈이 무효화 되고, HMR 업데이트가 적용될 때 이를 삭제하고 다시 생성합니다. 버블은 이 모듈의 일반 업데이트와 같습니다. 이 모듈은 invalidate를 자체 승인할 수 없습니다.

idle 상태에서 호출되면, 이 모듈을 포함하는 새 HMR 업데이트가 생성됩니다. HMR은 ready 상태로 들어갑니다.

ready 또는 prepare 상태에서 호출되면, 이 모듈은 현재 HMR 업데이트에 추가됩니다.

check 상태에서 호출되면, 이 모듈은 업데이트를 사용할 수 있을 때 업데이트에 추가됩니다. 사용 가능한 업데이트가 없으면 새 업데이트가 생성됩니다. HMR은 ready 상태로 들어갑니다.

dispose 또는 apply 상태에서 호출되면, HMR은 해당 상태에서 나온 후 이를 선택합니다.

Use Cases

Conditional Accepting

모듈은 의존성을 받아들일 수 있지만, 의존성 변경을 처리할 수 없는 경우 invalidate를 호출할 수 있습니다.

import { processX, processY } from "anotherDep";
import { x, y } from "./dep";

const oldY = y;

processX(x);

export default processY(y);

module.hot.accept("./dep", () => {
  if (y !== oldY) {
    // 처리할 수 없으며, 부모에게 전달
    module.hot.invalidate();
    return;
  }
  // 처리할 수 없음
  processX(x);
});

Conditional self accept

모듈은 자체 수용할 수 있지만, 변경 사항을 처리할 수 없을 때 자체를 무효화 할 수 있습니다.

const VALUE = "constant";

export default VALUE;

if (
  module.hot.data &&
  module.hot.data.value &&
  module.hot.data.value !== VALUE
) {
  module.hot.invalidate();
} else {
  module.hot.dispose((data) => {
    data.value = VALUE;
  });
  module.hot.accept();
}

Triggering custom HMR updates

const moduleId = chooseAModule();
const code = __webpack_modules__[moduleId].toString();
__webpack_modules__[moduleId] = eval(`(${makeChanges(code)})`);
if (require.cache[moduleId]) {
  require.cache[moduleId].hot.invalidate();
  module.hot.apply();
}

removeDisposeHandler

dispose 또는 addDisposeHandler를 통해 추가된 핸들러를 제거합니다.

module.hot.removeDisposeHandler(callback);

// 또는
import.meta.webpackHot.removeDisposeHandler(callback);

Management API

status

hot module replacement 프로세스의 현재 상태를 검색합니다.

module.hot.status(); // 다음 문자열 중 하나를 반환합니다...

// 또는
import.meta.webpackHot.status();

check

업데이트를 위해 로드된 모든 모듈을 테스트하고, 업데이트가 있는 경우 이를 apply 합니다.

module.hot
  .check(autoApply)
  .then((outdatedModules) => {
    // outdated 모듈...
  })
  .catch((error) => {
    // 에러 catch
  });

// 또는
import.meta.webpackHot
  .check(autoApply)
  .then((outdatedModules) => {
    // outdated 모듈...
  })
  .catch((error) => {
    // 에러 catch
  });

autoApply 파라미터는 boolean이거나 호출될 때 apply메서드에 전달할 options일 수 있습니다.

apply

업데이트 프로세스를 계속합니다.(module.hot.status() === 'ready'인 동안)

module.hot
  .apply(options)
  .then((outdatedModules) => {
    // outdated 모듈...
  })
  .catch((error) => {
    // 에러 catch
  });

// 또는
import.meta.webpackHot
  .apply(options)
  .then((outdatedModules) => {
    // outdated 모듈...
  })
  .catch((error) => {
    // 에러 catch
  });

선택적 options 객체에는 다음 프로퍼티가 포함될 수 있습니다.

• ignoreUnaccepted (boolean): 허용되지 않는 모듈에 대한 변경 사항을 무시합니다.
• ignoreDeclined (boolean): 거부된 모듈에 대한 변경 사항을 무시합니다.
• ignoreErrored (boolean): accept 핸들러, 에러 핸들러 및 모듈을 재평가하는 동안 발생하는 에러를 무시합니다.
• onDeclined (function(info)): 거부된 모듈에 대한 알림
• onUnaccepted (function(info)): 허용되지 않는 모듈에 대한 알림
• onAccepted (function(info)): 허용된 모듈에 대한 알림
• onDisposed (function(info)): 폐기된 모듈에 대한 알림
• onErrored (function(info)): 에러 알림

info 파라미터는 다음 값 중 일부를 포함하는 객체입니다.

{
  type: 'self-declined' | 'declined' |
        'unaccepted' | 'accepted' |
        'disposed' | 'accept-errored' | 'accept-error-handler-errored' |
        'self-accept-errored' | 'self-accept-error-handler-errored',
  moduleId: 4, // 질문의 모듈.
  dependencyId: 3, // 에러의 경우: accept 핸들러를 throw한 업데이트된 디펜던시의 id (`moduleId`는 핸들러를 소유한 모듈).
  chain: [1, 2, 3, 4], // 거부/허용/허용되지 않음의 경우: 업데이트가 전파된 체인.
  parentId: 5, // 거부된 경우: 거부하는 상위의 모듈 id
  outdatedModules: [1, 2, 3, 4], // 허용된 경우: 오래되어 폐기될 모듈
  outdatedDependencies: { // 허용된 경우: 업데이트를 처리할 accept 핸들러의 위치
    5: [4]
  },
  error: new Error(...), // 에러의 경우: throw 된 에러
  originalError: new Error(...) // accept-error-handler-errored 및 self-accept-error-handler-errored의 경우:
                                // 에러 핸들러가 처리를 시도하기 전에 accept 핸들러 또는 모듈에서 발생한 에러.
}

addStatusHandler

status의 변경을 수신할 함수 등록합니다.

module.hot.addStatusHandler((status) => {
  // 현재 상태에 반응...
});

// 또는
import.meta.webpackHot.addStatusHandler((status) => {
  // 현재 상태에 반응...
});

상태 핸들러가 Promise를 반환하면, HMR 시스템은 계속하기 전에 Promise가 해결될 때까지 기다립니다.

removeStatusHandler

등록된 상태 핸들러 제거.

module.hot.removeStatusHandler(callback);

// 또는
import.meta.webpackHot.removeStatusHandler(callback);

Loader Interface

로더는 함수를 내보내는 자바스크립트 모듈입니다. 로드 러너는 이 함수를 호출하여 이전 로더 혹은 리소스 파일의 결과를 전달합니다. 함수의 this 컨텍스트는 webpack과 로드 러너에 의해 채워지며, 로더가 호출 스타일을 비동기로 변경하거나 쿼리 매개변수를 가져올 수 있도록 하는 몇가지 유용한 메소드를 제공합니다.

첫 번째 로더에는 리소스 파일의 내용이라는 하나의 인수를 넘깁니다. 컴파일러는 마지막 로더의 결과를 기대합니다. 결과는 모듈의 자바스크립트 소스 코드를 나타내는 String 또는 Buffer(문자열로 변환됨)여야 합니다. 선택적 소스맵 결과(JSON 객체로)도 전달할 수 있습니다.

동기 모드에서는 단일 결과가 반환될 수 있습니다. 여러 결과의 경우 this.callback()을 호출해야 하며 로더는 undefined를 반환해야 합니다.

비동기 모드에서 비동기 함수에서 단일 결과를 반환할 수 있습니다. 또는 this.async()를 호출하여 로더 러너가 비동기 결과를 기다려야 함을 나타낼 수 있습니다. 이 경우 this.callback()을 반환합니다. 이 경우 로더는 undefined를 반환하고 해당 콜백을 호출해야 합니다. 이 옵션은 여러 결과에 대한 유일한 옵션입니다.

/**
 *
 * @param {string|Buffer} [content] 리소스 파일의 내용
 * @param {object} [map] https://github.com/mozilla/source-map 에서 사용할 수 있는 소스맵 데이터
 * @param {any} [meta] 메타 데이터, 무엇이든 될 수 있습니다
 */
function webpackLoader(content, map, meta) {
  // webpack 로더의 코드
}

Examples

다음 섹션에서는 다양한 유형의 로더에 대한 몇 가지 기본 예를 제공합니다. map 및 meta 매개변수는 선택 사항입니다. 아래의 this.callback을 참고하세요.

Synchronous Loaders

return 또는 this.callback을 사용하여 변환된 content를 동기적으로 반환할 수 있습니다.

sync-loader.js

export default function syncLoader(content, map, meta) {
  return someSyncOperation(content);
}

this.callback 메소드는 content만 사용하는 것이 아니라 여러 인수를 전달할 수 있으므로 더 유연합니다.

sync-loader-with-multiple-results.js

export default function syncLoaderWithMultipleResults(content, map, meta) {
  this.callback(null, someSyncOperation(content), map, meta);
  return; // callback() 함수를 호출하면 항상 undefined를 반환합니다.
}

Asynchronous Loaders

비동기 로더의 경우 비동기 함수에서 변환된 콘텐츠를 반환할 수 있습니다.

async-loader.js

export default async function asyncLoader(content, map, meta) {
  const result = await someAsyncOperation(content);
  return result;
}

또는 this.async를 사용하여 callback 함수를 검색할 수 있습니다.

async-loader-with-callback.js

export default function asyncLoaderWithCallback(content, map, meta) {
  const callback = this.async();
  someAsyncOperation(content, (err, result) => {
    if (err) return callback(err);
    callback(null, result, map, meta);
  });
}

async-loader-with-multiple-results.js

export default function asyncLoaderWithMultipleResults(content, map, meta) {
  const callback = this.async();
  someAsyncOperation(content, (err, result, sourceMaps, meta) => {
    if (err) return callback(err);
    callback(null, result, sourceMaps, meta);
  });
}

"Raw" Loader

기본적으로 리소스 파일은 UTF-8 문자열로 변환되어 로더에 전달됩니다. raw 플래그를 true로 설정하면 로더가 원시 Buffer를 받게 됩니다. 모든 로더는 결과를 String 혹은 Buffer로 전달할 수 있습니다. 컴파일러는 로더 사이에서 변환되어 작동됩니다.

my-raw-loader.js

export default function rawLoader(content) {
  assert(content instanceof Buffer);
  return someSyncOperation(content);
  // 반환 값도 `Buffer`가 될 수 있습니다.
  // 로더가 "raw"가 아닌 경우에도 허용됩니다.
}
export const raw = true;

Pitching Loader

로더는 항상 오른쪽에서 왼쪽으로 호출됩니다. 로더가 요청 뒤의 메타 데이터에만 관심을 두고 이전 로더의 결과를 무시할 수 있는 경우가 있습니다. 로더의 pitch 메소드는 로더가 실제로 실행(오른쪽에서 왼쪽으로)되기 전에 왼쪽에서 오른쪽으로 호출됩니다.

다음과 같은 use 설정을 살펴보겠습니다.

export default {
  // ...
  module: {
    rules: [
      {
        // ...
        use: ["a-loader", "b-loader", "c-loader"],
      },
    ],
  },
};

다음 단계들이 발생합니다.

|- a-loader `pitch`
  |- b-loader `pitch`
    |- c-loader `pitch`
      |- 요청된 모듈이 의존성으로 선택됩니다
    |- c-loader 정상 실행
  |- b-loader 정상 실행
|- a-loader 정상 실행

그렇다면 로더가 "pitching" 단계를 이용하는 이유는 무엇일까요?

첫째, pitch 메소드에 전달된 data는 실행 단계에서도 this.data 아래에 노출되며 실행 주기의 초기부터 정보를 캡처하고 공유하는 데 유용할 수 있습니다.

export default function myLoaderName(content) {
  return someSyncOperation(content, this.data.value);
}

export function pitch(remainingRequest, previousRequest, data) {
  data.value = 42;
}

둘째, 로더가 pitch 방식으로 결과를 전달하면 프로세스가 돌아가 나머지 로더를 건너뜁니다. 아래는 위의 예시에서 b-loader의 pitch 메소드가 무언가를 반환했을 때의 경우를 살펴봅니다.

export default function myLoaderName(content) {
  return someSyncOperation(content);
}

export function pitch(remainingRequest, previousRequest, data) {
  if (someCondition()) {
    return `import _from_loader from "${JSON.stringify(`-!${remainingRequest}`)}"; export default _from_loader;`;
  }
}

위의 단계는 다음과 같이 단축됩니다.

|- a-loader `pitch`
  |- b-loader는 `pitch`를 통해 모듈을 리턴합니다
|- a-loader 정상 실행

The Loader Context

로더 컨텍스트는 this 속성에 할당된 로더 내부에서 사용할 수 있는 속성을 나타냅니다.

Example for the loader context

다음 예제가 주어지면 require 호출이 사용됩니다.

/abc/file.js의 경우

import "./loader1?xyz!loader2!./resource?rrr";

this.addContextDependency

addContextDependency(directory: string)

로더 결과의 의존성으로 디렉터리를 추가합니다.

this.addDependency

addDependency(file: string)
dependency(file: string) // 단축

기존 파일을 감시할 수 있게 만들기 위해 로더 결과의 의존성으로 파일을 추가합니다. 예를 들어, sass-loader, less-loader는 가져온 css 파일이 변경될 때마다 이를 사용하여 재컴파일합니다.

this.addMissingDependency

addMissingDependency(file: string)

존재하지 않는 파일을 감시할 수 있게 만들기 위해 로더 결과의 의존성으로 파일을 추가합니다. addDependency와 유사하지만 감시자가 올바르게 연결되기 전에 컴파일하는 동안 파일 생성을 처리합니다.

this.addBuildDependency

addBuildDependency(file: string)

파일을 빌드 디펜던시로 추가합니다. 즉, 모듈의 결과가 의존하는 것이 아니라 로더 자체의 동작이 의존하는 것으로 등록합니다. 자체 설정 파일을 읽는 로더는 여기에 등록하여, 해당 파일이 변경될 때 지속 캐시가 무효화되도록 합니다 — cache.buildDependencies를 참고하세요.

결과의 일부가 되는 파일에는 addDependency를 사용하세요.

this.async

로더가 비동기로 콜백할 예정임을 loader-runner에 알립니다. this.callback을 반환합니다.

this.cacheable

현재 모듈의 빌드 결과를 캐시 불가능하게 표시할 수 있는 함수입니다.

cacheable(flag = true: boolean)

기본적으로 모듈의 빌드 결과는 캐시 가능으로 표시됩니다. 어떤 로더에서든 this.cacheable(false)를 호출하면 전체 모듈의 빌드 결과가 캐시 불가능으로 표시되어, 입력과 디펜던시가 변경되지 않아도 webpack이 이후 컴파일에서 모듈을 재빌드합니다. 이는 호출하는 로더의 중간 결과만이 아닌 전체 로더 체인에 적용됩니다.

this.cacheable(true) 또는 this.cacheable() 호출은 효과가 없으며, 비활성화된 후 캐시 가능성을 복원하지 않습니다.

캐시 가능한 로더는 입력과 의존성이 변경되지 않는 한 변하지 않는 결과를 가져야 합니다. 이는 로더가 this.addDependency로 지정된 것 이외의 의존성을 갖지 않아야 함을 의미합니다.

this.callback

여러 결과를 반환하기 위해 동기식 또는 비동기식으로 호출할 수 있는 함수입니다. 예상되는 인수는 다음과 같습니다.

this.callback(
  err: Error | null,
  content: string | Buffer,
  sourceMap?: SourceMap,
  meta?: any
);

1. 첫 번째 인수는 반드시 Error 또는 null이어야 합니다.
2. 두 번째 인수는 string 또는 Buffer입니다.
3. 선택적: 세 번째 인수는 이 모듈로 파싱될 수 있는 소스맵이어야 합니다.
4. 선택적: 네 번째 인수(meta)는 무엇이든 될 수 있습니다(예: 일부 메타데이터). webpack은 meta.webpackAST만 읽어 사전 파싱된 AST로 사용하며, 그 외의 모든 것은 다음 로더에 전달됩니다.

이 함수가 호출되는 경우 로더의 모호한 결과를 피하고자 undefined를 반환해야 합니다.

this.clearDependencies

clearDependencies();

로더 결과의 모든 의존성을 제거합니다. 이는 초기 의존성과 다른 로더의 의존성을 포함합니다. pitch 사용을 고려하세요.

this.context

모듈의 디렉터리. 다른 것을 해석하기 위한 컨텍스트로 사용할 수 있습니다.

이 예제에서 resource.js가 이 디렉터리에 있기 때문에 /abc가 됩니다.

this.currentRequest

string

현재 로더가 앞으로 처리해야 할 요청 부분으로, 현재 로더 자신을 포함합니다. this.loaderIndex부터 이후의 모든 로더와 리소스를 포함합니다.

예제에서: loader1에서는 '/abc/loader1.js?xyz!/abc/node_modules/loader2/index.js!/abc/resource.js?rrr', loader2에서는 '/abc/node_modules/loader2/index.js!/abc/resource.js?rrr'

this.data

로더의 pitch와 정상 실행 단계 간에 공유되는 데이터 객체입니다.

this.emitError

emitError(error: Error)

출력에도 표시될 수 있는 오류를 내보냅니다.

ERROR in ./src/lib.js (./src/loader.js!./src/lib.js)
Module Error (from ./src/loader.js):
Here is an Error!
 @ ./src/index.js 1:0-25

this.emitFile

emitFile(name: string, content: Buffer|string, sourceMap: {...}, assetInfo?: AssetInfo)

파일을 내보냅니다. 이는 webpack에 한정됩니다. 선택적 assetInfo는 buildInfo.assetsInfo에 애셋의 정보로 저장됩니다.

this.emitWarning

emitWarning(warning: Error)

다음과 같이 출력에 표시될 경고를 내보냅니다.

WARNING in ./src/lib.js (./src/loader.js!./src/lib.js)
Module Warning (from ./src/loader.js):
Here is a Warning!
 @ ./src/index.js 1:0-25

this.environment

생성된 런타임 코드에서 어떤 종류의 ES 기능을 사용할 수 있는지 확인하세요.

예시:

{
  // 화살표 함수('() => { ... }')를 지원합니다.
  "arrowFunction": true,
  // BigInt를 문자 그대로 지원합니다(예를 들어, 123n).
  "bigIntLiteral": false,
  // const 및 let 변수 선언을 지원합니다.
  "const": true,
  // destructuring을 지원합니다('{ a, b } = obj' 처럼 사용합니다).
  "destructuring": true,
  // EcmaScript 모듈을 가져오는 비동기 import() 함수를 지원합니다.
  "dynamicImport": false,
  // 현재 웹 대상에 대해서만 작업자를 만들 때 async import()를 지원합니다.
  "dynamicImportInWorker": false,
  // 'for of' 반복자를 지원합니다('for (const x of array) { ... }' 처럼 사용합니다).
  "forOf": true,
  // 'globalThis'를 지원합니다.
  "globalThis": true,
  // ECMAScript 모듈을 가져오는 ECMAScript Module syntax를 지원합니다(import ... from '...' 처럼 사용합니다).
  "module": false,
  // 옵셔널 체이닝('obj?.a' 또는 'obj?.()')을 지원합니다.
  "optionalChaining": true,
  // 템플릿 리터럴을 지원합니다.
  "templateLiteral": true
}

this.fs

compilation의 inputFileSystem 속성에 접근합니다.

this.getContextDependencies

getContextDependencies(): string[]

이 로더 실행 중 addContextDependency로 지금까지 등록된 디렉터리의 복사본입니다.

this.getDependencies

getDependencies(): string[]

이 로더 실행 중 addDependency로 지금까지 등록된 파일의 복사본입니다. 리소스 자체는 어떤 로더가 실행되기 전에 목록에 있으므로, 자신이 추가한 것만 원하는 로더는 스스로 기억해야 합니다.

this.getLogger

getLogger(name?: string): Logger

이 로더와 처리 중인 파일로 범위가 지정된 로거입니다. 로더 경로와 모듈 식별자를 접두사로 붙이는 compilation.getLogger()의 단축어입니다. 독립적인 자식 로거를 위해 name을 전달하세요. 출력이 어떻게 필터링되고 형식화되는지는 로깅을 참고하세요.

this.getMissingDependencies

getMissingDependencies(): string[]

이 로더 실행 중 addMissingDependency로 지금까지 등록된 존재하지 않는 파일의 복사본입니다.

this.getOptions(schema)

주어진 로더 옵션을 추출합니다. 선택적으로 JSON 스키마를 인수로 허용합니다.

스키마를 전달하면 webpack이 옵션을 전달하기 전에 schema-utils로 검증하므로, 잘못 입력되거나 잘못된 타입의 옵션이 조용히 무시되는 대신 보고됩니다.

my-loader.js

const schema = {
  title: "Prefix Loader options",
  type: "object",
  properties: {
    prefix: {
      type: "string",
      description: "String to prepend to each file.",
    },
  },
  additionalProperties: false,
};

export default function (source) {
  const { prefix = "" } = this.getOptions(schema);
  return `${prefix}\n${source}`;
}

오타 { loader: "./my-loader.js", options: { prefx: "// built by me" } }로 설정하면 로더를 사용하는 모듈의 빌드가 실패합니다.

ERROR in ./src/index.js
Module build failed (from ./my-loader.js):
ValidationError: Invalid options object. Prefix Loader has been initialized using an options object that does not match the API schema.
 - options has an unknown property 'prefx'. These properties are valid:
   object { prefix?: string }

이 메시지를 형성하는 두 키워드가 있습니다.

• additionalProperties: false는 인식되지 않는 옵션을 로더가 조용히 읽지 않는 것이 아닌 오류로 만드는 것입니다.
• title은 마지막 공백에서 분리됩니다. 이전 모든 것이 로더 이름을 나타내고, 마지막 단어가 검증 중인 값을 나타냅니다 — 'Prefix Loader options'가 위 메시지에서 Prefix Loader와 options has an unknown property를 넣는 것입니다. 제목 없이는 메시지가 Loader로만 시작하여 여러 로더가 체인에 있을 때 아무것도 식별하지 못합니다.

this.getResolve

getResolve(options: ResolveOptions): resolve

resolve(context: string, request: string, callback: function(err, result: string))
resolve(context: string, request: string): Promise<string>

this.resolve와 유사한 resolve 함수를 만듭니다.

Webpack resolve 옵션 아래의 모든 옵션이 가능합니다. 설정된 resolve 옵션과 병합됩니다. "..."는 resolve 옵션에서 값을 확장하기 위해 배열에서 사용할 수 있습니다(예: { extensions: [".sass", "..."] }).

options.dependencyType은 추가 옵션입니다. 이는 우리가 resolve 옵션에서 byDependency를 해석하는 데 사용되는 의존성 타입을 지정할 수 있도록 합니다.

해석 작업의 모든 의존성은 현재 모듈에 대한 의존성으로 자동 추가됩니다.

this.hot

boolean

Hot Module Replacement가 활성화되어 있는지 여부입니다 — HotModuleReplacementPlugin이 적용될 때 true이며, --hot과 devServer.hot이 이를 처리합니다.

생성된 모듈이 자체 업데이트를 처리할 수 있도록 하는 import.meta.webpackHot.accept(...) 호출을 내보내기 전에 이를 확인하여, 프로덕션 출력에 포함되지 않도록 하세요.

export default function (source) {
  const code = compile(source);

  if (!this.hot) return code;

  return `${code}
if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}`;
}

무엇을 accept하고 왜 해야 하는지는 로더 가이드의 Hot Module Replacement를 참고하세요.

this.hashDigest

string

해시를 생성할 때 사용할 인코딩입니다. output.hashDigest를 참고하세요.

this.hashDigestLength

number

사용할 해시 다이제스트의 접두사 길이입니다. output.hashDigestLength를 참고하세요.

this.hashFunction

string function

사용할 해싱 알고리즘입니다. output.hashFunction을 참고하세요.

this.hashSalt

string

Node.JS의 hash.update를 통해 해시를 업데이트하는 선택적 salt입니다. output.hashSalt를 참고하세요.

this.importModule

(request: string, options?: ImportModuleOptions) => Promise<any> (request: string, options: ImportModuleOptions | undefined, callback: (err?: Error | null, exports?: any) => void) => void

자식 컴파일러가 빌드 시 요청을 컴파일하고 실행하기 위한 대체 경량 솔루션입니다.

• request: 모듈을 로드할 요청 문자열입니다
• options:
  • baseUri: 빌드된 모듈에 사용되는 기본 URI 5.70.0+
  • layer: 이 모듈이 배치/컴파일되는 레이어를 지정합니다
  • publicPath: 빌드된 모듈에 사용되는 공개 경로입니다
• callback: 모듈의 export 또는 ESM용 네임스페이스 객체를 반환하는 선택적 Node.js 스타일 콜백 함수입니다. 콜백을 제공하지 않으면 importModule이 Promise를 반환합니다.

webpack.config.js

export default {
  module: {
    rules: [
      {
        test: /stylesheet\.js$/i,
        use: ["./a-pitching-loader.js"],
        type: "asset/source", // 로더가 문자열을 리턴하므로 타입을 'asset/source'로 설정합니다
      },
    ],
  },
};

a-pitching-loader.js

export async function pitch(remaining) {
  const result = await this.importModule(
    `${this.resourcePath}.webpack[javascript/auto]!=!${remaining}`,
  );
  return result.default || result;
}

src/stylesheet.js

import { green, red } from "./colors.js";

export default `body { background: ${red}; color: ${green}; }`;

src/colors.js

export const red = "#f00";
export const green = "#0f0";

src/index.js

import stylesheet from "./stylesheet.js";
// 스타일 시트는 빌드시 문자열 `body { background: #f00; color: #0f0; }`가 됩니다

위 예에서 다음과 같은 사실을 알 수 있습니다

1. pitching 로더가 존재합니다
2. 해당 pitching 로더에서 !=! 구문을 사용하여 요청에 대한 matchResource를 설정합니다. 즉, 원본 리소스 대신 module.rules와 일치시키기 위해 this.resourcePath + '.webpack[javascript/auto]'를 사용합니다.
3. .webpack[javascript/auto]는 .webpack[type] 패턴의 유사 확장이며, 다른 모듈 타입이 지정되지 않은 경우 기본 모듈 타입을 지정하는 데 사용합니다. 일반적으로 !=! 구문과 함께 사용됩니다.

위의 예는 단순화된 예제이므로 webpack 저장소에서 전체 예제를 확인할 수 있습니다.

this.loaderIndex

현재 로더의 로더 배열에 있는 인덱스입니다.

예제에서 loader1은 0, loader2은 1입니다.

this.loadModule

loadModule(request: string, callback: function(err, source, sourceMap, module))

주어진 요청을 모듈로 해석하고, 설정된 모든 로더를 적용하고, 생성된 소스, 소스맵 및 모듈 인스턴스(일반적으로 NormalModule의 인스턴스)로 콜백합니다. 결과를 생성하기 위해 다른 모듈의 소스 코드를 알아야 하는 경우 이 기능을 사용합니다.

로더 컨텍스트의 this.loadModule은 기본적으로 CommonJS 해석 규칙을 사용합니다. 'esm', 'commonjs' 또는 사용자 정의와 같은 다른 해석을 사용하기 전에 적절한 dependencyType과 함께 this.getResolve를 사용하세요.

this.loaders

모든 로더의 배열입니다. pitch 단계에서 쓸 수 있습니다.

loaders = [{
  request: string,
  path: string,
  query: string,
  fragment: string,
  options: object | string | undefined,
  ident: string,
  normal: function | undefined,
  pitch: function | undefined,
  raw: boolean | undefined,
  data: object | undefined,
  pitchExecuted: boolean,
  normalExecuted: boolean,
  type?: 'commonjs' | 'module'
}]

예제의 내용입니다.

[
  {
    request: "/abc/loader1.js?xyz",
    path: "/abc/loader1.js",
    query: "?xyz",
    normal: [Function],
  },
  {
    request: "/abc/node_modules/loader2/index.js",
    path: "/abc/node_modules/loader2/index.js",
    query: "",
    normal: [Function],
  },
];

this.mode

어떤 mode webpack이 실행되고 있는지 읽습니다.

가능한 값은 'production', 'development', 'none'입니다.

this.previousRequest

string

이미 처리된 로더들을 !로 연결한 것입니다 — this.loaderIndex 이전의 모든 것입니다. 리소스는 포함하지 않으며, 첫 번째 로더에서는 빈 문자열입니다.

예제에서: loader1에서는 '', loader2에서는 '/abc/loader1.js?xyz'

this.query

1. 로더가 options 객체로 설정된 경우 해당 객체를 가리킵니다.
2. 로더에 options이 없지만 쿼리 문자열로 호출된 경우 ?로 시작하는 문자열이 됩니다.

this.remainingRequest

string

현재 로더 이후의 로더들에게 남은 요청 부분입니다. this.loaderIndex 이후의 모든 로더와 리소스를 포함합니다. 이것은 pitch에 첫 번째 인수로 전달되는 값이며, -!를 접두사로 붙이는 것이 피칭 로더가 체인의 나머지를 재요청하는 방법입니다.

예제에서: loader1에서는 '/abc/node_modules/loader2/index.js!/abc/resource.js?rrr', loader2에서는 '/abc/resource.js?rrr'

this.request

해석된 요청 문자열입니다.

예제의 '/abc/loader1.js?xyz!/abc/node_modules/loader2/index.js!/abc/resource.js?rrr'

this.resolve

resolve(context: string, request: string, callback: function(err, result: string))

require 표현식과 같은 요청을 resolve(해석)합니다.

• context는 디렉터리의 절대 경로여야 합니다. 이 디렉터리는 해석을 위한 시작 위치로 사용됩니다.
• request는 해석될 요청입니다. 일반적으로 ./relative와 같은 상대 요청이나 module/path와 같은 모듈이 요청되지만 /some/path와 같은 절대 경로도 요청으로 가능합니다.
• callback은 resolve된 경로를 제공하는 일반 Node.js 스타일 콜백 함수입니다.

resolve 작업의 모든 의존성은 현재 모듈에 대한 의존성으로 자동 추가됩니다.

this.resource

쿼리를 포함한 요청의 리소스 부분입니다.

예제의 '/abc/resource.js?rrr'

this.resourceFragment

string

앞에 #을 포함한 리소스의 프래그먼트이며, 요청에 없는 경우 빈 문자열입니다. this.resource에 새 값을 할당하면 resourcePath, resourceQuery, resourceFragment로 분리됩니다.

./resource?rrr#frag 요청의 경우: '#frag'

this.resourcePath

리소스 파일입니다.

예제의 '/abc/resource.js'

this.resourceQuery

리소스의 쿼리입니다.

예제의 '?rrr'

this.rootContext

프로젝트 기본 디렉터리의 절대 경로입니다. 즉, webpack이 시작된 디렉터리가 기본값인 설정의 context 옵션입니다. 로드 중인 모듈의 디렉터리인 this.context와 달리, 컴파일의 모든 모듈에서 동일합니다.

로더가 모듈 간에 안정적인 경로가 필요할 때마다 사용하세요. 출력 이름이나 소스맵에 상대 경로를 만들거나, 프로젝트 루트 옆의 설정 파일을 찾거나, 파일이 아닌 프로젝트별로 캐시 키를 지정할 때 사용합니다.

import path from "node:path";

export default function loader(source) {
  const relative = path.relative(this.rootContext, this.resourcePath);
  // …
}

this.sourceMap

소스맵을 생성해야 하는지 여부를 알려줍니다. 소스맵을 생성하는 것은 비용이 많이 드는 작업이므로 소스맵이 실제로 요청되었는지 확인해야 합니다.

this.target

컴파일 대상입니다. 설정 옵션에서 전달됩니다.

예: 'web', 'node'

this.utils

다음 유틸리티에 접근합니다.

• absolutify: 가능한 경우 절대 경로를 사용하여 새 요청 문자열을 리턴합니다.
• contextify: 가능한 경우 절대 경로를 피하는 새 요청 문자열을 리턴합니다.
• createHash: 제공된 해시 함수에서 새 Hash 객체를 반환합니다.

my-sync-loader.js

export default function (content) {
  this.utils.contextify(
    this.context,
    this.utils.absolutify(this.context, "./index.js"),
  );
  this.utils.absolutify(this.context, this.resourcePath);
  const mainHash = this.utils.createHash(
    this._compilation.outputOptions.hashFunction,
  );
  mainHash.update(content);
  mainHash.digest("hex");
  // …
  return content;
}

this.version

로더 API 버전입니다. 현재는 2버전입니다. 이는 이전 버전과의 호환성을 제공하는 데 유용합니다. 버전을 사용하여 커스텀 동작 또는 주요 변경 사항에 대한 대체를 지정할 수 있습니다.

this.webpack

이 boolean은 webpack에 의해 컴파일될 때 true로 설정됩니다.

Webpack specific properties

로더 인터페이스는 모든 모듈 관련 정보를 제공합니다. 하지만 드물게 컴파일러 API 자체에 접근해야 할 수도 있습니다.

그러므로 최후의 수단으로만 사용해야 합니다. 이 속성들을 사용하면 로더의 범용성이 떨어집니다.

this._compilation

Webpack의 현재 Compilation 객체에 접근합니다.

this._compiler

Webpack의 현재 Compiler 객체에 접근합니다.

Deprecated context properties

this.debug

webpack에서 더 이상 설정되지 않습니다. LoaderOptionsPlugin이 debug 옵션으로 구성된 경우에만 설정되며, 해당 옵션이 로더 컨텍스트에 복사됩니다.

this.minimize

webpack에서 더 이상 설정되지 않습니다. LoaderOptionsPlugin이 minimize 옵션으로 구성된 경우에만 설정되며, 해당 옵션이 로더 컨텍스트에 복사됩니다.

this._module

로드되는 모듈 객체에 대한 hacky 접근.

Error Reporting

다음을 통해 로더 내부에서 오류를 보고할 수 있습니다.

• this.emitError를 사용합니다. 모듈의 컴파일을 중단하지 않고 오류를 보고합니다.
• throw(혹은 기타 잡히지 않는 예외)를 사용합니다. 로더가 실행되는 동안 오류가 발생하면 현재 모듈 컴파일이 실패합니다.
• callback(비동기 모드에서)를 사용합니다. 콜백에 오류를 전달하면 모듈 컴파일 실패도 발생합니다.

예시:

./src/index.js

import "./loader!./lib";

로더에서 오류가 발생하는 경우입니다.

./src/loader.js

export default function (source) {
  throw new Error("This is a Fatal Error!");
}

또는 비동기 모드에서 콜백에 오류를 전달하는 경우입니다.

./src/loader.js

export default function (source) {
  const callback = this.async();
  // ...
  callback(new Error("This is a Fatal Error!"), source);
}

모듈은 다음과 같이 번들로 제공됩니다.

/***/ "./src/loader.js!./src/lib.js":
/*!************************************!*\
  !*** ./src/loader.js!./src/lib.js ***!
  \************************************/
/*! no static exports found */
/***/ (function(module, exports) {

throw new Error("Module build failed (from ./src/loader.js):\nError: This is a Fatal Error!\n    at Object.module.exports (/workspace/src/loader.js:3:9)");

/***/ })

그후 다음 빌드 출력에도 오류가 표시됩니다(this.emitError와 유사합니다).

ERROR in ./src/lib.js (./src/loader.js!./src/lib.js)
Module build failed (from ./src/loader.js):
Error: This is a Fatal Error!
    at Object.module.exports (/workspace/src/loader.js:2:9)
 @ ./src/index.js 1:0-25

아래에서 볼 수 있듯이 오류 메시지뿐만 아니라 관련 로더 및 모듈에 대한 세부 정보도 표시됩니다.

• 모듈 경로: ERROR in ./src/lib.js
• 요청 문자열: (./src/loader.js!./src/lib.js)
• 로더 경로: (from ./src/loader.js)
• 호출자 경로: @ ./src/index.js 1:0-25

Inline matchResource

새로운 인라인 요청 구문이 webpack v4에 도입되었습니다. 요청에 접두사 <match-resource>!=!를 붙이면 이 요청에 대한 matchResource가 설정됩니다.

matchResource가 설정되면 원래 리소스 대신 module.rules와 일치하는 데 사용됩니다. 이는 리소스에 추가 로더를 적용해야 하거나 모듈 유형을 변경해야 하는 경우에 유용할 수 있습니다. 또한 통계에 표시되며 splitChunks에서 test와 Rule.issuer를 일치시키는 데 사용됩니다.

예제:

file.js

/* STYLE: body { background: red; } */
console.log("yep");

로더는 파일을 다음 파일로 변환하고 matchResource를 사용하여 사용자 지정 CSS 처리 규칙을 적용할 수 있습니다.

file.js (로더에 의해 변환되었습니다)

import "./file.js.css!=!extract-style-loader/getStyles!./file.js";

console.log("yep");

이는 extract-style-loader/getStyles!./file.js에 종속성을 추가하고 결과를 file.js.css로 처리합니다. module.rules에는 /\.css$/와 일치하는 규칙이 있고 이 종속성에 적용되기 때문입니다.

로더는 다음과 같이 보일 수 있습니다.

extract-style-loader/index.js

import getStylesLoader from "./getStyles";

export default function (source) {
  if (STYLES_REGEXP.test(source)) {
    source = source.replace(STYLES_REGEXP, "");
    return `import ${JSON.stringify(
      this.utils.contextify(
        this.context || this.rootContext,
        `${this.resource}.css!=!${getStylesLoader}!${this.remainingRequest}`,
      ),
    )};${source}`;
  }
  return source;
}

extract-style-loader/getStyles.js

export default function (source) {
  const match = source.match(STYLES_REGEXP);
  return match[0];
}

Logging

로깅 API는 webpack 4.37 릴리즈부터 사용할 수 있습니다. stats 설정에서 logging이 활성화되거나 infrastructure 로깅이 활성화되면 로더가 메세지를 기록할 수 있으며 이 메세지는 해당 로거 형식(stats, infrastructure)으로 출력됩니다.

• 로더는 this.getLogger()를 사용하는 것을 선호해야 합니다. 이는 로더 경로와 처리된 파일을 포함한 compilation.getLogger()의 단축어입니다. 이러한 종류의 로깅은 stats에 저장되고 그에 따라 형식이 지정됩니다. webpack 사용자가 필터링하고 내보낼 수 있습니다.
• 로더는 this.getLogger('name')를 사용하여 자식 이름을 가진 독립 로거를 얻을 수 있습니다. 로더 경로 및 처리된 파일은 계속 추가됩니다.
• 로더는 getLogger 방식을 지원하지 않는 이전 webpack 버전이 사용되는 경우 대체 코드를 제공하기 위해 this.getLogger ? this.getLogger() : console를 감지하는 특정한 대체 코드를 사용할 수 있습니다.

Logger Interface

로깅 출력은 최종 사용자에게 메시지를 표시하는 추가적인 방법입니다.

webpack애서 사용자 정의 로깅 API의 이점:

• 로깅 설정 표시 레벨의 공통 위치
• stats.json의 일부로 export 할 수 있는 로깅 출력입니다.
• 통계 프리셋은 로깅 출력에 영향을 줍니다.
• 플러그인이 로깅 캡처 및 표시 레벨에 영향을 줄 수 있습니다.
• 여러 플러그인 및 로더를 사용하는 경우 공통 로깅 솔루션을 사용합니다.
• CLI, webpack용 UI 도구는 로깅을 표시하는 다른 방법을 선택할 수 있습니다.
• webpack 코어는 로깅 출력을 내보낼 수 있습니다. 예) 타이밍 데이터

webpack 로깅 API를 도입함으로써 webpack 플러그인 및 로더가 로그를 내보내는 방식을 통합하고 빌드 문제를 검사하는 더 나은 방법을 제공하기를 바랍니다. 통합 로깅 솔루션은 개발 경험을 개선하여 플러그인 및 로더 개발자를 지원합니다. 대시보드 또는 기타 UI와 같은 CLI가 아닌 wepack 솔루션을 위한 기반을 마련합니다.

Examples of how to get and use webpack logger in loaders and plugins

my-webpack-plugin.js

const PLUGIN_NAME = "my-webpack-plugin";

export class MyWebpackPlugin {
  apply(compiler) {
    // 컴파일러에서 로거에 액세스 할 수 있습니다.
    const logger = compiler.getInfrastructureLogger(PLUGIN_NAME);
    logger.log("log from compiler");

    compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
      // 컴파일에서도 로거에 액세스 할 수 있습니다.
      const logger = compilation.getLogger(PLUGIN_NAME);
      logger.info("log from compilation");
    });
  }
}

my-webpack-loader.js

export default function (source) {
  // webpack 로더에서 `this.getLogger`를 사용하여 로거를 가져올 수 있습니다.
  const logger = this.getLogger("my-webpack-loader");
  logger.info("hello Logger");
  return source;
}

위의 my-webpack-plugin.js 예제에서 볼 수 있듯이, 두 가지 유형의 로깅 방법이 있습니다.

1. compilation.getLogger
2. compiler.getInfrastructureLogger

플러그인/로깅이 컴파일과 관련된 경우 compilation.getLogger를 사용하는 것이 좋으며 통계 안에 저장됩니다. 컴파일 주기 밖에서 발생하는 로깅의 경우에는 대신 compiler.getInfrastructureLogger를 사용하세요.

Logger methods

• logger.error(...): 에러 메시지용입니다.
• logger.warn(...): 경고용입니다.
• logger.info(...): 중요 정보성 메시지용입니다. 이러한 메시지는 기본적으로 표시됩니다. 사용자가 실제로 봐야하는 메시지에만 사용합니다.
• logger.log(...): 중요하지 않은 정보성 메시지용입니다. 이러한 메시지는 사용자가 볼 수 있도록 선택한 경우에만 표시됩니다.
• logger.debug(...): 디버깅 정보용입니다. 이러한 메시지는 사용자가 특정 모듈에 대한 디버그 로깅을 보기로 선택한 경우에만 표시됩니다.
• logger.trace(): 스택 추적을 표시하기 위해 사용합니다. logger.debug처럼 표시됩니다.
• logger.group(...): 메시지를 그룹화하기 위해 사용합니다. logger.log처럼 접힌 채로 표시됩니다.
• logger.groupEnd(): 로깅 그룹을 종료하기 위해 사용합니다.
• logger.groupCollapsed(...): 메시지를 함께 그룹화하기 위해 사용합니다. logger.log처럼 접힌 채로 표시됩니다. 로깅 수준이 'verbose' 나 'debug'로 설정된 경우 확장되어 표시됩니다.
• logger.status: 임시 메시지를 작성하고, 새 상태를 설정하고, 이전 메시지를 재정의합니다.
• logger.clear(): 수평 라인을 출력합니다. logger.log처럼 표시됩니다.
• logger.profile(...), logger.profileEnd(...): 프로파일을 캡처하기 위해 사용합니다. 지원되는 경우 console.profile에 위임됩니다.

Runtime Logger API

런타임 로거 API는 개발 도구로만 사용할 수 있고 프로덕션 모드에 포함할 수 없습니다.

• import logging from 'webpack/lib/logging/runtime': 런타임에서 로거를 사용하려면 webpack에서 직접 require 해야 합니다.
• logging.getLogger('name'): 이름으로 개별 로거를 가져오기 위해 사용합니다.
• logging.configureDefaultLogger(...): 기본 로거를 재정의합니다.

import logging from "webpack/lib/logging/runtime";

logging.configureDefaultLogger({
  level: "log",
  debug: /something/,
});

• logging.hooks.log: 런타임 로거에 플러그인을 적용하기 위해 사용합니다.

Module Methods

이 섹션에서는 webpack으로 컴파일된 코드에서 사용할 수 있는 모든 메서드를 다룹니다. Webpack을 사용하여 애플리케이션을 번들할 때 ES6, CommonJS 및 AMD와 같은 여러 가지 구문 스타일 중 선택할 수 있습니다.

Webpack은 여러 모듈 구문을 지원하지만, 일관성을 유지하고 이상한 동작이나 버그를 피하려면 단일 구문을 따르는 것이 좋습니다. 실제로 webpack은 가장 가까운 상위 package.json 파일에 값이 "module" 이거나 commonjs인 "type" 필드가 포함된 경우, .mjs 파일, .cjs 파일 또는 .js 파일에 대한 권장 사항을 적용합니다. 계속해서 읽기 전에 다음 적용 사항을 알아보세요.

• package.json에 "type": "module"이 있는 .mjs 또는 .js.
  • CommonJS가 허용되지 않습니다. 예를 들면 require, module.exports 또는 exports를 사용할 수 없습니다.
  • 가져올 때 파일 확장자가 필요합니다. 예를 들어 import './src/App' 대신에 import './src/App.mjs'를 사용해야 합니다. (Rule.resolve.fullySpecified를 사용하여 이 사항을 비활성화할 수 있습니다.)
• package.json에 "type": "commonjs"가 있는 .cjs 또는 .js.
  • import도 export도 사용할 수 없습니다.
• package.json에 "type": "module"이 있는 .wasm.
  • wasm 파일을 가져올 때 파일 확장자가 필요합니다.

ES6 (Recommended)

Webpack 버전 2는 기본적으로 ES6 모듈 구문을 지원합니다. 즉, babel과 같은 도구 없이 import 및 export를 사용하여 이를 처리할 수 있습니다. 다른 ES6+ 기능에는 여전히 babel이 필요할 수 있습니다. Webpack이 지원하는 메서드는 다음과 같습니다.

import

다른 모듈의 export를 정적으로 import 합니다.

import MyModule from "./my-module.js";
import { NamedExport } from "./other-module.js";

Data URI를 import 할 수도 있습니다.

import "data:text/javascript;charset=utf-8;base64,Y29uc29sZS5sb2coJ2lubGluZSAxJyk7";
import {
  fn,
  number,
} from "data:text/javascript;charset=utf-8;base64,ZXhwb3J0IGNvbnN0IG51bWJlciA9IDQyOwpleHBvcnQgY29uc3QgZm4gPSAoKSA9PiAiSGVsbG8gd29ybGQiOw==";

export

무엇이든 default 또는 이름이 지정된 내보내기로 내보냅니다.

// 이름이 지정된 내보내기
export const Count = 5;
export function Multiply(a, b) {
  return a * b;
}

// 기본 내보내기
export default {
  // 데이터...
};

import()

(path: string) => Promise<any>

모듈을 동적으로 로드합니다. import()에 대한 호출은 분할 지점으로 처리됩니다. 즉, 요청된 모듈과 그 자식은 별도의 청크로 분할됩니다.

if (module.hot) {
  import("lodash").then((_) => {
    // lodash(일명 '_')로 작업 수행...
  });
}

Dynamic expressions in import()

import(foo)와 같은 완전히 동적인 import 문을 사용하는 것은 불가능합니다. foo는 잠재적으로 시스템이나 프로젝트의 모든 파일에 대한 경로가 될 수 있기 때문입니다.

import()는 최소한 모듈 위치에 대한 정보를 포함해야 합니다. 번들링은 특정 디렉터리 또는 파일 집합으로 제한될 수 있습니다. 그러므로 동적 표현 식을 사용할 때 import() 호출 시 잠재적으로 요청 가능한 모든 모듈이 포함됩니다. 예를 들어, import(`./locale/${language}.json`)는 ./locale 디렉터리와 하위 디렉터리에 있는 모든 .json 파일만 새 청크로 묶고 다른 파일 확장자를 가진 파일은 제외합니다. 런타임에 language 변수가 계산되면 english.json이나 german.json과 같은 모든 파일을 사용할 수 있습니다.

// 쿠키나 다른 저장소에서 언어를 가져오는 방법이 있다고 상상해 보세요.
const language = detectVisitorLanguage();
import(`./locale/${language}.json`).then((module) => {
  // 번역과 관련된 작업을 수행합니다.
});

완전히 동적인 import(foo)는 오류가 아닙니다 — webpack은 여전히 이를 위해 컨텍스트 모듈을 생성하지만 비어있는 상태입니다. 빌드 시 Critical dependency: the request of a dependency is an expression을 보고하며, 해당 호출에 대해 아무것도 번들하지 않고 반환된 프로미스는 런타임에 거부됩니다. 파서가 어떤 파일이 요청될 수 있는지 알 수 없고, 표현식이 해석될 수 있는 모든 파일을 포함하는 것은 거의 원하는 바가 아니기 때문에 아무것도 포함되지 않습니다.

원하는 경우, 모듈 컨텍스트 옵션을 사용하여 활성화할 수 있습니다 — exprContextRequest는 탐색할 디렉터리, exprContextRegExp는 그 안의 파일 선택, exprContextRecursive는 서브디렉터리 포함 여부를 결정하며, exprContextCritical은 경고를 제어합니다.

export default {
  module: {
    parser: {
      javascript: {
        // bundle every module below the importing directory
        exprContextRegExp: /^\.\/.*$/,
        exprContextCritical: false,
      },
    },
  },
};

Magic Comments

가져오기에 주석을 추가하여 청크의 이름을 지정하거나 다른 모드를 선택하는 등의 여러 작업을 할 수 있습니다. 이 특별한 주석의 전체 목록과 주석이 수행하는 작업은 아래 코드와 설명을 참고하세요.

// 단일 대상
import(
  /* webpackChunkName: "my-chunk-name" */
  /* webpackMode: "lazy" */
  /* webpackExports: ["default", "named"] */
  /* webpackFetchPriority: "high" */
  "node:module"
);

// 여러 가능한 대상
import(
  /* webpackInclude: /\.json$/ */
  /* webpackExclude: /\.noimport\.json$/ */
  /* webpackChunkName: "my-chunk-name" */
  /* webpackMode: "lazy" */
  /* webpackPrefetch: true */
  /* webpackPreload: true */
  `./locale/${language}`
);

import(/* webpackIgnore: true */ "ignored-module.js");

webpackIgnore

JavaScript Usage

true로 설정하면 동적 import 구문 파싱을 비활성화합니다.

import.meta.url을 사용할 때, 그대로 유지되지 않고, 대신 baseURI에 따라 대체됩니다. 모듈의 경우 new URL("./", import.meta.url)로 대체되고, 다른 경우에는 document.baseURI로 기본 설정됩니다. 이렇게 하면 기본 URL 컨텍스트에 맞게 상대 URL이 올바르게 작동합니다.

import(/* webpackIgnore: true */ "ignored-module.js");

new URL(/* webpackIgnore: true */ "./file1.css", import.meta.url);

CSS Usage

webpackIgnore 주석은 webpack이 특정 가져오기 또는 URL 참조를 처리할지 여부를 제어할 수 있습니다. 특정 경우에는 바로 사용할 수 있지만 성능상의 이유로 모든 경우를 지원하지는 않습니다.

다음의 경우에는 webpackIgnore를 지원합니다:

@import /* webpackIgnore: false */ url(./basic.css);

.class {
  color: red;
  background: /* webpackIgnore: true */ url("./url/img.png");
}

.class {
  background-image: image-set(
    /*webpackIgnore:  true*/ url(./url/img1x.png) 1x,
    url(./url/img2x.png) 2x,
    url(./url/img3x.png) 3x
  );
}

HTML Usage

experiments.html을 활성화하면 태그 바로 앞에 webpackIgnore HTML 주석을 추가하여 해당 태그의 src, href, srcset 및 유사한 속성의 URL 리졸브를 건너뛸 수 있습니다. 내보낸 HTML에서도 태그를 변경하지 않습니다.

<!-- webpackIgnore: true -->
<img src="https://cdn.example.com/logo.png" />

<!-- webpackIgnore: true -->
<script src="/legacy/external.js"></script>

magic comment 값은 JS 및 CSS parser가 사용하는 것과 동일한 context로 파싱되며, boolean이 아닌 값은 UnsupportedFeatureWarning을 발생시킵니다.

webpackChunkName

새 청크의 이름입니다. Webpack 2.6.0부터 플레이스홀더 [index]와 [request]는 주어진 문자열 내에서 증가된 숫자 또는 실제 확인된 파일 이름으로 각각 지원합니다. 이 주석을 추가하면 개별 청크 이름이 [id].js 대신 [my-chunk-name].js로 지정됩니다.

webpackFetchPriority

특정 동적 import에 대한 fetchPriority를 설정합니다. module.parser.javascript.dynamicImportFetchPriority 옵션을 사용하여 모든 동적 import에 전역 기본값을 설정할 수도 있습니다.

import(
  /* webpackFetchPriority: "high" */
  "path/to/module"
);

webpackMode

Webpack 2.6.0부터 동적 import를 해석하기 위한 다른 모드를 지정할 수 있습니다. 다음 옵션이 지원됩니다.

• 'lazy' (기본값): 각 import()된 모듈에 대해 지연 로드 가능한 청크를 생성합니다.
• 'lazy-once': import()에 대한 모든 호출을 만족시킬 수 있는 단일 지연 로드 가능 청크를 생성합니다. 청크는 import()에 대한 첫 번째 호출에서 가져오고, import()에 대한 후속 호출은 동일한 네트워크 응답을 사용합니다. 이것은 잠재적으로 요청 가능한 복수의 모듈 경로가 있는 import(`./locales/${language}.json`)와 같은 부분 동적 문일 경우에만 의미가 있습니다.
• 'eager': 추가 청크를 생성하지 않습니다. 모든 모듈은 현재 청크에 포함되며 추가 네트워크 요청은 발생하지 않습니다. 이미 해석된 Promise가 반환됩니다. 정적 가져오기와 달리 모듈은 import()가 호출될 때까지 실행되지 않습니다. 청크가 생성되지 않으므로 webpackChunkName은 이 모드에서 효과가 없습니다 — 모듈을 별도 청크에 넣으려면 'lazy' 또는 'lazy-once'를 사용하세요.
• 'weak': 모듈 함수가 이미 다른 방식으로 로드된 경우 모듈 로드를 시도합니다(예: 다른 청크가 이를 가져왔거나 모듈을 포함하는 스크립트가 로드된 경우). Promise가 여전히 반환되지만 청크가 이미 클라이언트에 있는 경우에만 성공적으로 해석됩니다. 모듈을 사용할 수 없으면 Promise가 거부됩니다. 네트워크 요청은 발생하지 않습니다. 이는 필요한 청크가 초기 요청에서 항상 수동으로 제공되는 (페이지에 내장된 경우) 범용 렌더링에 유용합니다. 하지만 앱 탐색이 초기에 제공되지 않은 가져오기를 트리거 하는 경우에는 유용하지 않습니다.

webpackPrefetch

향후 탐색에 리소스가 필요할 수 있음을 브라우저에 알립니다. webpackPrefetch 작동 방식에 대한 자세한 내용은 가이드를 확인하세요.

webpackPreload

현재 탐색 중에 리소스가 필요할 수 있음을 브라우저에 알립니다. webpackPreload 작동 방식에 대한 자세한 내용은 가이드를 확인하세요.

webpackInclude

가져오기 해석 중 일치하는지 확인할 정규식입니다. 일치하는 모듈만 번들로 제공됩니다.

webpackExclude

가져오기 해석 중 일치하는지 확인할 정규식입니다. 일치하는 모듈은 번들로 제공되지 않습니다.

webpackExports

webpackExports: 동적으로 import()된 모듈의 지정된 내보내기만 번들로 묶도록 webpack에 지시합니다. 청크의 출력 크기를 줄일 수 있습니다. webpack 5.0.0-beta.18부터 사용 가능합니다.

CommonJS

CommonJS의 목표는 브라우저 외부에서 JavaScript용 생태계를 지정하는 것입니다. Webpack에서 지원하는 CommonJS 메서드는 다음과 같습니다.

require

require(dependency: String);

다른 모듈의 내보내기를 동기적으로 검색합니다. 컴파일러는 출력 번들에서 의존성을 사용할 수 있는지 확인합니다.

import $ from "jquery";
import myModule from "my-module";

require에 대한 특별한 주석도 활성화할 수 있습니다. 자세한 내용은 module.parser.javascript.commonjsMagicComments를 참고하세요.

require.resolve

require.resolve(dependency: String);

모듈의 ID를 동기적으로 검색합니다. 컴파일러는 출력 번들에서 의존성을 사용할 수 있는지 확인합니다. require.cache[id] 또는 __webpack_require__(id)와 함께 사용할 수 있는 불투명 값으로 처리하는 것이 좋습니다 (이러한 사용을 피하는 것이 가장 좋습니다).

자세한 내용은 module.id를 참고하세요.

require.cache

동일한 모듈을 여러 번 require 하면 모듈이 한 번만 실행되고 하나의 내보내기만 발생합니다. 따라서 런타임에 캐시가 존재합니다. 이 캐시에서 값을 제거하면 새 모듈이 실행되고 새 내보내기가 발생합니다.

import d1 from "dependency";

// In ESM, module caching is handled automatically.
// Manual cache deletion like in CommonJS is not supported.
if (import.meta.webpackHot) {
  import.meta.webpackHot.accept("dependency", (newModule) => {
    // Handle module update here
  });
}

// file.js에서
// ESM에서는 수동 캐시 조작이 지원되지 않습니다.
// Webpack은 모듈 캐싱을 내부적으로 처리합니다.

require.ensure

require.ensure(
  dependencies: String[],
  callback: function(require),
  errorCallback: function(error),
  chunkName: String
)

비동기식으로 로드될 지정된 dependencies를 별도의 번들로 분할합니다. CommonJS 모듈 구문을 사용할 때 이것은 의존성을 동적으로 로드하는 유일한 방법입니다. 즉, 이 코드는 작업 중에 실행될 수 있으며 특정 조건이 충족되는 경우에만 dependencies를 로드합니다.

const a = require("normal-dep");

if (module.hot) {
  import("b").then(() => {
    import("c").then((c) => {
      // 특별한 작업을 수행...
    });
  });
}

다음 파라미터는 위에서 지정한 순서대로 지원됩니다.

• dependencies: callback의 코드 실행에 필요한 모든 모듈을 선언하는 문자열 배열입니다.
• callback: 의존성이 로드되면 webpack이 실행할 함수입니다. require 함수 구현은 이 함수에 대한 파라미터로 전송됩니다. 함수 본문은 이것을 사용하여 실행에 필요한 추가 require() 모듈을 사용할 수 있습니다.
• errorCallback: Webpack이 의존성을 불러오지 못했을 때 실행되는 함수입니다.
• chunkName: 특별히 이 require.ensure()에 의해 생성된 청크에 부여된 이름입니다. 다양한 require.ensure() 호출에 동일한 chunkName을 전달하면 해당 코드를 단일 청크로 결합할 수 있으므로 브라우저에서 로드하는 번들이 하나만 생성됩니다.

AMD

비동기 모듈 정의(AMD)는 모듈을 작성하고 로드하기 위한 인터페이스를 정의하는 JavaScript 사양입니다. Webpack은 다음과 같은 AMD 메서드를 지원합니다.

define (with factory)

define([name: String], [dependencies: String[]], factoryMethod: function(...))

dependencies가 제공되면 factoryMethod가 각 의존성의 내보내기와 함께 같은 순서로 호출됩니다. dependencies가 제공되지 않으면 factoryMethod가 require, exports 및 module과 함께 호출됩니다(호환성을 위함입니다!). 이 함수가 값을 반환하면 모듈에서 이 값을 내보냅니다. 컴파일러는 각 의존성을 사용할 수 있는지 확인합니다.

define(["jquery", "my-module"], ($, myModule) =>
  // $와 myModule로 작업을 수행하세요...

  // 함수 내보내기
  function doSomething() {
    // ...
  });

define (with value)

define(value: !Function)

제공된 value를 내보냅니다. 여기서 value는 함수를 제외한 모든 것이 될 수 있습니다.

define({
  answer: 42,
});

require (amd-version)

require(dependencies: String[], [callback: function(...)])

require.ensure와 유사하게, 주어진 dependencies를 비동기식으로 로드되는 별도의 번들로 분할합니다. callback은 dependencies 배열의 각 종속성을 내보낼 때 호출됩니다.

import("b").then((b) => {
  import("c").then((c) => {
    // b और c का इस्तेमाल करें
  });
});

Webpack

위에서 설명한 모듈 구문 외에도 webpack에 한정된 몇가지 사용자 정의 메서드를 허용합니다.

require.context

require.context(
  (directory: String),
  (includeSubdirs: Boolean) /* 선택, 기본값 true */,
  (filter: RegExp) /* 선택, 기본값 /^\.\/.*$/, 모든 파일 */,
  (mode: String) /* 선택, 'sync' | 'eager' | 'weak' | 'lazy' | 'lazy-once', 기본값 'sync' */
);

directory에 대한 경로, includeSubdirs 옵션, 포함된 모듈을 좀 더 세밀하게 제어하기 위한 filter, 로드 작동 방식을 정의하는 mode를 사용하여 전체 의존성 그룹을 지정합니다. 그러면 기본 모듈은 나중에 해석할 수 있습니다.

const context = import.meta.webpackContext("components", {
  recursive: true,
  regExp: /\.html$/,
});
const componentA = context.resolve("componentA");

mode가 'lazy'로 설정되면 기본 모듈이 비동기식으로 로드됩니다.

const context = import.meta.webpackContext("locales", {
  recursive: true,
  regExp: /\.json$/,
  mode: "lazy",
});
context("localeA").then((locale) => {
  // locale로 작업을 수행
});

사용 가능한 모드의 전체 목록과 그 동작은 import() 문서에 설명되어 있습니다.

require.include

require.include((dependency: String));

실행하지 않고 dependency를 포함합니다. 출력 청크에서 모듈의 위치를 최적화하는 데 사용할 수 있습니다.

import("a");
import("b");
import("c").then((moduleC) => {
  // Use moduleC here
});

결과는 다음과 같습니다.

• 엔트리 청크: file.js 와 a
• 익명 청크: b
• 익명 청크: c

require.include('a')가 없으면 두 익명 청크에 복제됩니다.

require.resolveWeak

require.resolve와 유사하지만, module을 번들로 가져오지 않습니다. 이것은 "약한" 의존성으로 간주합니다.

if (__webpack_modules__[require.resolveWeak("module")]) {
  // 모듈을 사용할 수 있을 때 수행...
}
if (require.cache[require.resolveWeak("module")]) {
  // 이전에 모듈이 로드된 경우 수행...
}

// 동적 해석("context")을 수행할 수 있습니다.
// 다른 require/import 메서드와 유사합니다.
const page = "Foo";
__webpack_modules__[require.resolveWeak(`./page/${page}`)];

warning

모듈 소스에 정적으로 분석할 수 없는 요구 사항이 포함되어 있으면, 중요한 종속성 경고가 표시됩니다.

예제 코드:

someFn(require);
require.bind(null);
require(variable);

Module Variables