Skip to Content
Getting StartedQuick Start

Quick Start

React 19 앱에서 제품 패키지 하나와 해당 스타일만 추가해 Vortex UI를 사용해보세요.

시작하기 전에

React / React DOM 19 앱과 Vortex Private Registry 접근 권한이 필요합니다. 레지스트리를 아직 등록하지 않았다면 다음 명령을 실행하세요.

npm config set @vortex:registry http://repo.calsplatz.com:4873
npm config set @cals:registry http://repo.calsplatz.com:4873

기존 앱에 패키지 추가

아래에서 앱에 맞는 제품 하나를 선택하세요. Cals와 iCignal의 Foundation 의존성은 자동으로 설치됩니다. 소비자 앱에서 Foundation을 별도로 설치하거나 import하지 않습니다.

Foundation

pnpm add @vortex/ui-foundation

앱 진입점에서 스타일을 한 번 import합니다.

import "@vortex/ui-foundation/styles"
import { Button, Card, CardContent } from "@vortex/ui-foundation"
 
export default function App() {
  return (
    <Card>
      <CardContent>
        <Button>저장</Button>
      </CardContent>
    </Card>
  )
}

Cals

pnpm add @vortex/ui-cals

앱 진입점에서 스타일을 한 번 import합니다.

import "@vortex/ui-cals/styles"
import { Button, Card, CardContent } from "@vortex/ui-cals"
 
export default function App() {
  return (
    <Card>
      <CardContent>
        <Button title="저장" />
      </CardContent>
    </Card>
  )
}

iCignal

pnpm add @vortex/ui-icignal

앱 진입점에서 스타일을 한 번 import합니다.

import "@vortex/ui-icignal/styles"
import { Button, Card, CardContent } from "@vortex/ui-icignal"
 
export default function App() {
  return (
    <Card>
      <CardContent>
        <Button>저장</Button>
      </CardContent>
    </Card>
  )
}

이제 앱의 개발 서버를 실행하세요. UI에 필요한 유틸리티, 토큰, 폰트, 다크 모드 스타일은 패키지의 컴파일된 CSS에 포함되어 있습니다. Tailwind/PostCSS 설치나 설정, preset, content/@source, cn 함수 작성, TypeScript 경로 별칭은 패키지 사용에 필요하지 않습니다.

다크 모드는 html 등 상위 요소에 dark 클래스를 적용해 전환합니다. 테마 선택 UI와 저장은 앱에서 처리하세요. 특정 컴포넌트의 Provider, 라우터, 데이터 등 기능별 요구사항은 해당 문서를 따릅니다.

선택 사항: 앱 자체 Tailwind CSS v4 유틸리티

패키지 UI가 아니라 앱 코드에서 Tailwind 클래스를 직접 작성하는 경우에만 앱의 Tailwind v4 빌드를 구성하세요. 앱 CSS에 선택한 제품의 tailwind-config를 추가할 수 있습니다. Cals 예시는 다음과 같습니다.

@import "tailwindcss";
@import "@vortex/ui-cals/tailwind-config";

Foundation은 @vortex/ui-foundation/tailwind-config, iCignal은 @vortex/ui-icignal/tailwind-config를 사용합니다. 이 선택적 설정은 컴포넌트 CSS가 아니므로 해당 제품의 styles import는 계속 유지하세요. 자세한 내용은 설치 가이드를 참고하세요.

Next.js 앱에서 사용

React 19 기반 Next.js 앱에서도 동일한 설치 흐름을 사용합니다. Foundation을 선택한 경우 app/layout.tsx에서 전역 스타일을 import하세요.

import type { ReactNode } from "react"
import "@vortex/ui-foundation/styles"
 
export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="ko">
      <body>{children}</body>
    </html>
  )
}

상호작용이 필요한 페이지나 컴포넌트는 Next.js의 Client Component 규칙을 따릅니다.

"use client"
 
import { Button } from "@vortex/ui-foundation"
 
export default function Home() {
  return <Button>시작하기</Button>
}

Next.js 앱에서 Tailwind를 선택하지 않아도 Vortex 패키지의 스타일을 사용할 수 있습니다.

별도 흐름: CLI로 새 프로젝트 생성

앱이 아직 없다면 Vortex CLI의 템플릿으로 시작할 수 있습니다.

Foundation

npx @vortex/cli init my-app --template vite-foundation
cd my-app
pnpm install
pnpm dev

Cals

npx @vortex/cli init my-cals-app --template vite-cals
cd my-cals-app
pnpm install
pnpm dev

iCignal

npx @vortex/cli init my-icignal-app --template vite-icignal
cd my-icignal-app
pnpm install
pnpm dev

템플릿은 React, TypeScript, 선택한 UI 패키지, .npmrc 및 앱 개발 설정을 제공합니다. 템플릿에 포함된 Tailwind나 경로 별칭은 배포된 UI 패키지의 필수 소비자 설정이 아닙니다.

별도 흐름: CLI로 컴포넌트 소스 복사

패키지 import 대신 컴포넌트 소스를 직접 수정하려면 CLI의 add를 사용합니다.

npx @vortex/cli add button

여러 컴포넌트를 복사하거나 목록을 확인할 수도 있습니다.

npx @vortex/cli add button input card select
npx @vortex/cli list

복사한 소스에는 앱의 Tailwind 빌드, 경로 별칭, 의존성이 필요할 수 있습니다. CLI/템플릿 가이드를 따르세요. 패키지의 완성된 CSS를 사용하는 흐름과 소스 복사 흐름은 서로 다릅니다.

문제 해결

  • 설치 오류: 레지스트리 주소, 접근 권한과 인증을 확인하세요.
  • UI 스타일 누락: 선택한 제품의 styles가 전역 진입점에 있는지 확인하세요. Cals/iCignal 사용 시 Foundation 스타일을 추가하지 않습니다.
  • 직접 작성한 Tailwind 클래스 누락: 선택 사항의 앱 Tailwind v4 설정을 확인하세요.
  • Provider 오류: 컴포넌트 문서의 기능별 요구사항을 확인하세요.
  • 복사한 소스의 경로 오류: CLI 소스 복사 가이드에서 앱 경로 설정을 확인하세요. 배포 패키지 사용에는 @/ 별칭이 필요하지 않습니다.

다음 단계

Last updated on
Introduction