Next.js에서 storybook 기본 세팅 및 tailwind css 연동 방법

Next.js 14+ App Router에서 Storybook 기본 세팅과 tailwind css 연동 방법을 알아보겠습니다.

Storybook이란?

Storybook은 컴포넌트를 개발하고 문서화하는 도구입니다. Storybook은 컴포넌트를 독립적으로 테스트하고 문서화하며, 컴포넌트를 개발할 때 빠르게 반복할 수 있도록 도와줍니다. Storybook은 React, Vue, Angular, Svelte 등 다양한 프레임워크를 지원합니다.

이번에는 Next.js에서 Storybook을 사용하는 방법을 알아보겠습니다.

Storybook 설치

Next js 설치 단계는 건너뛰고 Storybook 설치 단계부터 시작하겠습니다. tailwind를 설치한 가정하에 시작합니다.

npx storybook@latest init

현재 기준으로 Storybook 8버전이 설치됩니다.

만약 미리 설치된 7+버전 미만에서 사용한다면 다음과 같이 공식문서를 참고해주세요. `Storybook 7+버전 미만에서 업그레이드 방법 - 공식문서`

storybook을 설치하면 .storybook 폴더와 stories 폴더가 생성됩니다. 그리고 자동으로 스토리북 페이지가 열리게 됩니다.

만약 자동으로 스토리북 페이지가 열리지 않는다면 다음과 같이 실행해주세요.

npm run storybook

스토리북을 실행하면 다음과 같은 화면이 나타납니다.

스토리북 이미지

위 이미지와 같은 화면이 나타난다면 성공적으로 설치가 된 것입니다.

storybook 설치 후 stories 폴더에 여러 파일들이 생성된 것을 확인할 수 있습니다.

스토리북 더미 파일들

stories의 파일들은 더미로 Default로 생성된 파일들입니다. stories폴더를 제외한 이 파일들은 삭제해도 무방합니다.

Storybook과 Next.js 연동

Storybook 설치 후 Storybook의 세팅과 Next.js의 세팅을 약간 수정해야 합니다.

먼저 .storybook/main.ts 파일의 addons: [] 부분을 다음 부분을 삭제합니다.

"@storybook/addon-onboarding",

tailwind css 연동을 위해 preview.ts 파일에 global.css 파일을 import 해줍니다.

import type { Preview } from '@storybook/react';
import '../app/globals.css';
 
const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
};
 
export default preview;

globals.css 파일이 만약 다른곳에 위치한다면 경로를 맞게 수정해주세요.

본 예제는 Next.js 14+ 버전을 기준으로 작성되었습니다.

이제 Storybook과 Next.js의 연동이 완료되었습니다.

stories 폴더에는 story파일을 생성하여 컴포넌트를 작성하여 story 페이지의 컴포넌트를 확인할 수 있습니다.

import Button from '@/components/Button'; // 실제 컴포넌트 경로
import type { Meta, StoryObj } from '@storybook/react';
 
const meta: Meta<typeof Button> = {
  title: 'Button',
  component: Button,
  tags: ['autodocs'],
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
export const Primary: Story = {
  args: {
    label: '버튼',
  },
};

컴포넌트는 이전과 하던 방식으로 사용하면 됩니다.

타입은 stories/Button.stories.tsx 파일에 작성한 타입과 동일 해야합니다. args는 컴포넌트에 전달할 props를 작성합니다.

const Button = ({ label }: { label: string }) => {
  return <button className="bg-green-400">{label}</button>;
};
 
export default Button;

14.1이하 이전 버전 사용시 추가 설정 - 필요할 수도 있습니다.

storybook에서 tailwind css를 사용하기위해 다음과 같이 설치합니다.

npx storybook@latest add @storybook/addon-styling-webpack

{
  "compilerOptions": {
    // ... 다른 옵션들
    "baseUrl": "."
  }
}

컴파일 옵션에 baseUrl을 추가해주세요.

이슈

현재 4월 13일 기준으로 create-next-app@latest 사용시 Next js 버전이 14.2+ 로 업데이트 되었습니다. Storybook 8버전에서 tailwind css를 사용할 때, Storybook 페이지에서 컴포넌트가 적용되지 않는 이슈가 있습니다. Next js 사용시 본 방법은 14.1 버전을 기준으로 사용하길 바랍니다.