[Next.js] styled-components에서 vanilla-extract로 마이그레이션 진행 (app router)

[Next.js] styled-components에서 vanilla-extract로 마이그레이션 진행 (app router)

📖 들어가며

기존 프로젝트에서 Next.js 14버전의 앱 라우터에서 styled-components를 사용하고 있었습니다.

이전에 Next.js 11버전에서 14버전으로 마이그레이션을 진행하면서 남아있던 부분이었습니다.

 

앱 라우터에서 서버 컴포넌트를 지원하기 시작하면서, 서버 컴포넌트 활용 해보고자 마이그레이션을 진행했습니다.

 

그럼 먼저 왜 마이그레이션을 진행했고, 왜 vanilla-extract를 선택했는지 간략히 설명해 볼게요.

🔍 앱 라우터(app router)에서 styled-components의 문제점

styled-components는 서버 컴포넌트를 지원하지 않기 때문에, styled-components를 사용하려면 'use client'를 명시함으로써 클라이언트 컴포넌트를 강제적으로 사용해야 했습니다.

또한, 런타임 환경에서 실행되기 때문에 제로 런타임 환경에서 동작하는 것보다 상대적으로 렌더링이 늦을 수 있습니다.

✔️ vanilla-extract 선택 이유

왜 수많은 스타일 라이브러리 중에서 vanilla-extarct를 선택했을까요?

 

처음에는 Next.js 공식문서에서 자체적으로 추천해 주는 Tailwind Css를 고려해 봤습니다.

하지만 Tailwind css는 추가 문법을 의도치 않게 외워야 하는 상황을 고려하게 되었고,

개인적으로 CSS-in-JS 형식이 가독성 부분에서 더 좋다고 생각하여 선호하는 편이었습니다.

 

styled-components의 CSS-in-JS를 따라가면서 제로 런타임 환경에서 동작하며 서버컴포넌트를 지원하는 라이브러리 중에

panda css와 vanilla-extract 중에서 고민을 했습니다.

 

현재 제 프로젝트는 Typescript 환경이었습니다.

 

vanilla-extract는 Typescript로 css를 작성하며 정확히 CSS-in-JS가 아닌 CSS-in-TS라고 볼 수 있습니다.

이러한 면에서 강력한 타입스크립트 지원이 된다고 판단하여 더 끌리게 되었습니다.

 

또한, npm trends를 확인해 봤을 때 vanilla-extract가 상대적으로 많이 사용될뿐더러, pandacss가 vanilla-extract에 영감을 받았다고 합니다.

vanilla-extract vs pandcss npm trends

 

이러한 이유로 vanilla-extarct를 선택했습니다.

✔️ vanilla-extract을 선택함으로써 기대하는 부분

• 서버 컴포넌트 활용으로 인한 번들 크기 감소 및 네트워크 비용 감소 기대
• 런타임에 CSS를 생성하지 않기 때문에 더 빠른 페이지 로드 기대 (제로 런타임)

✏️ 진행 과정

먼저 vanilla-extract가 잘 적용되는지 확인하면서 작업하기 위해 작은 컴포넌트부터 점진적으로 적용하기로 했습니다.

✔️ 설치 및 적용

https://vanilla-extract.style/documentation/integrations/next/

Next.js — vanilla-extract

위 공식문서를 보며 설치를 하고 적용하는 과정을 거쳤습니다.

 

next.config.js에 해당 코드를 추가했습니다.

next.config.js

당시 코드를 보면 styled-componetns를 사용하기 위한 코드가 공존하고 있는 것을 볼 수 있습니다.

✔️ theme 정의

기존 styled-comopnents에서는 GlobalStyles.ts에서 전역 스타일을 정의해서 사용하고 있었습니다.

또한 theme에 자주 사용되는 스타일 코드도 정의하여 사용하고 있었습니다.

 

아래는 styled-comopnents를 사용할 당시 코드의 일부입니다.

// theme.ts
const margin = {
  small: '.5rem',
  base: '1rem',
  medium: '1.5rem',
  large: '2rem',
  xLarge: '3rem',
};

const padding = {
  small: '.5rem',
  base: '1rem',
  large: '2rem',
  xLarge: '3rem',
};
...

// GlobalStyle.ts
...
const GlobalStyle = styled.createGlobalStyle`
  ${reset};
  * {
    box-sizing: border-box;
  }
  ${({ theme }) => {
    return styled.css`
      body {
        background-color: ${theme.color.mainBackground};
        font-family: ${notoSansKr.style.fontFamily};
        font-size: ${theme.font.size.small};
        color: ${theme.color.mainFontColor};
        user-select: none;
        transition: all 0.25s linear;
      }
    `;
  }}
  a {
    text-decoration: none;
    color: inherit;
  }
`;

export default GlobalStyle;

 

vanilla-extract 또한 강력한 theme 기능을 제공해 주기 때문에 매우 좋았습니다.

// globalTheme.css.ts

...
export const global = createGlobalTheme(':root', {
  fontFamily: {
    notoSansKR: `var(--font-noto-sans-kr)`,
  },
  fontSize: {
    xLarge: '48px',
    large: '36px',
    medium: '28px',
    regular: '18px',
    small: '16px',
    micro: '14px',
  },
..
  margin: {
    small: '.5rem',
    base: '1rem',
    medium: '1.5rem',
    large: '2rem',
    xLarge: '3rem',
  },
  padding: {
    small: '.5rem',
    base: '1rem',
    large: '2rem',
    xLarge: '3rem',
  },
  ...
});

globalStyle('*', {
  boxSizing: 'border-box',
});

globalStyle('body', {
  fontSize: global.fontSize.small,
 ...
  userSelect: 'none',
  transition: 'all 0.25s linear',
});

globalStyle('a', {
  textDecoration: 'none',
  color: 'inherit',
});

createGlobalTheme을 통해 글로벌 스타일로 css 변수를 쉽게 지정했습니다.

또한, globalStyle을 통해 전역 스타일을 지정할 수 있었습니다.

 

물론 다크모드 관련한 코드도 존재합니다.

vanilla-extarct 다크모드 관련해서는 다음 포스팅에서 다룰 예정입니다.

✔️ reset css

기존에 styled-components를 사용할 때는 styled-reset 라이브러리를 설치하여 GlobalStyles.ts에 적용했습니다.

 

하지만 vanilla-extract에서는 디폴트로 reset CSS를 지원하지 않기 때문에, 직접 reset.css 파일을 생성하고 reset 스타일을 적용해야 했습니다.

reset.css를 layout 컴포넌트에서 import 하여 적용했고, 우선순위를 높이기 위해 globalTheme.css보다 위에 선언했습니다.

import 'src/styles/reset.css';
import 'src/styles/globalTheme.css';

https://meyerweb.com/eric/tools/css/reset/

CSS Tools: Reset CSS

✔️ 점진적 적용

먼저 layout 컴포넌트부터 점진적으로 적용했습니다.

// layout.css.ts
import { style } from '@vanilla-extract/css';
import { global } from 'styles/globalTheme.css';

export const container = style({
  width: '100%',
  maxWidth: global.device.mobile,
  minHeight: '100vh',
  margin: 'auto',
  padding: global.padding.base,
});

CSS-In-TS 형식으로 기존 styled-components 코드와 문법적으로 큰 차이가 없어서 매우 편했습니다.

 

대신 파일 선언은 '파일이름.css.ts'로 생성합니다.

 

이후 스타일 적용은 아래와 같이 적용할 수 있습니다.

import * as style from './layout.css';

<div className={style.container}>
 <DarkModeBtn />
 {children}
 <Footer />
</div>

적용 후 브라우저에서 확인한 결과 아래와 같이 잘 적용되었습니다.

vanilla-extarct도 각 class마다 고유한 class를 생성해서 부여하기 때문에 class가 중복되는 부분을 따로 고려하지 않아도 되었습니다.

styled-compoents와 다르게 css 변수로 잘 적용이 되어 있는 모습입니다.

 

그리고 브라우저 콘솔로 head를 확인해 보면 layout.css에 대한 stylesheet가 불러오고 있습니다!

이것이 바로 빌드 시점에 CSS 파일을 생성하여 잘 적용하고 있다는 의미입니다.

 

또한, 이전에 적용했던 글로벌 변수도 아래와 같이 잘 생성되어 사용되고 있습니다.

✔️ 동적 스타일링

제 프로젝트에서는 동적 스타일링을 통해 재사용 가능한 Button 컴포넌트를 생성해서 사용하고 있었습니다.

 

먼저 기존 styled-components를 사용한 Button 컴포넌트입니다.

// Button.tsx
'use client'

import styled, { css } from 'styled-components';

type Color =
  | 'contentBackground'
  | 'white'
  | 'whiteYellow'
  | 'yellow'
  | 'whiteBlue'
  | 'bluePuple'
  | 'lightBlue'
  | 'lightGray'
  | 'whiteGray'
  | 'darkGray'
  | 'laime'
  | 'lightRed'
  | 'pink'
  | 'red'
  | 'black';

const SButton = styled.button<{
  bgColor: Color;
  fontColor: Color;
  borderColor: Color;
}>`
  ${({ theme, bgColor, fontColor, borderColor }) => {
    return css`
      width: 100%;
      padding: ${theme.padding.small} ${theme.padding.base};
      margin-bottom: ${theme.margin.medium};
      border: 2px solid ${theme.color[borderColor]};
      border-radius: 4px;
      color: ${theme.color[fontColor]};
      font-size: ${theme.font.size.small};
      font-family: ${theme.font.family.base};
      background-color: ${theme.color[bgColor]};
      cursor: pointer;
    `;
  }}
`;

interface IButtonProps {
  children: React.ReactNode;
  bgColor?: Color;
  fontColor?: Color;
  borderColor?: Color;
  onClick?: (event: React.MouseEvent<HTMLElement>) => any;
  name?: string;
}

const Button = ({
  children,
  onClick,
  bgColor = 'contentBackground',
  fontColor = 'lightBlue',
  borderColor = 'whiteBlue',
  name,
}: IButtonProps) => (
  <SButton onClick={onClick} {...rest}>
    {children}
  </SButton>
);

export default Button;

 

동적 스타일링을 사용하기 위해 추가로 vanilla-extract/dynamic을 설치해 줬습니다.

https://vanilla-extract.style/documentation/packages/dynamic/

Dynamic — vanilla-extract

동적으로 css variables를 생성하기 위해 @vanilla-extract/dynamic에서는 assignInlineVars api를 제공합니다.

런타임에 생성하지만 라이브러리 자체는 매우 가벼우며 성능 저하를 일으키지 않습니다.

 

createVar와 assignInlineVars를 활용해서 동적 스타일링이 가능하도록 해줬습니다.

// button.css.ts
import { style, createVar } from '@vanilla-extract/css';
import { global } from 'src/styles/globalTheme.css';

export const backgroundColor = createVar();
export const fontColor = createVar();
export const borderColor = createVar();

export const button = style({
  display: 'flex',
  justifyContent: 'center',
  alignItems: 'center',
  width: '100%',
  padding: `${global.padding.small} ${global.padding.base}`,
  marginBottom: global.margin.medium,
  border: `2px solid ${borderColor}`,
  borderRadius: 4,
  color: fontColor,
  fontSize: global.fontSize.small,
  fontFamily: global.fontFamily.notoSansKR,
  backgroundColor,
  cursor: 'pointer',
});

// Button.tsx
import { global, vars } from 'src/styles/globalTheme.css';
import { assignInlineVars } from '@vanilla-extract/dynamic';
import * as style from './button.css';

...
const Button = ({
  children,
  onClick,
  bgColor,
  fontColor = 'lightBlue',
  borderColor = 'whiteBlue',
  name,
}: IButtonProps) => (
  <button
    className={style.button}
    style={assignInlineVars({
      [style.backgroundColor]: bgColor
        ? global.color[bgColor]
        : `hsl(${vars.themeColor.color.contentBackground})`,
      [style.fontColor]: global.color[fontColor],
      [style.borderColor]: global.color[borderColor],
    })}
    onClick={onClick}
    name={name}
  >
    {children}
  </button>
);

export default Button;

또한, 'use client'를 제거함으로써 서버 컴포넌트로 동작할 수 있게 되었습니다.

 

이러한 방식으로 다른 컴포넌트 점진적으로 vanilla-extarct를 적용했습니다.

✔️ next/font 적용 문제

next/font를 글로벌 변수로 적용하는 데 있어서 문제를 맞이했습니다.

기존 styled-components에서는 아래와 같이 선언 후 사용하고 있었습니다.

// GlobalStyle.ts
import { Noto_Sans_KR } from 'next/font/google';
import * as styled from 'styled-components';
import reset from 'styled-reset';

export const notoSansKr = Noto_Sans_KR({
  weight: ['300', '400', '500'],
  subsets: ['latin'],
});
const GlobalStyle = styled.createGlobalStyle`
  ..
  ${({ theme }) => {
    return styled.css`
      body {
      ..
        font-family: ${notoSansKr.style.fontFamily};
..
      }
    `;
  }}
 ..
`;

export default GlobalStyle;

 

그래서 해당 폰트를 적용하기 위해서 다음과 같이 시도해 봤습니다.

layout 컴포넌트에서 next/font를 선언 후 globalTheme.css.ts에서 import 한 후 동일하게 사용해야 하는지..?

 

도무지 감이 잡히지 않아서 구글링 해 본 결과 같은 문제를 겪고 있는 issue를 통해 해결할 수 있었습니다.

https://github.com/vanilla-extract-css/vanilla-extract/discussions/1019#discussioncomment-6776002

Global font-family with `next/font` ? · vanilla-extract-css vanilla-extract · Discussion #1019

 

먼저 layout 컴포넌트에서 사용할 next/font를 작성했습니다.

export const notoSansKr = Noto_Sans_KR({
  display: 'swap',
  weight: ['300', '400', '500'],
  subsets: ['latin'],
  variable: '--font-noto-sans-kr',
});

여기서 variable을 꼭 명시해줘야 합니다.

이게 css에서 사용할 변수명이 됩니다.

 

그리고 먼저 body에 해당 폰트를 적용하기 위해 아래와 같이 className을 적용할 수 있도록 했습니다.

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ko" suppressHydrationWarning>
      <body className={`${notoSansKr.className}`}>
      ...
      </body>
      ..
    </html>
  );
}

 

이후 해당 변수명을 사용해 줍니다.

export const global = createGlobalTheme(':root', {
  fontFamily: {
    notoSansKR: `var(--font-noto-sans-kr)`,
  },

그리고 사용하려는 css 파일에서 아래와 같이 폰트를 적용할 수 있었습니다.

import { style, createVar } from '@vanilla-extract/css';
import { global } from 'src/styles/globalTheme.css';


export const button = style({
 ...
  fontFamily: global.fontFamily.notoSansKR,
 ...
});

✔️ styled-components 관련 코드 및 종속성 제거

모든 컴포넌트에 정상적으로 vanilla-extract를 적용한 후 드디어 styled-compnents를 걷어낼 수 있었습니다.

이렇게 styled-components 때문에 강제적으로 클라이언트 컴포넌트로 사용해야 했던 문제를 해결했습니다.

 

이제 정말로 클라이언트 컴포넌트로만 동작해야 하는 컴포넌트만 클라이언트 컴포넌트로 작동하고, 나머지는 서버 컴포넌트로 작동하게 되었습니다.

🧐 결과

마이그레이션을 진행한 결과 서버 컴포넌트로 작동이 잘 되었습니다.

네크워크 탭

이로 인해서 초기에 다운로드하는 자바스크립트 파일과 크기가 줄어드는 개선 효과를 볼 수 있었습니다.

styled-comopnent (마이그레이션 이전)	vanilla-extract (마이그레이션 이후)

 

vanilla-extract로 마이그레이션을 진행한 것은 최고의 선택이었습니다.

프로젝트상 단점은 딱히 없고 장점만 남은 마이그레이션이 된 것 같습니다.

 

대신에 개발하면서 단점도 분명 존재했습니다.

아무래도 styled-components로 개발할 때보다 참고자료가 부족했습니다.

그래서 공식문서와 깃허브 issue에 많이 의존하여 개발을 진행했습니다.

대신 문법적으로나 복잡한 기술이 요구되지 않기 때문에 기존에 CSS-in-JS 방식에 익숙했다면 금방 적응이 가능한 것 같습니다.