Skip to Content
Getting StartedInstallation

Installation

Vortex UI 패키지는 설치 → 스타일 import → 컴포넌트 사용으로 시작합니다. UI에 필요한 유틸리티, 디자인 토큰, 폰트, 다크 모드 스타일은 컴파일된 CSS에 포함되어 있습니다.

요구사항

  • React / React DOM: 19 버전의 앱
  • Node.js: v20.0.0 이상
  • 패키지 매니저: pnpm 9+ (권장) 또는 npm/yarn
  • Private Registry: Vortex 레지스트리에 접근 가능한 환경

레지스트리를 아직 등록하지 않았다면 다음 명령을 한 번 실행하세요. @vortex 패키지와 Cals 내부 의존성의 @cals 스코프를 해당 레지스트리에서 받도록 설정합니다.

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

CLI로 생성한 프로젝트에는 .npmrc가 포함됩니다. 사내 네트워크 접근 및 필요한 인증은 설치 전에 준비해야 합니다.

1. 제품 패키지 설치

앱에 맞는 제품 패키지 하나를 선택하세요.

Foundation

pnpm add @vortex/ui-foundation

Cals

pnpm add @vortex/ui-cals

iCignal

pnpm add @vortex/ui-icignal

Cals와 iCignal은 Foundation을 내부 의존성으로 자동 설치합니다. 소비자 앱에서 @vortex/ui-foundation을 따로 설치하거나 import할 필요가 없습니다.

2. 해당 제품의 스타일 import

앱 진입점 또는 프레임워크가 허용하는 전역 CSS 진입점에서 선택한 제품의 스타일만 한 번 import하세요.

Foundation

import "@vortex/ui-foundation/styles"

Cals

import "@vortex/ui-cals/styles"

iCignal

import "@vortex/ui-icignal/styles"

styles는 완성된 CSS입니다. 패키지 컴포넌트를 사용하기 위해 Tailwind CSS, PostCSS, Autoprefixer, Tailwind preset, content/@source 경로 또는 TypeScript 경로 별칭을 설정하지 않아도 됩니다. UI CSS 생성에 필요한 Tailwind/PostCSS 처리는 패키지 내부 빌드에서 수행합니다.

3. 같은 제품 패키지에서 컴포넌트 import

Foundation

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

Cals

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

iCignal

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

위 예제에는 앱 자체 Tailwind 유틸리티가 필요하지 않습니다. 컴포넌트별로 요구하는 React Context/Provider, 라우터, 데이터 설정은 해당 컴포넌트 문서를 따르세요. 스타일 설정이 불필요하다는 의미이지 React나 기능별 Provider까지 없어지는 것은 아닙니다.

다크 모드

다크 모드 토큰과 스타일도 styles에 포함됩니다. 앱에서 html 등 상위 요소의 dark 클래스를 켜거나 끄면 됩니다. 테마 선택 UI와 사용자 설정 저장은 앱에서 처리합니다.

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

앱 코드에서 className="p-8 bg-primary" 같은 Tailwind 유틸리티를 직접 작성할 때만 앱의 Tailwind CSS v4 빌드 환경을 별도로 구성하세요. 프레임워크에 맞는 Tailwind v4 설정을 사용하며, 이것은 Vortex UI 패키지 설치의 필수 단계가 아닙니다.

앱의 Tailwind CSS 진입점에는 선택한 제품의 tailwind-config를 추가할 수 있습니다.

Foundation

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

Cals

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

iCignal

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

tailwind-config는 앱 유틸리티 생성에 쓰는 선택적 설정이며 컴포넌트 CSS를 대신하지 않습니다. 앞서 안내한 해당 제품의 styles import는 그대로 유지하세요. 임의의 앱 유틸리티까지 패키지 CSS에 포함되어 있는 것은 아닙니다.

별도 흐름: CLI로 프로젝트 생성 또는 소스 복사

새 프로젝트를 템플릿으로 만들려면 CLI를 사용할 수 있습니다.

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

vite-cals, vite-icignal 템플릿도 선택할 수 있습니다. 템플릿에 포함된 Tailwind나 경로 별칭은 앱 개발을 위한 템플릿 설정이지, 배포된 UI 패키지를 사용하기 위한 필수 설정은 아닙니다.

컴포넌트 소스를 프로젝트에 복사해서 직접 수정하려면 다음 흐름을 사용합니다.

npx @vortex/cli add button

add는 패키지 import 방식과 다릅니다. 복사한 소스의 Tailwind 빌드, 경로 별칭, 의존성은 해당 CLI 및 템플릿 가이드에 따라 구성해야 하며, 이 소스 복사 흐름에는 패키지의 무설정 스타일 사용 방식이 그대로 적용되지 않습니다.

문제 해결

  • 패키지 설치 실패: 레지스트리 주소, 사내 네트워크 접근, 필요한 인증을 확인하세요.
  • 스타일 누락: 설치한 제품과 styles import의 제품명이 같은지, 전역 CSS 진입점에서 로드되는지 확인하세요. Cals/iCignal 사용 시 Foundation 스타일을 별도로 추가하지 마세요.
  • 앱 유틸리티 누락: UI 자체가 아니라 직접 작성한 Tailwind 클래스가 문제라면 선택 사항의 앱 Tailwind v4 설정을 확인하세요.
  • Provider 오류: 사용 중인 컴포넌트가 요구하는 Provider를 해당 컴포넌트 문서에서 확인하세요.

다음 단계

Last updated on
For DesignersCals 설치 가이드