Module Variables

이 섹션에서는 webpack으로 컴파일된 코드에서 사용할 수 있는 모든 변수를 다룹니다. 모듈은 module 및 기타 변수를 통해 컴파일 프로세스의 특정 데이터에 접근할 수 있습니다.

module.loaded (NodeJS)

모듈이 현재 실행 중이면 false이고, 실행이 완료되면 true입니다.

module.hot (webpack-specific)

Hot Module Replacement가 활성화되었는지 여부를 나타내며 프로세스를 위한 인터페이스를 제공합니다. 자세한 내용은 HMR API 페이지를 참고하세요.

module.id (CommonJS)

현재 모듈의 ID입니다.

console.log(import.meta.url);

export default

소비자가 모듈에 import 호출을 할 때 반환될 값을 정의합니다(기본값은 새 객체).

export default function doSomething() {
  // 작업을 수행합니다...
}

exports (CommonJS)

명명된 내보내기를 사용하면 단일 모듈에서 여러 변수, 함수 또는 객체를 내보낼 수 있습니다. 기본 내보내기와 달리 이러한 값을 가져올 때는 정확한 이름을 사용해야 합니다.

export const someValue = 42;
export const anObject = {
  x: 123,
};
export function doSomething() {
  // 작업을 수행합니다
}

global (NodeJS)

node.js global을 참고하세요.

호환성을 위해 webpack은 기본적으로 global 변수를 폴리필합니다.

__dirname (NodeJS)

설정 옵션 node.__dirname에 따라 다릅니다.

• false: 정의되지 않음
• true: 컴파일러 context에 상대적인 모듈의 디렉터리
• 'mock': '/'와 같음
• 'warn-mock': '/'와 같음, 경고와 함께
• 'node-module': ES 모듈 출력에서 import.meta.url (또는 지원되는 경우 import.meta.dirname)에서 파생
• 'eval-only': Node.js가 런타임에 평가하도록 남겨둠

Node.js와 유사한 타겟의 경우 기본값은 'eval-only'이며, 그 외에는 'mock'입니다.

파서에 의해 파싱되는 표현식 내부에서 사용되는 경우, 설정 옵션은 true로 처리됩니다.

import.meta

import.meta는 모듈의 URL과 같은 컨텍스트별 메타데이터를 JavaScript 모듈에 노출합니다. ESM에서만 사용할 수 있습니다.

import.meta에 대한 직접 접근이 지원됩니다. webpack은 이를 알려진 속성(url, webpack, main, env 등)의 객체로 대체합니다. module.parser.javascript.importMeta가 'preserve-unknown' 또는 객체로 설정되지 않은 경우, 알 수 없는 속성은 undefined입니다.

Object.keys(import.meta); // e.g. ['url', 'webpack', 'main', 'env']

console.log(import.meta.url);
const { url } = import.meta;

import.meta.url

모듈의 절대 file: URL을 반환합니다.

src/index.js

console.log(import.meta.url); // `file:///path/to/your/project/src/index.js`와 같은 출력

import.meta.webpack

webpack 버전을 반환합니다.

src/index.js

console.log(import.meta.webpack); // webpack 5의 경우 `5` 출력

import.meta.webpackHot

Webpack 특유의 속성입니다. module.hot의 별칭으로, import.meta.webpackHot은 strict ESM에서 사용할 수 있지만 module.hot은 할 수 없습니다.

import.meta.webpackContext

require.context와 동일한 값을 반환하지만 javascript/auto 및 javascript/esm에 대해서만 반환합니다.

• Type:

  Copy

  (
    request: string,
    options?: {
      recursive?: boolean;
      regExp?: RegExp;
      include?: RegExp;
      exclude?: RegExp;
      preload?: boolean | number;
      prefetch?: boolean | number;
      chunkName?: string;
      exports?: string | string[][];
      mode?: "sync" | "eager" | "weak" | "lazy" | "lazy-once";
    },
  ) => webpack.Context;

• Available: 5.70.0+

• Example:

  Copy

  const contextRequire = import.meta.webpackContext(".", {
    recursive: false,
    regExp: /two/,
    mode: "weak",
    exclude: /three/,
  });

import.meta.main

현재 모듈이 엔트리 포인트인지 여부를 나타내는 부울 값을 반환합니다.

src/index.js (엔트리 포인트)

console.log(import.meta.main); // true

src/utils.js (엔트리 포인트가 아닙니다)

console.log(import.meta.main); // false

이는 Node.js의 require.main === module 검사와 유사하게, 진입 모듈에서만 실행되어야 하는 조건부 로직에 유용합니다.

import.meta.env

다양한 소스에서 환경 변수에 접근할 수 있습니다. import.meta.env는 process.env와 유사하게 동작하는 객체로, 다양한 webpack 플러그인 및 구성 옵션을 통해 정의된 환경 변수에 접근할 수 있도록 해줍니다.

webpack.config.js

import webpack from "webpack";

export default {
  mode: "production", // NODE_ENV는 자동으로 "production"으로 설정됩니다.
  dotenv: {
    prefix: "WEBPACK_", // WEBPACK_ 접두사가 붙은 변수만 노출합니다.
  },
  plugins: [
    // EnvironmentPlugin은 process.env의 변수를 노출합니다.
    new webpack.EnvironmentPlugin({
      API_URL: "https://api.example.com",
    }),
    // DefinePlugin은 사용자 정의 정의를 허용합니다.
    new webpack.DefinePlugin({
      "import.meta.env.CUSTOM_VAR": JSON.stringify("custom_value"),
    }),
  ],
};

src/index.js

// 환경 변수에 접근
console.log(import.meta.env.NODE_ENV); // "production" (모드에서 가져옴)
console.log(import.meta.env.API_URL); // EnvironmentPlugin 또는 process.env의 값
console.log(import.meta.env.CUSTOM_VAR); // "custom_value"(DefinePlugin에서 가져옴)

// 타입 검사
console.log(typeof import.meta.env); // "object"

// 참 같은 값 검사
if (import.meta.env) {
  // import.meta.env는 참 같은 값입니다.
}

// 존재하지 않는 속성에 접근하면 undefined가 반환됩니다.
if (!import.meta.env.NOT_EXIST) {
  // NOT_EXIST는 정의되지 않았거나 거짓입니다.
}

// 구조 분해 할당
const { NODE_ENV, API_URL } = import.meta.env;

환경 변수의 출처:

1. mode 옵션: webpack 모드(development, production 또는 none)에 따라 import.meta.env.NODE_ENV를 자동으로 설정합니다.

2. EnvironmentPlugin: process.env의 변수를 노출하거나 기본값을 제공합니다.

3. DotenvPlugin: .env 파일에서 변수를 로드합니다. 지정된 접두사(기본값: WEBPACK_)가 있는 변수만 노출됩니다.

4. DefinePlugin: "import.meta.env.*" 패턴을 사용하여 사용자 정의를 허용합니다.

import.meta.env는 process.env와 유사하게 동작합니다. 객체이며 typeof 검사를 지원하고, 존재하지 않는 속성에 접근하면 undefined를 반환합니다.

webpack 5.109.0부터 다음 상수들이 기본으로 정의됩니다(optimization.nodeEnv에서 파생되므로 optimization.nodeEnv: false가 아닌 한 사용할 수 있습니다).

• import.meta.env.MODE: mode의 값입니다(import.meta.env.NODE_ENV와 동일).
• import.meta.env.DEV: development mode에서는 true, 그 외에는 false입니다.
• import.meta.env.PROD: DEV의 부정값입니다.
• import.meta.env.SSR: server-only build(browser target이 아닌 Node.js target)에서는 true입니다.
• import.meta.env.BASE_URL: output.publicPath의 값이며, publicPath가 비어 있거나 'auto'이면 '/'로 fallback합니다.

import.meta.env 평가는 importMeta parser 옵션(importMeta: { env: false })으로 끌 수 있습니다.

import.meta.resolve

native import.meta.resolve처럼 module specifier를 URL로 resolve합니다. specifier가 번들된 asset을 가리키면 webpack은 build time에 호출을 emit된 asset URL로 대체합니다.

const assetUrl = import.meta.resolve("./logo.png");

평가는 importMeta.resolve parser 옵션으로 제어합니다.

import.meta.glob

glob pattern으로 여러 module을 한 번에 import합니다. 일치하는 각 file path를 dynamic import 함수에 매핑하는 object를 반환하며, 일치한 module은 기본적으로 on-demand chunk로 분리됩니다.

const modules = import.meta.glob("./pages/*.js");
// {
//   "./pages/about.js": () => import("./pages/about.js"),
//   "./pages/home.js": () => import("./pages/home.js"),
// }

for (const path in modules) {
  modules[path]().then((mod) => console.log(path, mod));
}

pattern(string 또는 string 배열, ! 접두사가 붙은 negative pattern 지원)과 options object는 모두 literal이어야 합니다. 지원되는 옵션:

• eager (boolean = false): dynamic import 함수를 반환하는 대신 module을 정적으로 import합니다. 값은 module namespace 자체입니다.
• import (string): 각 module에서 단일 export(예: 'default')를 선택하여 더 나은 tree shaking을 가능하게 합니다.
• query (string | object): 각 request에 query를 추가합니다. 예: { query: '?raw' }.
• base (string): pattern을 다른 base directory를 기준으로 resolve합니다. 결과 object의 key는 이 directory에 상대적입니다.
• exhaustive (boolean = false): node_modules와 hidden directory 안의 파일도 매치합니다.
• caseSensitive (boolean = true): 비활성화하면 path를 대소문자 구분 없이 매치합니다.

const icons = import.meta.glob("./icons/*.svg", {
  eager: true,
  import: "default",
  query: "?url",
});

__filename (NodeJS)

설정 옵션 node.__filename에 따라 다릅니다.

• false: 정의되지 않음
• true: 컴파일러 context에 상대적인 모듈의 경로
• 'mock': '/index.js'와 같음
• 'warn-mock': '/index.js'와 같음, 경고와 함께
• 'node-module': ES 모듈 출력에서 import.meta.url (또는 지원되는 경우 import.meta.filename)에서 파생
• 'eval-only': Node.js가 런타임에 평가하도록 남겨둠

Node.js와 유사한 타겟의 경우 기본값은 'eval-only'이며, 그 외에는 'mock'입니다.

파서에 의해 파싱되는 표현식 내부에서 사용되는 경우, 설정 옵션은 true로 처리됩니다.

__resourceQuery (webpack-specific)

현재 모듈의 리소스 쿼리입니다. 만약 다음과 같은 import 호출이 이루어졌다면, 쿼리 문자열은 file.js 파일에서 확인할 수 있습니다.

import "file.js?test";

file.js

__resourceQuery === "?test";

__webpack_public_path__ (webpack-specific)

설정 옵션의 output.publicPath와 동일합니다.

__webpack_require__ (webpack-specific)

원시 요청 함수입니다. 이 표현식은 파서에 의해 의존성이 파싱되지 않습니다.

__webpack_chunk_load__ (webpack-specific)

내부 청크 로딩 함수. 하나의 인수를 가집니다.

• chunkId는 로드할 청크의 ID입니다.

하나가 실패했을 때 대체 퍼블릭 경로에서 청크를 로드하는 예제입니다.

const originalLoad = __webpack_chunk_load__;
const publicPaths = ["a", "b", "c"];
__webpack_chunk_load__ = async (id) => {
  let error;
  for (const path of publicPaths) {
    __webpack_public_path__ = path;
    try {
      return await originalLoad(id);
    } catch (err) {
      error = err;
    }
  }
  throw error;
};
import("./module-a").then((moduleA) => {
  // 이제 webpack은 사용자 정의 __webpack_chunk_load__ 를 사용하여 청크를 로드합니다.
});

__webpack_module__ (webpack-specific)

현재의 모듈에 접근할 수 있습니다. 엄격한 ESM에서는 모듈을 사용할 수 없습니다.

__webpack_module__.id (webpack-specific)

현재 모듈(module.id)의 ID에 접근할 수 있습니다. 엄격한 ESM에서는 모듈을 사용할 수 없습니다.

__webpack_modules__ (webpack-specific)

모든 모듈의 내부 객체에 대한 접근을 제공합니다.

__webpack_hash__ (webpack-specific)

컴파일의 해시에 대한 접근을 제공합니다.

__webpack_layer__ (webpack-specific)

string | null

현재 모듈이 배치된 레이어, 또는 레이어가 없는 경우 null입니다. webpack은 빌드 시 이를 리터럴로 대체하므로 런타임 비용 없이 비교하거나 분기할 수 있으며, typeof __webpack_layer__도 정적으로 평가됩니다.

if (__webpack_layer__ === "server") {
  // only kept in modules built in the "server" layer
}

__webpack_nonce__ (webpack-specific)

string

Content Security Policy 하에 서비스되는 페이지를 위해 webpack이 주입하는 모든 스크립트 태그에 설정하는 nonce입니다. 청크가 로드되기 전에 한 번 할당하세요.

__webpack_nonce__ = "2726c7f26c";

__webpack_chunkname__ (webpack-specific)

string

현재 런타임이 속한 청크의 이름입니다.

__webpack_init_sharing__ (webpack-specific)

function

공유 스코프를 초기화하고 이 빌드가 제공하는 공유 모듈로 채웁니다. 프로미스를 반환하며 스코프 이름을 인수로 받습니다.

await __webpack_init_sharing__("default");

__webpack_share_scopes__ (webpack-specific)

object

이 빌드가 알고 있는 공유 스코프로, 스코프 이름으로 키가 지정됩니다. 스코프를 초기화한 후 원격 컨테이너의 init()에 전달하는 것입니다 — 동적 원격 컨테이너를 참고하세요.

__system_context__ (webpack-specific)

object

output.libraryTarget: 'system'으로 빌드할 때 사용할 수 있는 System.register 컨텍스트입니다.

__webpack_css_server_styles__ (webpack-specific)

string

DOM 없이 렌더링하는 동안 수집한 CSS를 하나의 문자열로 반환합니다. 내장 CSS 지원(experiments.css)이 server-side rendering처럼 <style>을 삽입할 document가 없는 환경에서 실행되면 webpack은 style을 전역 registry에 기록합니다. 이 변수는 style이 적용된 순서대로 registry를 읽어 서버가 전송하는 HTML에 인라인으로 삽입할 수 있게 합니다.

import { renderToString } from "react-dom/server";
import App from "./App.js";

export function render() {
  const html = renderToString(<App />);
  // render가 가져온 모든 스타일시트를 적용 순서대로 반환
  const css = __webpack_css_server_styles__;

  return `<!doctype html><html><head><style>${css}</style></head><body>${html}</body></html>`;
}

registry는 style 식별자를 key로 사용하고 output.uniqueName으로 namespace를 지정하므로, 같은 프로세스에서 렌더링되는 여러 번들이 서로의 style을 읽지 않습니다.

__webpack_get_script_filename__ (webpack-specific)

(chunkId: string | number) => string

id로 청크의 파일 이름을 제공합니다.

할당 가능하기 때문에 런타임에서 사용하는 파일 이름을 변경할 수 있습니다. 예를 들면 청크를 로드할 때 최종 경로를 결정하는 데 사용할 수 있습니다.

const oldFn = __webpack_get_script_filename__;

__webpack_get_script_filename__ = (chunkId) => {
  const filename = oldFn(chunkId);
  return `${filename}.changed`;
};

__non_webpack_require__ (webpack-specific)

webpack에 의해 파싱되지 않는 require 함수를 생성합니다. 가능한 경우 전역 요청 함수로 멋진 작업을 수행하는데 사용할 수 있습니다.

__webpack_global__ (webpack-specific)

__webpack_require__의 별칭입니다. webpack 번들이 다시 번들링될 때(예: 이전에 번들링된 출력이 입력으로 사용될 때), CompatibilityPlugin은 충돌을 방지하기 위해 이전 번들의 __webpack_require__ 함수 이름을 변경합니다. __webpack_global__을 사용하면 현재 컴파일의 __webpack_require__ 함수에 항상 접근할 수 있습니다.

src/module.js

__webpack_global__.myProperty = "value";

__webpack_exports_info__ (webpack-specific)

모듈에서, __webpack_exports_info__는 export 내부 검사를 허용하는데 사용할 수 있습니다.

• __webpack_exports_info__는 항상 true입니다.

• __webpack_exports_info__.<exportName>.used는 export가 사용되지 않는 경우 false이고, 그렇지 않으면 true입니다.

• __webpack_exports_info__.<exportName>.useInfo는 다음과 같습니다.

  • export가 사용되지 않는 경우 false
  • export가 사용되는 경우 true
  • export 사용이 런타임 조건에 따라 달라질 수 있는 경우 `nul l
  • 정보가 없을 경우 undefined

• __webpack_exports_info__.<exportName>.provideInfo는 다음과 같습니다.

  • export가 제공되지 않는 경우 false
  • export가 제공되는 경우 true
  • export 규정이 런타임 조건에 따라 달라질 수 있는 경우 `nul l
  • 정보가 없을 경우 undefined

• nested export에서 정보에 접근할 수 있습니다. 예. __webpack_exports_info__.<exportName>.<exportName>.<exportName>.used

• export가 __webpack_exports_info__.<name>.canMangle로 맹글링될 수 있는지 확인합니다.

__webpack_is_included__ (webpack-specific)

주어진 모듈이 webpack에 의해 번들 되어 있는지 테스트합니다.

if (__webpack_is_included__("./module-a.js")) {
  // 작업을 수행합니다
}

__webpack_base_uri__ (webpack-specific)

런타임에 기본 URI를 변경합니다.

• Type: string

• Available: 5.21.0+

• Example:

  Copy

  __webpack_base_uri__ = "https://example.com";

__webpack_runtime_id__

현재 엔트리의 runtime id에 접근합니다.

이것은 webpack의 고유 기능이며 webpack 5.25.0부터 사용할 수 있습니다.

src/index.js

console.log(__webpack_runtime_id__ === "main");