MSUB/ui

문서

시작하기

MSUB/ui는 MSUB의 내부 디자인 시스템 컴포넌트 라이브러리입니다. TailwindCSS 기반으로 만들어졌으며, shadcn/ui 스타일의 소스 복사 방식을 채택합니다.

전제 조건

MSUB/ui를 사용하기 전에 다음 환경이 준비되어 있어야 합니다.

Node.js 18+

CLI 도구 실행을 위해 Node.js 18 버전 이상이 필요합니다.

React 18+ 프로젝트

Next.js, Vite, CRA 등 React 18 이상 기반의 프로젝트가 필요합니다.

TailwindCSS 3.4+

모든 컴포넌트는 TailwindCSS로 스타일링되어 있습니다.

GitHub 계정 (MSUB-Core Organization 멤버)

패키지 다운로드를 위해 GitHub 인증이 필요합니다.

GitHub Token 설정

MSUB/ui CLI는 GitHub Packages에서 배포되므로, 먼저 GitHub Personal Access Token을 발급받아야 합니다.

1. GitHub Token 발급

  1. GitHub에 로그인 후 Settings로 이동합니다.
  2. 좌측 하단 Developer settings를 클릭합니다.
  3. Personal access tokens → Tokens (classic)을 선택합니다.
  4. Generate new token (classic)을 클릭합니다.
  5. Token 이름을 입력합니다 (예: msub-ui-cli)
  6. 권한에서 read:packages를 체크합니다.
  7. Generate token을 클릭하고 생성된 토큰을 복사합니다.

팁: 토큰은 생성 직후에만 볼 수 있으므로 안전한 곳에 저장해 두세요.

2. .npmrc 파일 설정

프로젝트 루트 또는 홈 디렉토리(~/.npmrc)에.npmrc 파일을 생성하고 다음 내용을 추가합니다.

.npmrc
@msub-core:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

YOUR_GITHUB_TOKEN 부분을 발급받은 토큰으로 교체합니다.

3. 환경 변수로 설정 (선택)

토큰을 파일에 직접 저장하지 않고 환경 변수로 관리할 수도 있습니다.

.npmrc
@msub-core:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

그런 다음 쉘 설정 파일 (~/.zshrc 또는~/.bashrc)에 다음을 추가합니다.

Terminal
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

설치

1. 프로젝트 초기화

Terminal
npx @msub-core/ui-cli init

이 명령어를 실행하면 대화형 프롬프트가 시작됩니다.

init 프롬프트 예시
✔ TailwindCSS 설정 파일 경로? … tailwind.config.ts
✔ 글로벌 CSS 파일 경로? … src/styles/globals.css
✔ 컴포넌트 설치 경로? … src/components/ui
✔ 유틸리티 함수 경로? … src/lib/utils
✔ 다크모드를 사용하시나요? … yes

설정 완료! msub.json 파일이 생성되었습니다.

완료되면 프로젝트 루트에 msub.json 설정 파일이 생성됩니다.

msub.json
{
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "src/styles/globals.css"
  },
  "aliases": {
    "components": "src/components/ui",
    "utils": "src/lib/utils"
  },
  "darkMode": true
}

2. 컴포넌트 추가

Terminal
npx @msub-core/ui-cli add button

원하는 컴포넌트를 프로젝트에 추가합니다. 여러 컴포넌트를 동시에 추가할 수도 있습니다.

Terminal
npx @msub-core/ui-cli add button input card dialog

컴포넌트 목록 확인은 다음 명령어로 가능합니다.

Terminal
npx @msub-core/ui-cli list

3. 사용

추가된 컴포넌트는 설정한 경로에 소스 코드로 복사됩니다. 직접 import하여 사용할 수 있습니다.

TSX
import { Button } from "@/components/ui/button"

export default function Example() {
  return (
    <Button variant="default" size="lg">
      Click me
    </Button>
  )
}

다크모드

다크모드는 선택적으로 지원됩니다. init 명령어 실행 시 다크모드 사용 여부를 선택할 수 있습니다.

다음 단계