Installation

Exem UI를 프로젝트에 설치하고 설정하는 방법을 안내합니다.

CLI로 시작하기

대화형 CLI가 패키지 설치, Tailwind 설정, 설정 파일 생성을 한 번에 처리합니다.

Terminal

npx @exem-ui/cli init

최신 프리릴리즈 버전을 사용하고 싶다면, @next 태그를 붙여 실행하세요.

Terminal

npx @exem-ui/cli@next init

CLI가 안내하는 단계

1패키지 매니저 — pnpm, npm, yarn, bun 중 자동 감지 및 선택
2프레임워크 — React 선택 시 @exem-ui/react 자동 포함
3Tailwind 버전 — v4, v3, 또는 미사용
4패키지 선택 — 프레임워크와 Tailwind 버전에 따른 기본값 자동 설정
5릴리즈 채널 — Stable(latest) 또는 Experimental(next)

완료되면 exem-ui.config.json 설정 파일과 Tailwind 설정이 자동 생성됩니다.

설정 변경 (Re-init)

이미 설치된 프로젝트에서 init을 다시 실행하면 기존 @exem-ui/* 패키지를 자동으로 제거한 후 새로 설치합니다. 릴리즈 채널 변경, 패키지 추가/제거, Tailwind 버전 전환 등에 활용할 수 있습니다.

Terminal

# 기존 설정을 감지하여 이전 선택값을 기본값으로 표시
npx @exem-ui/cli init

릴리즈 채널

채널	설명	package.json 버전
Stable (latest)	안정 릴리즈	`^0.3.2` (고정 버전)
Experimental (next)	develop 브랜치 최신	`next` (dist-tag)

next 채널을 선택하면 package.json에 특정 프리릴리즈 버전 대신 "next" dist-tag가 기록됩니다. pnpm update를 실행하면 항상 최신 프리릴리즈 버전으로 갱신됩니다.

수동 설치

CLI 없이 직접 패키지를 설치하고 설정하는 방법입니다.

1. 패키지 설치

Terminal

# 핵심 패키지 (필수)
pnpm add @exem-ui/core

# React 컴포넌트
pnpm add @exem-ui/react

# Tailwind CSS 통합 (택 1)
pnpm add @exem-ui/tailwindcss3   # v3 사용 시
pnpm add @exem-ui/tailwindcss4   # v4 사용 시

@exem-ui/core는 디자인 토큰과 CSS 변수를 제공하는 기반 패키지로, 모든 경우에 필요합니다.

2. Tailwind CSS 설정

Tailwind v4

CSS 엔트리 파일에 import를 추가합니다. JavaScript 설정 파일이 필요 없습니다.

globals.css

/* globals.css */
@import 'tailwindcss';
@import '@exem-ui/core/css';
@import '@exem-ui/tailwindcss4';
@import '@exem-ui/react/styles';

@variant dark (&:where(.dark, .dark *));

Import	역할
`@exem-ui/core/css`	글로벌 CSS 변수 (디자인 토큰 정의)
`@exem-ui/tailwindcss4`	CSS 변수를 Tailwind `@theme`으로 매핑 + 토큰 유틸리티 safelist
`@exem-ui/react/styles`	컴포넌트 내부 Tailwind 클래스의 CSS 생성 보장
`@variant dark (...)`	다크 모드 활성화 (`.dark` 클래스 기반)

Tailwind v4는 node_modules를 기본 스캔 대상에서 제외합니다. @exem-ui/react/styles를 import해야 컴포넌트 내부 스타일이 정상 적용됩니다.

Tailwind v3

tailwind.config.ts

import type { Config } from 'tailwindcss';
import exemPlugin from '@exem-ui/tailwindcss3/plugin';

const config: Config = {
  darkMode: 'class',
  plugins: [exemPlugin],
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@exem-ui/react/dist/**/*.{js,mjs}',
  ],
};

export default config;

globals.css

/* globals.css */
@import '@exem-ui/core/css';

@tailwind base;
@tailwind components;
@tailwind utilities;

3. 기본 스타일

배경색과 텍스트 색상을 디자인 토큰에 맞게 설정합니다.

globals.css

body {
  background-color: var(--color-background-primary);
  color: var(--color-text-primary);
}

패키지 구조

패키지	설명
`@exem-ui/core`	CSS 변수, 디자인 토큰, 순수 유틸, 타입, SVG 아이콘 원본
`@exem-ui/react`	React UI 컴포넌트 (22개) + 아이콘 (202개)
`@exem-ui/tailwindcss3`	Tailwind v3 플러그인
`@exem-ui/tailwindcss4`	Tailwind v4 CSS-first 테마
`@exem-ui/cli`	프로젝트 초기 설정 CLI

사전 요구사항

이름	버전	비고
Node.js	`>= 18`
React	`>= 19`	@exem-ui/react 사용 시
Tailwind CSS	`>= 3.0 또는 >= 4.0`	Tailwind 통합 사용 시