가이드: PostCSS | Next.js

출처 URL: https://nextjs.org/docs/pages/guides/post-css

Next.js에서 PostCSS를 구성하는 방법

마지막 업데이트: 2026년 2월 20일

기본 동작

Next.js는 내장 CSS 지원을 위해 CSS를 PostCSS로 컴파일합니다.

별도 설정 없이도 Next.js는 다음과 같은 변환으로 CSS를 컴파일합니다.

Autoprefixer는 CSS 규칙에 벤더 프리픽스를 자동으로 추가합니다(IE11까지 지원).
브라우저 간 Flexbox 버그를 수정하여 명세와 동일하게 동작하도록 합니다.
새로운 CSS 기능을 Internet Explorer 11과 호환되도록 자동으로 컴파일합니다.

기본적으로 CSS Grid와 사용자 정의 속성(CSS 변수)은 IE11 지원을 위해 컴파일되지 않습니다.

CSS Grid Layout을 IE11용으로 컴파일하려면 CSS 파일 상단에 다음 주석을 추가하세요.

    /* autoprefixer grid: autoplace */

프로젝트 전체에서 CSS Grid Layout에 IE11 지원을 적용하려면 아래(접힌) 구성으로 autoprefixer를 설정할 수 있습니다. 자세한 내용은 아래 “플러그인 사용자 정의”를 참조하세요.

CSS Grid Layout을 활성화하는 구성을 보려면 클릭하세요

postcss.config.json

    {
      "plugins": [
        "postcss-flexbugs-fixes",
        [
          "postcss-preset-env",
          {
            "autoprefixer": {
              "flexbox": "no-2009",
              "grid": "autoplace"
            },
            "stage": 3,
            "features": {
              "custom-properties": false
            }
          }
        ]
      ]
    }

CSS 변수는 안전하게 컴파일할 수 없기 때문에 컴파일되지 않습니다. 변수를 반드시 사용해야 한다면 Sass가 컴파일해 제거하는 Sass 변수 같은 대안을 고려하세요.

대상 브라우저 사용자 정의

Next.js는 Browserslist를 통해 ( Autoprefixer와 컴파일되는 CSS 기능에 대한) 대상 브라우저를 설정할 수 있게 해줍니다.

browserslist를 사용자 정의하려면 package.json에 browserslist 키를 다음과 같이 추가하세요.

package.json

    {
      "browserslist": [">0.3%", "not dead", "not op_mini all"]
    }

browsersl.ist 도구를 사용하면 타깃팅 중인 브라우저를 시각화할 수 있습니다.

CSS 모듈

CSS 모듈을 지원하는 데 별도 설정이 필요하지 않습니다. 파일 확장을 .module.css로 바꾸면 해당 파일에 CSS 모듈이 활성화됩니다.

Next.js의 CSS 모듈 지원에 대해 더 알아보세요.

플러그인 사용자 정의

경고 : 사용자 지정 PostCSS 구성 파일을 정의하면 Next.js는 기본 동작을 완전히 비활성화합니다. Autoprefixer를 포함해 필요한 기능을 모두 직접 설정해야 합니다. 또한 사용자 지정 구성에 포함된 플러그인은 npm install postcss-flexbugs-fixes postcss-preset-env처럼 수동으로 설치해야 합니다.

PostCSS 구성을 사용자 정의하려면 프로젝트 루트에 postcss.config.json 파일을 만드세요.

다음은 Next.js가 사용하는 기본 구성입니다.

postcss.config.json

    {
      "plugins": [
        "postcss-flexbugs-fixes",
        [
          "postcss-preset-env",
          {
            "autoprefixer": {
              "flexbox": "no-2009"
            },
            "stage": 3,
            "features": {
              "custom-properties": false
            }
          }
        ]
      ]
    }

알아두면 좋아요 : Next.js는 이 파일을 .postcssrc.json으로 이름 붙이거나, package.json의 postcss 키에서 읽을 수도 있습니다.

환경에 따라 플러그인을 조건부로 포함하고 싶을 때 유용한 postcss.config.js 파일로 PostCSS를 설정하는 것도 가능합니다.

postcss.config.js

    module.exports = {
      plugins:
        process.env.NODE_ENV === 'production'
          ? [
              'postcss-flexbugs-fixes',
              [
                'postcss-preset-env',
                {
                  autoprefixer: {
                    flexbox: 'no-2009',
                  },
                  stage: 3,
                  features: {
                    'custom-properties': false,
                  },
                },
              ],
            ]
          : [
              // No transformations in development
            ],
    }

알아두면 좋아요 : Next.js는 이 파일을 .postcssrc.js로 이름 붙이는 것도 허용합니다.

PostCSS 플러그인을 가져올 때는 require()를 사용하지 마세요. 플러그인은 문자열로 제공해야 합니다.

알아두면 좋아요 : 동일한 프로젝트에서 postcss.config.js가 다른 비-Next.js 도구도 지원해야 한다면, 다음과 같이 상호 운용 가능한 객체 기반 형식을 사용해야 합니다.

>     module.exports = {
>       plugins: {
>         'postcss-flexbugs-fixes': {},
>         'postcss-preset-env': {
>           autoprefixer: {
>             flexbox: 'no-2009',
>           },
>           stage: 3,
>           features: {
>             'custom-properties': false,
>           },
>         },
>       },
>     }

보내기