CLI

Chakra UI CLI는 커스텀 테마 토큰(색상, 시맨틱 토큰, 레시피 변형 등)에 대한 타입을 생성하고, 커뮤니티 스니펫과 프리미엄 Pro 블록을 프로젝트에 추가하는 데 사용하는 명령줄 도구예요.

출처: 문서

본문

Chakra UI CLI는 색상, 시맨틱 토큰, 레시피 변형 등 커스텀 테마 토큰에 대한 타입을 생성하는 데 사용할 수 있어요. 또한 커뮤니티 스니펫과 프리미엄 Pro 블록을 프로젝트에 추가할 수 있습니다.

설치 (Installation)

CLI를 사용하려면 프로젝트에 dev dependency로 설치해야 해요.

:::code-group

npm i -D @chakra-ui/cli

pnpm add -D @chakra-ui/cli

bun add -d @chakra-ui/cli

:::

:::warning

CLI 도구를 사용하려면 Node.js 버전이 >= 20.6.0인지 확인하세요.

:::

사용법 (Usage)

Chakra CLI를 사용해 선호하는 패키지 매니저로 아래 명령 중 하나를 실행하세요.

Usage: npx chakra [options] [command]

The official CLI for Chakra UI projects

Options:
  -V, --version               output the version number
  -h, --help                  display help for command

Commands:
  typegen [options] <source>  Generate theme and recipe typings
  snippet                     Add snippets to your project for better DX
  blocks                      Add Chakra UI Pro blocks to your project
  eject [options]             Take control over the default theme tokens and recipes
  help [command]              display help for command

`chakra typegen`

커스텀 테마에 대한 테마 및 레시피 타입을 생성해요. 프로젝트에서 자동완성과 타입 안전성을 제공하는 데 도움이 됩니다.

# 타입 생성
chakra typegen src/theme.ts

# 변경 사항을 감시하고 재빌드
chakra typegen src/theme.ts --watch

# props variant와 size에 대한 엄격한 타입 생성
chakra typegen src/theme.ts --strict

typegen을 언제 실행하나요?

typegen 명령은 개발 환경과 CI/CD 모두에서 동작해요. 로컬 사용에만 국한되지 않으며, 프로젝트가 빌드되거나 설치되는 모든 곳에서 실행해 생성된 타입을 최신 상태로 유지하세요.

typegen이 필수인가요?

다음 조건이 모두 해당한다면 typegen을 실행하세요.

TypeScript를 사용한다
Chakra 시스템(토큰, 시맨틱 토큰, 레시피, 슬롯 레시피 등)을 커스터마이즈한다
타입 안전한 자동완성과 엄격한 토큰 검증을 원한다

JavaScript만 사용하거나, 커스텀 Chakra 테마 타입 없이 TypeScript를 사용한다면 typegen은 선택사항이에요.

워크플로우 통합 (Workflow integration)

Chakra UI를 사용하는 프론트엔드 애플리케이션의 postinstall 또는 prepare 스크립트에 typegen을 추가하세요. 이렇게 하면 타입이 생성된 상태로 유지됩니다.

npm install / pnpm install / bun install 이후(로컬 개발)
빌드 전에 의존성이 설치되는 CI/CD 중
npm ci 등으로 실행되는 프로덕션 빌드에서

{
  "scripts": {
    "postinstall": "chakra typegen src/theme.ts",
    "prepare": "chakra typegen src/theme.ts"
  }
}

:::tip

모든 설치 후 타입을 원한다면 postinstall을 사용하세요. 패키지가 패킹될 때(게시용)도 실행되기를 원한다면 prepare를 사용하세요. typegen이 두 번 실행되지 않도록 하나만 선택하세요.

:::

CI/CD 전략

CI에서 타입 검사와 빌드 단계 전에 typegen을 실행하세요.

{
  "scripts": {
    "typegen": "chakra typegen src/theme.ts",
    "typecheck": "npm run typegen && tsc --noEmit",
    "build": "npm run typegen && your-build-command"
  }
}

이렇게 하면 오래되거나 누락된 Chakra 타입으로 인한 CI 실패를 방지할 수 있어요.

모노레포 설정 (Monorepo setup)

모노레포(예: pnpm workspaces)에서는 모노레포 루트가 아니라 Chakra UI에 의존하는 패키지—보통 프론트엔드 애플리케이션—에서 typegen을 실행하세요.

프론트엔드 패키지에 @chakra-ui/cli를 dev dependency로 설치합니다.
해당 패키지의 package.json에 postinstall 또는 prepare 스크립트를 추가합니다.

// packages/frontend/package.json
{
  "scripts": {
    "postinstall": "chakra typegen src/theme.ts"
  },
  "dependencies": {
    "@chakra-ui/react": "..."
  },
  "devDependencies": {
    "@chakra-ui/cli": "..."
  }
}

루트에서 pnpm install을 실행하면 해당 프론트엔드 패키지의 postinstall이 실행되어 올바른 위치에 타입이 생성돼요.

생성된 타입을 커밋해야 하나요?

기본적으로는 아니에요. CLI는 생성된 파일을 Chakra의 설치된 패키지 타입 디렉터리(node_modules/@chakra-ui/react/types/styled-system/generated)에 작성하는데, 이는 커밋해서는 안 됩니다.

리포지토리 안에 커스텀 --outdir을 사용한다면 팀의 codegen 정책을 따르세요. 대부분의 경우 생성된 파일을 커밋하는 것보다 CI에서 재생성하는 것이 더 좋아요.

`chakra snippet`

개발 속도를 높여 주는 유용한 컴포넌트 조합을 생성해요.

# 모든 스니펫 추가
chakra snippet add --all

# 특정 스니펫 추가
chakra snippet add button

# 사용 가능한 모든 스니펫 나열
chakra snippet list

# 커스텀 디렉터리 지정
chakra snippet add dialog --outdir ./components/custom

`chakra blocks`

Chakra UI Pro의 프리미엄 블록을 프로젝트에 추가해요. 전문적으로 설계되고 완전히 반응형이며, 필요에 맞게 커스터마이즈할 수 있는 컴포넌트입니다.

# 대화형 블록 선택
chakra blocks add

# 특정 블록의 모든 변형 추가
chakra blocks add hero

# 블록의 특정 변형 추가
chakra blocks add hero --variant "simple"

# 사용 가능한 블록 나열
chakra blocks list

# 특정 카테고리의 블록 나열
chakra blocks list --category "marketing"

# 다운로드하지 않고 블록 미리보기
chakra blocks add --dry-run --category "marketing"

# 출력 디렉터리 지정
chakra blocks add --outdir ./components/blocks

Pro API 키 설정 (Pro API Key Setup)

Pro 블록을 사용하려면 Chakra UI Pro 구독과 API 키가 필요해요.

Chakra UI Pro에서 API 키를 받습니다
환경 변수를 설정합니다.
```
export CHAKRA_UI_PRO_API_KEY="your-api-key"
```
또는 프로젝트 루트에 .env 파일을 만듭니다.
```
CHAKRA_UI_PRO_API_KEY=your-api-key
```
환경 변수를 사용한다면 영속성을 위해 셸 프로필(.bashrc, .zshrc 등)에 추가합니다

사용 가능한 옵션 (Available Options)

--variant <variant>: 모든 변형 대신 특정 변형을 추가합니다
--outdir <dir>: 블록의 출력 디렉터리를 지정합니다
--force: 기존 파일을 덮어씁니다
--dry-run: 파일을 쓰지 않고 무엇이 다운로드될지 미리 봅니다
--tsx: TypeScript JSX 형식을 강제합니다(기본적으로 자동 감지)

`chakra eject`

기본 테마 토큰과 레시피를 포함하는 파일을 생성해 완전히 제어할 수 있게 해 줘요.

# 토큰과 레시피를 프로젝트에 복사
chakra eject --outdir src/theme

FAQ

typegen은 로컬 개발 전용인가요?

아니요. typegen 명령은 개발 환경과 CI/CD 모두에서 동작해요. 설치 후 실행되도록 postinstall 또는 prepare에 추가하세요—로컬과 CI 파이프라인 모두에서요.

strictTokens에 typegen이 필요한가요?

네. strictTokens를 활성화한다면 로컬과 CI 워크플로우에서 typegen을 실행해 토큰 타입이 테마와 동기화되도록 하세요.

커스텀 토큰 자동완성이 동작하지 않나요?

타입을 생성한 후 자동완성이 나타나도록 "Restart TS Server"를 실행해야 해요.

또는 @chakra-ui/cli 패키지를 로컬에 dev dependency로 설치하고 chakra typegen 명령을 실행해 타입을 생성할 수도 있습니다.

CLI

CLI

본문