Native HTML | Webpack

이 가이드에서는 experiments.html을 사용해 webpack의 네이티브 HTML 처리를 사용하는 방법과 기존 설정에서 html-loader 및 html-webpack-plugin을 제거하며 마이그레이션하는 방법을 설명합니다.
experiments.html은 아직 실험적인 기능입니다. webpack v6에서 기본값이 될 예정이지만 개발이 계속되는 동안 동작이 변경될 수 있습니다. 전체 진행 상황은 이슈 #536에서 확인할 수 있습니다.
webpack 설정에서 네이티브 HTML 지원을 활성화하세요.
이 옵션을 활성화하면 webpack은 .html 파일을 일급 모듈로 이해하고 loader에 전달하는 대신 직접 파싱합니다.
"Built-in"은 체인에 loader나 plugin 없이 webpack이 직접 작업한다는 의미이며, html-loader와 html-webpack-plugin의 모든 기능을 지원한다는 의미는 아닙니다. 정확한 지원 범위는 다음과 같습니다.
따라서 html-webpack-plugin으로 번들을 감싸는 문서를 만들거나 html-loader로 partial을 가져오는 프로젝트에는 둘 다 필요하지 않습니다. template engine으로 페이지를 렌더링하거나 html-webpack-plugin hook을 사용하는 plugin에 의존하는 프로젝트는 해당 plugin을 유지해야 합니다.
webpack 5.109.0부터 이 옵션의 기본값은 'auto'입니다. loader 또는 명시적인 모듈 타입을 지정한 module.rules 항목이 .html 파일과 이미 일치하지 않는 경우 내장 HTML 지원이 활성화됩니다. 따라서 기존 html-loader 설정은 그대로 작동하며 규칙을 하나씩 마이그레이션할 수 있습니다. experiments.futureDefaults를 사용하면 true로 리졸브됩니다.
Native HTML은 이전에 서로 다른 두 패키지가 필요했던 세 가지 작업을 지원합니다. 프로젝트에 맞는 방식을 선택하세요. 여러 방식을 함께 사용할 수도 있습니다.
entry가 .html 파일을 가리키도록 하면 webpack이 페이지를 직접 빌드합니다. 모든 <script src>, <link rel="stylesheet">, <img src>, 인라인 <style>, 인라인 <script>가 모듈 그래프의 일부가 되며, 내보낸 페이지의 모든 URL은 빌드된 hash 파일 이름으로 재작성됩니다.
이는 Vite와 Parcel이 사용하는 HTML 우선 모델입니다. 페이지가 필요한 script와 style의 단일 정보 소스가 되므로 동기화해야 할 별도의 엔트리 포인트 목록이 없습니다.
experiments.html을 명시적으로 true로 설정하면 .html이 JavaScript 확장자보다 앞서 기본 resolve.extensions에 추가됩니다. 따라서 ./src/index.js가 있어도 entry: './src'는 ./src/index.html로 리졸브됩니다. 'auto' 기본값에서는 .html이 .js 다음의 폴백으로만 사용됩니다.
JavaScript 엔트리를 유지하면서 webpack이 문서를 작성하도록 하려면 output.html을 설정하세요. Webpack은 HTML이 아닌 각 엔트리 포인트마다 HTML 파일 하나를 생성하고, dependOn을 통해 공유하는 청크를 포함하여 해당 엔트리 포인트의 초기 JS와 CSS 청크를 주입합니다.
이는 번들을 감싸는 문서를 생성하는 html-webpack-plugin의 역할에 해당합니다. 생성된 페이지를 설정하려면 output.html을 객체로 지정하세요.
JavaScript에서 .html 파일을 가져오면 모든 애셋 참조가 webpack을 통해 리졸브된 처리 결과 HTML을 문자열로 얻습니다. 이는 오랫동안 html-loader가 담당했던 역할입니다.
이 방식으로 가져온 HTML 모듈은 기본적으로 독립 파일로 내보내지 않지만, 엔트리로 사용한 HTML 모듈은 파일로 내보냅니다. module.generator.html.extract를 사용해 두 동작을 재정의할 수 있습니다.
기본적으로 parser는 알려진 URL 포함 속성을 의존성으로 처리합니다. 다음 항목은 별도 설정 없이 처리됩니다.
다음 두 규칙으로 JavaScript 측의 동작을 예측할 수 있습니다.
JS가 아닌 script 타입(application/ld+json, importmap 등), data URI, CSS가 아닌 type을 가진 <style>은 변경하지 않고 그대로 전달합니다.
태그 바로 앞에 webpackIgnore 주석을 추가하면 URL을 처리하지 않습니다. CDN 애셋이나 서버가 런타임에 재작성하는 URL에 유용합니다.
module.parser.html.sources는 전체 목록을 제어합니다. literal "..."을 사용하면 내장 기본값을 유지하면서 사용자 정의 항목을 추가할 수 있습니다.
URL 추출을 완전히 비활성화하려면 sources: false를 전달하세요. 인라인 <script>와 <style> 본문은 계속 처리됩니다. filter callback을 사용하면 개별 요소를 건너뛸 수 있습니다.
html source 타입은 다른 페이지를 가리키는 href를 빌드에 포함합니다. 연결된 파일은 자체 페이지로 번들링되어 출력되고, 속성은 해당 출력 파일 이름으로 재작성됩니다.
아래의 모든 옵션은 output.html 아래에 있으며 webpack이 생성한 페이지에 적용됩니다. entry descriptor를 통해 엔트리별로 재정의할 수 있습니다.
charset 키는 charset 선언으로 특별 처리되며(meta: { charset: "UTF-8" }은 <meta charset="UTF-8">을 내보냄), og:로 시작하는 키는 name 대신 property 속성을 사용합니다. 페이지에 이미 해당 선언이 있으면 각 항목을 건너뛰므로 직접 작성한 페이지의 값이 항상 우선합니다.
output.html.inject는 주입된 청크 태그의 위치를 지정합니다. 'body'가 기본값이고 output.module에서는 'head'가 기본값이며, 'head'를 직접 지정하거나 false로 sibling 청크 주입을 막을 수 있습니다. output.html.scriptLoading은 로드 방식을 선택합니다. 기본값인 'auto'는 ES module 출력에는 module script를, 그 외에는 defer를 사용하며, 'defer' 또는 'blocking'을 직접 지정할 수도 있습니다.
페이지에 <head>가 있으면 stylesheet <link> 태그는 항상 첫 번째 blocking script 앞의 <head>에 배치됩니다.
output.html.inline은 청크를 연결하는 대신 내용을 페이지에 직접 기록합니다. 이는 기존 html-webpack-inline-source-plugin이 담당하던 작업입니다. 페이지의 [contenthash]에는 인라인 콘텐츠가 반영됩니다.
직접 작성한 페이지에서는 webpackInline magic comment로 개별 참조의 인라인 여부를 지정할 수 있습니다.
manifest 안에 지정한 항목을 포함한 모든 icon은 일반 파이프라인을 통해 hash 애셋으로 내보냅니다. 두 옵션 모두 페이지 이름을 받는 함수도 허용하므로 멀티 페이지 빌드의 각 페이지에 서로 다른 icon 세트를 지정할 수 있습니다.
두 가지 제한 사항을 알아두세요. Webpack은 지정한 icon을 내보내지만 favicons-webpack-plugin 같은 전용 plugin처럼 하나의 원본 이미지에서 크기와 형식이 다른 variant를 생성하지는 않습니다. 또한 두 옵션은 webpack이 생성한 페이지에만 적용됩니다. 직접 작성한 페이지는 그대로 유지되므로 마크업을 직접 관리한다면 페이지에 <link> 태그를 추가해야 합니다.
integrity: true는 주입된 <script>/<link> 태그에 sha384 integrity 속성을 추가합니다. SRI에는 CORS가 활성화된 요청이 필요하므로 output.crossOriginLoading과 함께 사용하세요. csp는 엄격한 기본 policy와 모든 인라인 <script>/<style>의 hash를 포함하는 <meta http-equiv="Content-Security-Policy">를 주입합니다. 서버가 요청마다 값을 재작성한다면 대신 nonce를 설정하세요. 두 옵션은 webpack-subresource-integrity와 csp-html-webpack-plugin을 대체합니다.
output.resourceHints는 페이지에 <link rel="preload">/prefetch/modulepreload/preconnect 태그를 내보냅니다. 이는 기존 preload-webpack-plugin이 담당하던 작업입니다.
배열을 사용하면 literal href 및 이름이 지정된 청크나 엔트리에 대한 참조까지 완전히 제어할 수 있습니다.
CSS에서 참조하는 폰트에는 module.parser.css.fontPreload가 hint를 자동으로 추가합니다. server-side rendering에서는 resourceHints.manifest가 리졸브된 hint 목록을 JSON 애셋에 기록하여 서버가 직접 태그를 주입할 수 있도록 합니다.
module.parser.html.template은 parser가 의존성을 추출하기 전에 원본 HTML을 변환하므로 template 언어가 생성한 URL도 탐색하여 번들링합니다. 직접 작성한 페이지와 생성된 페이지 모두에서 실행됩니다.
context 객체는 현재 module과 해당 resource, 빌드 의존성 helper(addDependency, addContextDependency, addMissingDependency, addBuildDependency), emitWarning/emitError를 제공합니다. 읽는 template 파일을 등록해야 watch mode가 변경 사항을 감지합니다.
모든 동기 template engine을 같은 방식으로 연결할 수 있습니다.
HTML partial은 문서가 아니므로 문서로 파싱하면 context에 민감한 태그가 누락됩니다. 예를 들어 table 밖의 단독 <tr>이 그렇습니다. module.parser.html.as는 소스를 파싱할 context 요소의 이름을 지정합니다.
optimization.minimize가 활성화되면 내장 minimizer가 HTML 애셋을 최소화합니다. mode: 'production'에서는 기본적으로 활성화되며 별도로 설치하거나 연결할 항목이 없습니다.
문서의 DOM을 유지하는 모든 변환은 기본적으로 활성화됩니다. script나 selector가 다시 읽는 값을 변경하는 변환은 명시적으로 활성화해야 합니다. 객체 형태의 optimization.minimize로 설정하세요.