Autodocs로 문서 자동화하고 Storybook 배포하기

성태경·2026년 2월 25일
storybook

Storybook

목록 보기
5/5

들어가며

4편에서는 Play Function으로 인터랙션 테스트를 작성하는 방법을 알아봤다. 시리즈 마지막 글인 이번 편에서는 Story를 기반으로 문서를 자동 생성하는 Autodocs와, 완성된 Storybook을 빌드하고 배포하는 방법을 다룬다.

Autodocs란?

공식 문서의 Autodocs 페이지에 이런 설명이 나온다.

Storybook Autodocs is a powerful tool that can help you quickly generate comprehensive documentation for your UI components. By leveraging Autodocs, you're transforming your stories into living documentation.

Autodocs는 작성된 Story를 기반으로 컴포넌트 문서를 자동 생성하는 기능이다. 컴포넌트의 args, argTypes, parameters 같은 메타데이터를 추론해서, 사이드바 컴포넌트 트리의 최상단에 문서 페이지를 만들어준다.

따로 문서를 작성하지 않아도 Story만 잘 작성하면 "이 컴포넌트는 어떤 props를 받고, 각 상태가 어떻게 보이는지"를 보여주는 문서가 생기는 셈이다.

Autodocs 설정하기

Autodocs는 tags를 통해 활성화한다.

전체 프로젝트에 적용

.storybook/preview.ts에 tags: ['autodocs']를 추가하면 모든 Story에 대해 자동 문서가 생성된다.

// .storybook/preview.ts
import type { Preview } from '@storybook/nextjs';

const preview: Preview = {
  tags: ['autodocs'],
};
export default preview;

특정 컴포넌트에만 적용

전체가 아니라 특정 컴포넌트에만 적용하고 싶다면, 해당 Story 파일의 meta에 tags를 추가한다.

import type { Meta } from '@storybook/nextjs';
import { Button } from './Button';

const meta = {
  component: Button,
  tags: ['autodocs'],
} satisfies Meta<typeof Button>;
export default meta;

특정 컴포넌트 제외하기

반대로 전역으로 Autodocs를 켜둔 상태에서 특정 컴포넌트만 제외하고 싶다면, !autodocs 태그를 사용한다.

import type { Meta } from '@storybook/nextjs';
import { Page } from './Page';

const meta = {
  component: Page,
  tags: ['!autodocs'],
} satisfies Meta<typeof Page>;
export default meta;

특정 Story만 문서에서 제외하는 것도 가능하다.

export const InternalStory: Story = {
  tags: ['!autodocs'],
};

컴포넌트 설명 추가하기

Autodocs 페이지에 컴포넌트나 Story에 대한 설명을 추가할 수 있다. 두 가지 방법이 있다.

JSDoc 주석

컴포넌트나 Story 위에 JSDoc 주석을 작성하면 Autodocs 페이지에 표시된다.

/**
 * 기본 버튼 컴포넌트.
 * 다양한 크기와 스타일을 지원한다.
 */
const meta = {
  component: Button,
  tags: ['autodocs'],
} satisfies Meta<typeof Button>;
export default meta;

type Story = StoryObj<typeof meta>;

/** Primary 스타일의 기본 버튼 */
export const Primary: Story = {
  args: {
    primary: true,
    label: 'Button',
  },
};

meta 위의 주석은 컴포넌트 전체 설명으로, 개별 Story 위의 주석은 해당 Story의 설명으로 표시된다.

parameters.docs.description

JSDoc 대신 parameters로 설명을 추가할 수도 있다. JSDoc 주석과 동시에 사용하면 parameters가 우선한다.

const meta = {
  component: Button,
  tags: ['autodocs'],
  parameters: {
    docs: {
      description: {
        component: '기본 버튼 컴포넌트. 다양한 크기와 스타일을 지원한다.',
      },
    },
  },
} satisfies Meta<typeof Button>;

export const Primary: Story = {
  parameters: {
    docs: {
      description: {
        story: 'Primary 스타일의 기본 버튼',
      },
    },
  },
};

문서 템플릿 커스텀하기

기본 Autodocs 템플릿이 마음에 들지 않는다면, Doc Block을 조합해서 커스텀 템플릿을 만들 수 있다.

// .storybook/preview.tsx
import * as React from 'react';
import type { Preview } from '@storybook/nextjs';
import {
  Title,
  Subtitle,
  Description,
  Primary,
  Controls,
  Stories,
} from '@storybook/addon-docs/blocks';

const preview: Preview = {
  parameters: {
    docs: {
      page: () => (
        <>
          <Title />
          <Subtitle />
          <Description />
          <Primary />
          <Controls />
          <Stories />
        </>
      ),
    },
  },
};
export default preview;

각 Doc Block의 역할을 정리하면 이렇다.

Doc Block역할
Title컴포넌트 이름
Subtitle부제목
Description컴포넌트 설명 (JSDoc 또는 parameters에서 가져온다)
Primary첫 번째 Story를 렌더링한다
Controlsargs/argTypes 기반의 인터랙티브 테이블
Stories나머지 Story들의 목록

이 블록들의 순서를 바꾸거나, 일부를 빼거나, 사이에 커스텀 내용을 추가할 수 있다.

목차 자동 생성

문서 페이지가 길어지면 목차가 있으면 편하다. toc 옵션으로 목차를 활성화할 수 있다.

// .storybook/preview.ts
import type { Preview } from '@storybook/nextjs';

const preview: Preview = {
  parameters: {
    docs: {
      toc: true,
    },
  },
};
export default preview;

기본적으로 h3 헤딩만 목차에 포함되는데, 더 세밀하게 설정할 수도 있다.

parameters: {
  docs: {
    toc: {
      headingSelector: 'h1, h2, h3',
      title: 'Table of Contents',
    },
  },
},

특정 컴포넌트에서만 목차를 끄고 싶다면 해당 meta의 parameters에서 비활성화한다.

const meta = {
  component: MyComponent,
  tags: ['autodocs'],
  parameters: {
    docs: {
      toc: { disable: true },
    },
  },
} satisfies Meta<typeof MyComponent>;

Storybook 빌드하기

Storybook은 정적 웹 앱으로 빌드할 수 있다. 빌드하면 별도의 서버 없이 어디서든 호스팅할 수 있는 파일들이 생성된다.

pnpm storybook build

기본적으로 storybook-static 디렉토리에 빌드 결과물이 생성된다. 로컬에서 미리보기하려면:

pnpm dlx http-server ./storybook-static

Storybook 배포하기

빌드한 Storybook을 배포하면 팀원 누구나 URL 하나로 컴포넌트를 확인할 수 있다.

Chromatic

공식 문서에서 권장하는 배포 서비스는 Chromatic이다. Storybook 팀이 만든 서비스로, 무료 플랜이 있다.

pnpm add -D chromatic
pnpm exec chromatic --project-token=<your-project-token>

배포가 완료되면 https://random-uuid.chromatic.com 형태의 URL이 생성된다.

GitHub Actions와 연동하면 코드를 push할 때마다 자동으로 배포되도록 설정할 수도 있다.

그 외 호스팅

Storybook은 정적 웹 앱이므로, 아무 웹 호스팅 서비스에나 배포할 수 있다. GitHub Pages, Netlify, Vercel, AWS S3 등 어디든 가능하다. 다만 Chromatic은 Storybook과의 통합 기능(버전 관리, 컴포넌트 히스토리, 비주얼 테스트 등)을 추가로 제공한다는 차이가 있다.

정리

  1. Autodocs: tags: ['autodocs']를 추가하면 Story 기반으로 컴포넌트 문서가 자동 생성된다.
  2. 설명 추가: JSDoc 주석 또는 parameters.docs.description으로 컴포넌트/Story 설명을 작성한다.
  3. Doc Block: Title, Description, Primary, Controls, Stories 등의 블록을 조합해서 문서 템플릿을 커스텀할 수 있다.
  4. 배포: pnpm storybook build로 정적 앱을 빌드하고, Chromatic이나 다른 호스팅 서비스에 배포한다.

참고

profile
성태경
이전 포스트

Play Function으로 인터랙션 테스트 시작하기

0개의 댓글