Native CSS | Webpack

이 가이드는 experiments.css를 사용해 webpack의 네이티브 CSS 처리를 사용하는 방법과, 기존 설정에서 css-loader, style-loader, mini-css-extract-plugin을 제거하며 마이그레이션하는 방법을 설명합니다.
experiments.css는 아직 실험적인 기능입니다. webpack v6에서는 기본값이 될 것으로 예상되지만, 개발이 계속되는 동안 동작이 바뀔 수 있습니다.
webpack 설정에서 네이티브 CSS 지원을 활성화하세요.
이 옵션을 활성화하면 webpack은 .css 파일을 일급 모듈로 이해하고 loader에 전달하는 대신 직접 파싱합니다.
"Built-in"은 체인에 loader 없이 webpack이 직접 작업한다는 의미이며, CSS loader의 모든 기능을 지원한다는 의미는 아닙니다. 정확한 지원 범위는 다음과 같습니다.
따라서 기본 옵션으로 css-loader와 style-loader(또는 mini-css-extract-plugin)를 사용하는 프로젝트에는 CSS loader가 필요하지 않습니다. 오른쪽 열의 옵션을 사용하는 프로젝트는 필요한 파일에만 해당 loader를 유지할 수 있으며 두 방식을 규칙별로 함께 사용할 수 있습니다.
webpack 5.109.0부터 기본값은 'auto'입니다. loader 또는 명시적인 모듈 타입을 지정한 module.rules 항목이 .css 파일과 이미 일치하지 않으면 내장 CSS 지원이 활성화됩니다. 따라서 기존 css-loader 설정은 그대로 작동하며 규칙을 하나씩 마이그레이션할 수 있습니다. 네이티브 지원을 강제하려면 true, 비활성화하려면 false로 설정하세요.
실험 기능을 활성화한 뒤에는 JavaScript에서 .css 파일을 직접 import할 수 있습니다.
Webpack은 이 CSS를 처리해 빌드 결과물에 포함합니다.
Native CSS는 네 가지 Rule.type 값을 도입합니다. 어떤 값이 적용되는지 이해하는 것이 마이그레이션의 핵심인데, 각각이 서로 다른 css-loader modules.mode에 대응하기 때문입니다.
webpack이 /\.css$/i에 대해 기본으로 추가하는 rule은 css/auto이므로, *.module.css 파일은 CSS Modules가 되고 나머지는 모두 전역으로 유지됩니다. 이는 가장 일반적인 css-loader 설정과 기본적으로 동일합니다.
css/auto를 사용할 때는 파일 이름을 *.module.css(또는 *.modules.css)로 지정하면 CSS Modules로 처리할 수 있습니다.
src/button.module.css
기본적으로 namedExports가 활성화되어 있으므로, local 값은 namespace(import * as styles)나 이름(import { button } from "./button.module.css")으로 import하세요. 기존의 default-import object 방식을 유지하려면 이를 false로 설정하세요.
parser와 generator 옵션으로 CSS Modules 동작을 사용자 정의할 수 있습니다. 아래의 All options with examples를 참고하세요.
Native CSS Modules는 css-loader와 같은 authoring 기능을 이해하므로, 대부분의 stylesheet는 수정 없이 그대로 마이그레이션할 수 있습니다.
하나의 CSS module은 네 가지 방식으로 출력할 수 있습니다. exportType parser 옵션으로 이를 선택하며, 각각은 기존 툴체인의 다른 부분을 대체합니다.
module type별로 전역 설정할 수 있습니다.
또는 일부 파일에만 rule별로 설정할 수 있습니다.
Native CSS는 빌드 시점에 @custom-media와 @custom-selector를 리졸브하므로 이 두 규칙을 위해 흔히 사용하던 PostCSS plugin이 필요하지 않습니다.
리졸브는 파일 단위입니다. 정의는 이를 선언한 파일에만 적용되며, 해당 파일이 @import한 대상이나 전체 프로젝트에는 적용되지 않습니다. 둘 다 기본적으로 활성화되며 module.parser.css.customMedia와 module.parser.css.customSelectors로 각각 비활성화할 수 있습니다. 체인의 PostCSS plugin이 이미 처리한다면 비활성화하세요.
optimization.minimize가 활성화되면 내장 minimizer가 CSS 애셋을 최소화합니다. mode: 'production'에서는 기본적으로 활성화되며 별도로 설치하거나 연결할 항목이 없습니다.
이는 css-minimizer-webpack-plugin과 그 기반의 cssnano 체인을 대체합니다. 색상·숫자·값·selector 단축, longhand 및 규칙 병합, 불필요한 규칙 제거, 상수 기반 calc()와 수학 함수 계산, 따옴표 정규화, media query range 표기 등 스타일시트의 의미를 유지하는 모든 변환이 기본 활성화됩니다. script가 다시 읽는 텍스트를 변경하는 rewriteCustomProperties와 압축 후 효과가 적은 convertLengthUnits는 비활성화되어 있습니다.
객체 형태의 optimization.minimize로 설정하세요.
JavaScript minification은 유지하면서 CSS만 비활성화하려면 minimize: { css: false }를 사용하세요.
minimizer는 browserslist target에 맞춰 vendor prefix를 관리합니다. 선택한 브라우저에 여전히 필요한 property, at-rule, pseudo-selector의 -webkit-/-moz-/-ms- 표기를 추가하고 아무 브라우저에도 필요하지 않은 표기는 제거합니다. 따라서 대부분의 프로젝트에서 autoprefixer와 이를 위한 postcss-loader를 의존성에서 제거할 수 있습니다.
prefix 처리는 browserslist target에서만 적용됩니다. 다른 target에는 prefix를 지정할 브라우저 정보가 없습니다. PostCSS 체인이 이미 처리한다면 optimization.minimize.css.vendorPrefixes: false로 비활성화하세요.
CSS에서 참조하는 애셋에 plugin 없이 <link rel="preload">/prefetch hint를 지정할 수 있습니다. module.parser.css.fontPreload는 HTML 엔트리의 초기 CSS에서 접근 가능한 각 @font-face에 preload 하나를 추가합니다. 모든 형식을 preload하면 폰트를 두 번 다운로드하므로 기본 src URL만 사용합니다.
module.parser.css.urlHints는 url(...)로 접근하는 다른 항목에 애셋별 규칙을 제공하고, output.resourceHints는 프로젝트 전체 규칙을 설정합니다.
experiments.html을 활성화하면 HTML 페이지의 <link rel="stylesheet">가 CSS 청크 엔트리가 되고 인라인 <style> 본문과 style="" 속성도 같은 CSS 파이프라인을 거칩니다. 내부의 @import와 url()은 HTML 파일을 기준으로 리졸브되며 위의 minimizer 옵션도 적용됩니다.
전체 HTML 기능은 Native HTML 가이드를 참고하세요.
@webpack/css-plugins-to-native-css codemod를 사용하면 마이그레이션의 대부분을 자동으로 처리할 수 있습니다.
이 codemod는 해당 릴리스에서 도입된 experiments.css: "auto" 기본값을 사용하므로 webpack 5.109.0 이상이 필요합니다.
한 번에 loader 하나씩 마이그레이션하세요. 아래 섹션은 각 단계에서 빌드가 깨지지 않도록 하는 순서로 구성되어 있습니다.
이제 내장된 /\.css$/i → css/auto rule이 .css import를 처리합니다. 아래 섹션에서 각 옵션에 대응되는 기능을 확인한 뒤, 기존의 custom rule과 plugin을 제거하세요.
Native CSS는 기본적으로 stylesheet를 추출하고(exportType: "link"), 여기에 content hash까지 추가하므로 plugin과 그 loader가 더 이상 필요하지 않습니다.
남은 plugin 옵션은 다음과 같이 대응됩니다.
대부분의 css-loader 옵션은 module.parser.css와 module.generator.css 아래에 네이티브 대응 기능이 있습니다. 일반적인 기본값(url, import, namedExports 모두 활성화)은 보통의 css-loader 설정과 이미 일치하므로, 많은 프로젝트에서는 parser 설정이 아예 필요하지 않습니다.
예를 들어, 아래와 같은 css-loader CSS Modules 설정은
localIdentName은 [hash:base64:6] 같은 hash placeholder를 지원합니다. hashing은 output.hashFunction, output.hashDigest, output.hashDigestLength, output.hashSalt로 전역 조정하거나, localIdentHash* generator 옵션으로 module type별 조정할 수 있습니다.