[Next.js] Next.js `className` did not match

개발을 하던 도중 이런식으로 에러가 뜨면서 스타일드 컴포넌트로 만든 컴포넌트가
스타일링이 적용이 안되는 에러가 생겼다.

Next.js에서 styled-components를 사용할 때 _document를 따로 설정해서 SSR될 때 CSS가 head에 주입되도록 해야 한다. 만약 따로 설정하지 않는다면, styled-components가 적용되지 않은 상태로 렌더링될 수 있다.

Next.js에서 styled-components를 사용하면 위와 같은 경고가 뜨곤 한다.

경고 문구에서도 알 수 있듯이, 서버와 클라이언트의 클래스명이 다른 것이 원인이다.

Next.js는 첫 페이지 로드가 SSR로 동작하기 때문에, 서버에서 생성된 컴포넌트와 CSR로 클라이언트에서 생성된 컴포넌트의 클래스명이 서로 달라지게 된다.

이렇게 환경에 따라 달라지는 className을 일관되게 해주는 것이 바로 babel-plugin-styled-components이다.

만약 CNA(create-next-app)을 사용하고 있다면, 루트 디렉토리에 .babelrc 파일을 만들고 아래와 같이 작성하면 된다.

{
  "presets": ["next/babel"],
  "plugins": ["babel-plugin-styled-components"]
}

+ SWC를 사용하는 경우

Next.js 12버전부터 babel 대신 swc를 사용하여 컴파일하도록 변경되었다. 그러나 .babelrc가 있다면 babel을 사용하게 되므로 위 babel-plugin-styled-components를 사용하지 않고 아예 babelrc를 제거한 다음, next.config.js에서 nextConfig에 styledComponents 설정만 해주면 swc를 사용하면서 동일하게 문제를 해결할 수 있다.

/** @type {import('next').NextConfig} */
const nextConfig = {
  compiler: {
    styledComponents: true,
  },
};

module.exports = nextConfig;