Install

Fleet UI는 Track A / Track B 두 가지 설치 트랙을 제공해요.
어떤 트랙이 맞는지 고르려면 Quick Start에서 트랙 선택하기를 먼저 확인해요.

TL;DR

아래만 따라 하면 “테마가 적용되는 상태”까지 빠르게 만들 수 있어요.

1. 트랙을 고르기: Quick Start에서 트랙 선택하기
2. 엔트리 파일에 side-effect import 넣기
   • Track A: import '@fleet-ui/local/core/unistyles';
   • Track B: import '@fleet-ui/core/unistyles';
3. 필수 런타임 deps 설치하기: react-native-unistyles, react-native-reanimated, react-native-gesture-handler, react-native-worklets
4. Track A라면: init → add → doctor
5. Track B라면: 패키지 설치 → 엔트리 import → peerDeps 설치 → Babel 체크

목차

• 공통 숙지 사항
• Track A (CLI Based Local Install)
  • init
  • add
  • doctor
• Track B (NPM package install)
• Troubleshooting

공통 숙지 사항

두 트랙 모두 아래 3가지를 먼저 잡아두면, 설치 중에 헤매는 시간이 줄어요.

엔트리 파일 찾기

Unistyles 설정은 앱 시작 시점에 등록돼야 해요. 그래서 엔트리 파일에서 @fleet-ui/core/unistyles(또는 Track A의 local 경로)를 import해야 해요.

참고: Unistyles Configuration

• Expo Router(권장): 보통 app/_layout.tsx가 엔트리 파일이에요.
• react-navigation/native(권장) 기반 프로젝트: 보통 App.tsx 또는 index.tsx가 엔트리 파일이에요.
• main.ts 같은 커스텀 엔트리가 있나요? → 그 파일이 엔트리 파일이에요.

Track A의 fleet-ui init은 엔트리 파일을 자동 탐지해서 import를 넣으려고 시도해요(기본값은 Expo Router의 app/_layout.tsx예요).

완료 기준: 엔트리 파일이 어디인지 팀이 합의했고, 그 파일을 직접 열 수 있어요.

Track에 따라 import 경로(alias)가 달라요

Track A는 local suffix가 붙은 alias를 써요. 필요하면 프로젝트 내부에서 alias를 바꿔서 운영할 수도 있어요.

• Track A (CLI Based Local Install)

import '@fleet-ui/local/core/unistyles';

• Track B (Package Manager Based Install)

import '@fleet-ui/core/unistyles';

완료 기준: 엔트리 파일에 위 import 중 하나가 “딱 1번” 들어가 있어요.

필수 런타임 의존성

Fleet UI는 React Native 앱에서 자주 함께 쓰는 런타임 의존성을 전제로 해요.

버전 호환성 테이블

Fleet UI는 최신 버전보다 안정성을 우선해요. 릴리즈된 지 1~2개월 정도 지나 마이너 패치 안정성이 확보된 버전을 기준 종속성으로 사용해요. 최신 버전이나 구버전 의존성 설치가 필요하다면 아래 테이블을 참고하세요.

참고: Reanimated 4는 React Native New Architecture에서만 동작해요. Old Architecture를 사용 중이라면 Reanimated 3.x를 사용하세요.

Fleet UI v0.2.0 테스트 조합:

• React: 19.1.0
• React Native: 0.81.5
• Reanimated: 4.1.5
• Worklets: 0.6.1
• Expo SDK: 54

자세한 호환성 정보는 Reanimated Compatibility Guide를 참고하세요.

1. 모든 트랙 공통

아래 4개는 거의 모든 환경에서 필요하고, 누락되면 동작에 영향을 줄 수 있어요.

• pnpm

pnpm add react-native-unistyles react-native-reanimated react-native-gesture-handler react-native-worklets

• yarn

yarn add react-native-unistyles react-native-reanimated react-native-gesture-handler react-native-worklets

• npm

npm install react-native-unistyles react-native-reanimated react-native-gesture-handler react-native-worklets

• bun

bun add react-native-unistyles react-native-reanimated react-native-gesture-handler react-native-worklets

• Expo

npx expo install react-native-unistyles react-native-reanimated react-native-gesture-handler react-native-worklets

2. 자주 필요/컴포넌트별(선택)

아래 의존성은 컴포넌트/환경에 따라 필요할 수 있어요.

• (공통적으로 자주) react-native-safe-area-context, react-native-svg
• (주로 Expo 환경에서) expo-blur, expo-image, expo-linear-gradient

참고: Track A에서 fleet-ui init/fleet-ui doctor를 실행하면 “선택 의존성”까지 포함해 경고가 뜰 수 있어요. 경고가 떠도, 지금 쓰는 컴포넌트에 필요한지를 기준으로 설치하면 돼요.

완료 기준: 필수 런타임 deps 4개가 설치돼 있고, 앱이 실행될 준비가 됐어요.

Track A (CLI Based Local Install)

Overview

<project-root>/
├─ app/
│  └─ _layout.tsx
├─ fleet-ui/
│  ├─ core/
│  └─ components/
└─ fleet-ui.json

1. init (core 설치 + alias/config 자동 세팅)

pnpm dlx @fleet-ui/cli init

init은 아래 작업을 자동으로 진행해요.

• fleet-ui.json 생성(경로/alias/엔트리 파일 기록)
• 엔트리에 @fleet-ui/local/core/unistyles import 자동 삽입
• TypeScript alias(tsconfig.json paths) 설정
• Babel alias(module-resolver) 설정
• Unistyles plugin의 autoProcessImports 정합
• 필수/개발 의존성 누락 시 설치 커맨드 안내

완료 기준: fleet-ui.json이 생겼고, 엔트리 파일에 @fleet-ui/local/core/unistyles import가 들어갔어요.

옵션(필요할 때만):

# 예: 다른 프로젝트 루트에서 실행할 때
pnpm dlx @fleet-ui/cli init --cwd ./apps/my-app
 
# 예: 설치 경로를 바꾸고 싶을 때
pnpm dlx @fleet-ui/cli init --core-dir src/fleet-ui/core --components-dir src/fleet-ui/components
 
# 예: alias prefix를 바꾸고 싶을 때
pnpm dlx @fleet-ui/cli init --alias @fleet-ui/local
 
# 예: 엔트리 파일을 직접 지정할 때 (자동 감지가 안 될 때 유용해요)
pnpm dlx @fleet-ui/cli init --entry src/App.tsx
 
# 예: 모노레포나 커스텀 구조에서 엔트리 파일 지정
pnpm dlx @fleet-ui/cli init --cwd ./apps/mobile --entry app/index.tsx

init 옵션 전체 목록

Tip: 엔트리 파일 자동 감지가 실패하면 --entry 옵션으로 직접 지정하세요. 모노레포나 커스텀 프로젝트 구조에서 유용해요.

2. init 이후 “정상 상태” 확인

2.1. 엔트리 import가 들어갔는지

Expo Router 기준:

// app/_layout.tsx
import '@fleet-ui/local/core/unistyles';

2.2. TypeScript paths(alias)가 들어갔는지

tsconfig.json (개념 예시):

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@fleet-ui/local/*": ["fleet-ui/*"]
    }
  }
}

이 설정은 타입/에디터를 위한 것이고, 런타임(Metro/Babel)도 별도로 맞춰줘야 해요.

2.3. Babel 설정이 맞는지(런타임 alias + reanimated + unistyles)

babel.config.js(또는 babel.config.cjs)에서 핵심은 3가지다.

1. module-resolver로 alias를 런타임에서 해석
2. react-native-unistyles/plugin의 autoProcessImports에 @fleet-ui/local 포함
3. react-native-reanimated/plugin은 plugins 배열의 마지막

개념 예시:

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: [
      [
        'module-resolver',
        {
          alias: {
            '@fleet-ui/local': './fleet-ui',
          },
        },
      ],
      ['react-native-unistyles/plugin', { autoProcessImports: ['@fleet-ui/local'] }],
      'react-native-reanimated/plugin',
    ],
  };
};

Track A에서는 init이 이 설정을 best-effort로 패치한다.

3. 컴포넌트 추가

필요한 컴포넌트만 골라서 가져와요.

pnpm dlx @fleet-ui/cli add Button Modal

add가 하는 일(요약):

• registry에서 컴포넌트 소스 복사
• 내부 import를 best-effort로 @fleet-ui/local/core 기준으로 맞춤
• 대상 디렉터리의 index.ts(barrel) 업데이트

4. 컴포넌트별 선택 의존성(자주 쓰는 예시)

아래는 “이 컴포넌트를 쓰면 추가로 필요해질 수 있는 deps”의 대표 예시예요.

설치 예시(Expo 권장):

npx expo install expo-blur expo-image expo-linear-gradient react-native-safe-area-context react-native-svg

참고: Expo 모듈 의존성을 줄이고 싶다면, 컴포넌트 추가 시 대체 옵션을 두는 방식으로 운영할 수도 있어요.

5. doctor(권장)

pnpm dlx @fleet-ui/cli doctor

doctor가 주로 확인하는 것:

• fleet-ui.json 존재
• 엔트리 import 존재
• tsconfig alias 존재
• babel alias + unistyles autoProcessImports 존재
• 필수/개발 의존성 누락

Track B (NPM package install)

목표: 설치/업데이트 안정성을 최우선으로 두고, 패키지 버전 업그레이드로 변경을 흡수해요.

1. 패키지 설치

pnpm add @fleet-ui/core @fleet-ui/components

2. 엔트리 import 추가(강제)

import '@fleet-ui/core/unistyles';

3. peerDependencies 설치(필수)

패키지 트랙에서는 런타임 의존성이 peerDependencies로 선언되므로, 앱에서 직접 설치해야 해요.

pnpm add react-native-unistyles react-native-reanimated react-native-gesture-handler react-native-worklets
pnpm add react-native-safe-area-context react-native-svg

Expo 기반 기능을 쓰는 컴포넌트(Blur/Image/Gradient 등)를 사용한다면:

pnpm add expo-blur expo-image expo-linear-gradient

Expo 프로젝트에서는 pnpm add 대신 npx expo install을 권장해요.

4. Babel 설정 체크(특히 Reanimated)

패키지 트랙이라고 해서 Reanimated 설정이 자동으로 끝나진 않아요.

• babel.config.js에 react-native-reanimated/plugin이 필요할 수 있어요
• plugins 배열의 마지막이어야 해요

최소 예시:

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: ['react-native-reanimated/plugin'],
  };
};

이미 다른 plugins가 있다면:

plugins: [
  // ...기존 plugins...
  'react-native-reanimated/plugin',
]

Troubleshooting (자주 하는 실수 체크리스트)

1) “unistyles가 적용되지 않음 / 테마가 안 먹음”

증상: 테마가 적용되지 않아요(색/타이포가 기본값처럼 보여요).

원인(자주): 엔트리 파일에 side-effect import가 빠졌어요.

해결(체크리스트): 아래를 위에서부터 확인해요.

• 엔트리 파일이 맞나요? (Expo Router면 보통 app/_layout.tsx)
• 엔트리 파일에 side-effect import가 있나요?
  • Track A: import '@fleet-ui/local/core/unistyles';
  • Track B: import '@fleet-ui/core/unistyles';
• import가 “렌더링 이후”에 들어가 있진 않나요? (파일 최상단에 두는 걸 권장해요.)

2) “@fleet-ui/local/* 모듈을 찾을 수 없음”(Track A)

증상: @fleet-ui/local/* 모듈을 찾을 수 없다고 나와요.

원인(자주): alias 설정이 타입/런타임 중 한쪽만 잡혀 있어요.

해결(체크리스트): 아래 3가지를 순서대로 확인해요.

• tsconfig.json의 paths가 잡혀 있나요?
• babel.config.js에 module-resolver alias가 있나요?
• react-native-unistyles/plugin의 autoProcessImports에 @fleet-ui/local이 포함돼 있나요?

3) “Reanimated 관련 에러 / 앱이 바로 크래시”

증상: Reanimated 관련 에러가 나거나 앱이 바로 크래시돼요.

원인(자주): Reanimated Babel 플러그인이 없거나, plugins 배열 마지막이 아니에요.

해결(체크리스트):

• babel.config.js에 react-native-reanimated/plugin이 있나요?
• plugins 배열의 마지막인가요?

4) “특정 expo 모듈(expo-blur/expo-image/expo-linear-gradient)을 찾을 수 없음”

증상: expo-blur/expo-image/expo-linear-gradient 같은 모듈을 찾을 수 없다고 나와요.

원인(자주): 해당 모듈을 쓰는 컴포넌트를 추가했는데 의존성을 설치하지 않았어요.

해결(체크리스트):

• 그 컴포넌트가 실제로 해당 의존성을 쓰는지 확인해요(위 표 참고)
• Expo라면 npx expo install <dep>로 설치하는 걸 권장해요