Next.js + Tailwind + Storybook 개발 환경 구축하기

 

Next 13 + Tailwind + Storybook

치스톡 프로젝트를 Next 13 기반으로 결정한 뒤로 다른 기술 스택들로 Tailwind, Storybook을 골랐다.

그래서 오늘은 Next13 + Tailwind + Storybook 기반으로 공식 문서 설명 따라서 개발 환경을 구축해보려한다.

 

Next.js + Tailwind

npx create-next-app@latest

 

먼저 Next.js 기반으로 설정하기 위해서 create-next-app을 해준다.

React에서 CRA처럼 Next.js 보일러 플레이트를 제공해주는건데,

위는 npm 기반 명령어이고 나는 yarn 기반으로 진행했기 때문에 아래 명령어를 입력해주었다.

 

yarn create next-app   

//create 다음 -가 없다.

 

이 코드를 입력하면 Next 13 기반으로 초기 설정을 진행해주는데,

기본적으로 TypeScript를 사용할지, 또 Tailwind를 사용할지 물어보기 때문에 이 둘에 대한 설정은 따로 해주지 않았다.

 

npm run dev

 

설정을 마치고 위 명령어를 입력해보자.

localhost:3000에서 아래의 화면이 뜬다면 정상적으로 완료된 것이다.

 

 

ESLint 설정

yarn add --dev @typescript-eslint/eslint-plugin eslint-config-prettier

 

create-next-app을 통해 Next.js 기본 설정이 끝났다면, 이제 ESLint와 Prettier를 사용하기 위해 위 플러그인을 설치해주자.

 

{
  "plugins": ["@typescript-eslint"],
  "extends": [
    "next/core-web-vitals",
    "plugin:@typescript-eslint/recommended",
    "prettier"
  ],
  "rules": {
    "@typescript-eslint/no-unused-vars": "error",
    "@typescript-eslint/no-explicit-any": "error"
  }
}

 

이후 .eslintrc.json과 같은 eslint 설정 파일을 위와 같이 수정해주면 된다.

이렇게 되면 Next 프로젝트에서 ESLint와 Prettier를 사용하기 위한 설정이 끝났다.

(ESLint와 Prettier에 대한 기본 환경 설정은 이 글을 참고하자.)

 

Tailwind

create-next-app으로 Next를 설정하는 과정에서 Tailwind CSS를 사용하냐는 말에 체크를 했다면,

프로젝트 내에 tailwind.config.js 파일이 존재할 것이다.

안타깝게도 이 파일은 commonJS 모듈을 사용하는 js 파일로 설정된다.

 

npx tailwindcss init --ts

 

import/export를 사용하는 ts 파일로 바꿔주고 싶다면 위 명령어를 입력해서 tailwind.config.ts를 새로 생성해주자.

(tailwind.config.js는 기본 설정 일부를 ts로 옮긴 후에 삭제하자.)

 

//tailwind.config.ts

import type { Config } from "tailwindcss";

export default {
  content: [
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
    "./pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./components/**/*.{js,ts,jsx,tsx,mdx}",
 
    // Or if using `src` directory:
    "./src/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
} satisfies Config;

 

create-next-app으로 Next를 설정하는 과정에서 Tailwind CSS를 사용하냐는 말에 체크를 했다면,

프로젝트 내에 tailwind.config.js 파일이 존재할 것이다.

이 파일은 tailwind 설정 파일인데, 여기에서 content 속성에 tailwind class를 적용할 파일 경로들을 작성한다.

 

export default {
  darkMode: "class",  
  // darkMode: ['class', '[data-mode="dark"]']라고 적으면 클래스와 데이터 속성으로도 가능
	...
};

 

그 외에도 필요에 따라 다크 모드를 활성화시켜주면 좋다.

 

@tailwind base;
@tailwind components;
@tailwind utilities;

 

그 다음 global.css 파일 상단에 위 코드를 붙여넣어준다.

위 코드는 tailwind가 css 클래스를 구분하는 3개의 레이어를 global.css에 포함시켜주는 코드다.

 

base 레이어는 HTML 요소에 적용되는 규칙이나 기본 스타일을 의미하고,

component 레이어는 컴포넌트 단위로 정의되는 클래스 기반 스타일을 위한 레이어(.primary-btn)이며,

utility 레이어는 호버, 포커스, 다크모드와 같은 것들을 주입하는 레이어라고 한다.

 

export default function Home() {
  return (
    <h1 className="text-3xl font-bold underline">
      Hello world!
    </h1>
  )
}

 

app/page.tsx에 위 코드를 붙여넣고 yarn dev를 입력하여 스타일 클래스가 정상적으로 적용되는지 확인한다.

 

Tailwind를 위한 VS Code 설정

 

자동완성 기능을 사용하기 위해 Tailwind IntelliSense 플러그인을 설치해준다.

그 후, VS Code 설정에서 아래 항목을 설정해준다.

 

1. files.associations

"files.associations": {
  "*.css": "tailwindcss"
}

 

2. editor.quickSuggestions

"editor.quickSuggestions": {
  "strings": true
}

 

Tailwind Class를 자동 정렬해주는 Prettier 플러그인

Tailwind는 Class들이 결합되어 디자인을 나타내기 때문에 class 속성이 굉장히 길어진다.

이 속성들의 순서를 정리해주는 Prettier 플러그인이 바로 prettier-plugin-tailwindcss이다.

필요하다면, 아래 명령어를 입력하여 prettier와 플러그인을 설치해주자.

 

yarn add -D prettier prettier-plugin-tailwindcss

 

그 후, prettier.config.js파일을 생성해서 아래 설정을 붙여넣어준다.

 

module.exports = {
  plugins: ['prettier-plugin-tailwindcss'],
}

 

이렇게 Tailwind를 편하게 사용하기 위한 기본 설정이 끝났다.

 

Storybook

npx storybook@latest init

 

Next 13 기반에서 스토리북은 위 명령어를 통해 설치 및 초기화해줄 수 있다.

중간에 ESLint 플러그인도 설치하라고 나오는데 설치할 경우 ESLint 설정 파일에 자동으로 추가된다.

 

Tailwind와 엮기

yarn add -D @storybook/addon-styling

 

Storybook을 Tailwind와 같이 사용하려면 위 애드온을 설치해주어야한다.

설치 후에 yarn storybook 명령어로 빌드 시 빌드가 안 되는 문제가 발생할 수 있는데

검색해보니 yarn 패키지에서 무언가 꼬이면서 발생한 문제로 yarn.lock을 수정하거나

패키지 매니저를 pmpn으로 변경해서 설치 시 오류가 나지 않았다는 답변을 볼 수 있었다.

나는 그냥 yarn.lock을 지운 다음에 yarn 명령어로 다시 깔아주니 정상적으로 작동되었다.

 

정상적으로 빌드나 실행이 된다면, 아래 명령어를 통해 auto setup을 해준다.

 

yarn addon-styling-setup

 

이후 preview.js에 index.css 경로를 프로젝트의 global.css 경로로 변경해주면 된다.

 

//.storybook/preview.ts

import "../src/index.css";

->

import "../src/app/globals.css";  //프로젝트의 global css 경로

 

기본으로 설치되는 stories/Button.tsx로 tailwind를 테스트해보고 싶다면, tailwind.config.ts에 아래 부분을 추가해주자.

tailwind가 적용되는 경로를 추가해주는 것이다.

 

//tailwind.config.ts

import type { Config } from "tailwindcss";

export default {
  content: [
   ...
   "./src/stories/**/*.{js,ts,jsx,tsx,mdx}",  // 이 코드 추가
  ],
  theme: {
    extend: {},
  },
  plugins: [],
} satisfies Config;

 

다크모드 연동

스토리북에서는 다크모드 스위치 기능을 제공한다.

auto-setup을 했다면 아마 preview.ts에

withThemeByClassName이라는 class 기반으로 테마를 연동하는 데코레이터가 설정되어 있을 것이다.

이 경우는 html 태그의 class에 light나 dark와 같은 클래스 이름을 추가하여 다크모드를 연동할 수 있다.

 

그런데, 경우에 따라 tailwind에서 class 기반으로 다크모드를 하는게 아닌

data-mode 속성 기반으로 다크모드를 구분하는 경우도 존재할 것이다.

 

//tailwind.config.ts

import type { Config } from "tailwindcss";

export default {
  content: [
   ...
  ],
  // Toggle dark-mode based on data-mode="dark"
  darkMode: ['class', '[data-mode="dark"]'],
  theme: {
    extend: {},
  },
  plugins: [],
} satisfies Config;

 

tailwind.config.js에서 다크모드가 위와 같이 설정되어 있다면,

이는 class 뿐만 아니라 data-mode 속성 기반으로도 테마를 설정하겠다는 의미이다.

이처럼 data-mode 기반으로  테마를 구분할 경우 스토리북에 다크 모드를 연동하기 위해 아래 데코레이터를 추가해준다.

 

// .storybook/preview.js
import { withThemeByDataAttribute } from '@storybook/addon-styling';

export const decorators = [
  withThemeByDataAttribute({
    themes: {
      light: 'light',
      dark: 'dark',
    },
    defaultTheme: 'light',
    attributeName: 'data-mode',
  }),

 

이는 class가 아니라 data-mode 속성 기반으로 테마를 연동하겠다는 설정이다.

 

 

class든 data-속성이든 데코레이터를 통해 잘 연동했다면, 위와 같이 theme을 바꿔서 컴포넌트의 상태를 볼 수 있을 것이다.

 

 

이렇게 Next 13 + Tailwind + Storybook 개발환경 설정이 끝났다!

 

 

 

Reference

Getting Started: Installation | Next.js

Install Tailwind CSS with Next.js - Tailwind CSS

Integrate Tailwind CSS with Storybook | Storybook