Quick Start

5분 안에 Vortex로 첫 컴포넌트를 만들어보세요!

시작하기 전에

다음 중 하나를 선택하세요:

CLI로 새 프로젝트 생성 (권장) - 모든 설정이 자동으로 완료됩니다
기존 프로젝트에 추가 - 이미 React 프로젝트가 있는 경우

방법 1: CLI로 새 프로젝트 생성 (권장)

Vortex CLI를 사용하면 모든 설정이 자동으로 완료됩니다.

Foundation (기본)


# 프로젝트 생성
npx @vortex/cli init my-app --template vite --theme foundation
 
# 프로젝트 이동
cd my-app
 
# 개발 서버 실행
pnpm dev

브라우저에서 http://localhost:5173을 열면 바로 동작하는 앱을 확인할 수 있습니다!

iCignal


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

Cals


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

CLI가 자동으로 설정하는 것들

✅ React 19 + Vite 7 + TypeScript 5
✅ Tailwind CSS 4.0 (@tailwindcss/postcss)
✅ Private npm registry (.npmrc)
✅ TypeScript path aliases (@/*)
✅ cn 유틸리티 함수
✅ 선택한 테마 패키지 (@vortex/ui-foundation, @vortex/ui-icignal, @vortex/ui-cals)
✅ 모든 의존성 자동 설치

방법 2: 기존 프로젝트에 추가

이미 React 프로젝트가 있다면 Vortex 컴포넌트를 추가할 수 있습니다.

1. Private Registry 설정


echo "registry=http://repo.calsplatz.com:4873" > .npmrc

2. 패키지 설치

Foundation:


pnpm add @vortex/ui-foundation

iCignal:


pnpm add @vortex/ui-foundation @vortex/ui-icignal

Cals:


pnpm add @vortex/ui-foundation @vortex/ui-cals

3. Tailwind CSS 설정


pnpm add -D tailwindcss@next @tailwindcss/postcss@next


import type { Config } from "tailwindcss";
 
export default {
  content: ["./src/**/*.{js,ts,jsx,tsx,mdx}"],
  theme: {
    extend: {},
  },
} satisfies Config;

4. cn 유틸리티 함수 추가


import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";
 
export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

첫 번째 컴포넌트 사용

Button 컴포넌트


import { Button } from "@vortex/ui-foundation";
 
export default function App() {
  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold mb-4">My Vortex App</h1>
      <Button>Click me</Button>
    </div>
  );
}

다양한 Variants


import { Button } from "@vortex/ui-foundation";
 
export default function App() {
  return (
    <div className="p-8 space-y-4">
      <h1 className="text-2xl font-bold mb-4">Button Variants</h1>
 
      <div className="space-x-2">
        <Button variant="default">Default</Button>
        <Button variant="secondary">Secondary</Button>
        <Button variant="destructive">Destructive</Button>
        <Button variant="outline">Outline</Button>
        <Button variant="ghost">Ghost</Button>
        <Button variant="link">Link</Button>
      </div>
 
      <div className="space-x-2">
        <Button size="sm">Small</Button>
        <Button size="default">Default</Button>
        <Button size="lg">Large</Button>
      </div>
    </div>
  );
}

CLI로 컴포넌트 추가

Vortex CLI를 사용하면 필요한 컴포넌트를 프로젝트에 추가할 수 있습니다.

단일 컴포넌트 추가


npx @vortex/cli add button

여러 컴포넌트 추가


npx @vortex/cli add button input card select

컴포넌트 목록 확인


npx @vortex/cli list

실전 예제

로그인 폼 만들기


import { Button } from "@vortex/ui-foundation";
import { Input } from "@vortex/ui-foundation";
import { Card } from "@vortex/ui-foundation";
 
export default function LoginForm() {
  return (
    <Card className="w-full max-w-md p-6">
      <h2 className="text-2xl font-bold mb-6">로그인</h2>
 
      <form className="space-y-4">
        <div>
          <label className="block text-sm font-medium mb-2">이메일</label>
          <Input type="email" placeholder="you@example.com" />
        </div>
 
        <div>
          <label className="block text-sm font-medium mb-2">비밀번호</label>
          <Input type="password" placeholder="••••••••" />
        </div>
 
        <Button className="w-full">로그인</Button>
      </form>
    </Card>
  );
}

사용자 프로필 카드


import { Card } from "@vortex/ui-foundation";
import { Button } from "@vortex/ui-foundation";
import { Badge } from "@vortex/ui-foundation";
 
export default function UserProfile() {
  return (
    <Card className="w-full max-w-sm p-6">
      <div className="flex items-center space-x-4 mb-4">
        <img src="/avatar.jpg" alt="User" className="w-16 h-16 rounded-full" />
        <div>
          <h3 className="font-semibold text-lg">홍길동</h3>
          <p className="text-sm text-muted-foreground">hong@example.com</p>
        </div>
      </div>
 
      <div className="space-y-2 mb-4">
        <Badge>프론트엔드</Badge>
        <Badge variant="secondary">React</Badge>
        <Badge variant="outline">TypeScript</Badge>
      </div>
 
      <div className="flex gap-2">
        <Button variant="outline" className="flex-1">
          메시지
        </Button>
        <Button className="flex-1">팔로우</Button>
      </div>
    </Card>
  );
}

Next.js 프로젝트

1. Next.js 프로젝트 생성


pnpm create next-app@latest my-next-app --typescript --tailwind --app
cd my-next-app

2. Private Registry 설정


echo "registry=http://repo.calsplatz.com:4873" > .npmrc

3. Vortex 패키지 설치


pnpm add @vortex/ui-foundation

4. 컴포넌트 사용


import { Button } from "@vortex/ui-foundation";
 
export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1 className="text-4xl font-bold mb-8">Welcome to Vortex + Next.js</h1>
      <Button>Get Started</Button>
    </main>
  );
}

테마별 특화 기능

iCignal 전용 컴포넌트


import { Button } from "@vortex/ui-foundation";
import { IcignalCard } from "@vortex/ui-icignal";
 
export default function IcignalApp() {
  return (
    <IcignalCard className="bg-icignal-primary">
      <h2>iCignal 전용 카드</h2>
      <Button>Click me</Button>
    </IcignalCard>
  );
}

Cals 전용 컴포넌트


import { Button } from "@vortex/ui-foundation";
import { CalsCard } from "@vortex/ui-cals";
 
export default function CalsApp() {
  return (
    <CalsCard className="bg-cals-primary">
      <h2>Cals 전용 카드</h2>
      <Button>Click me</Button>
    </CalsCard>
  );
}

문제 해결

컴포넌트를 찾을 수 없습니다

증상: Cannot find module '@vortex/ui-foundation'

해결:


# .npmrc 파일 확인
cat .npmrc
 
# 패키지 재설치
pnpm install

스타일이 적용되지 않습니다

증상: 컴포넌트가 스타일 없이 표시됨

해결:


/* globals.css 확인 */
@import "tailwindcss";

TypeScript 경로 오류

증상: Cannot find module '@/...'

해결:


// tsconfig.json 확인
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

다음 단계

컴포넌트

모든 컴포넌트와 사용 예제를 확인하세요.

패턴

실전 UI 패턴과 모범 사례를 배워보세요.

디자인 기초

색상, 타이포그래피, 간격 등을 알아보세요.

디자이너 가이드

Figma 파일과 디자인 토큰을 활용하세요.