설치 (Getting Started)
사전 준비: GitHub Packages 레지스트리 설정
@coldsurfers/ocean-road는 npm이 아닌 GitHub Packages에 배포되어 있습니다.
설치 전에 프로젝트 루트에 .npmrc 파일을 만들어 레지스트리를 지정하세요.
.npmrc
@coldsurfers:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
GITHUB_TOKEN은 read:packages 권한이 있는 GitHub Personal Access Token입니다.
환경변수로 설정하거나 .env 파일에서 로드하세요. 토큰 값을 직접 커밋하지 마세요.
패키지 설치
# pnpm
pnpm add @coldsurfers/ocean-road @coldsurfers/ocean-road-design-tokens
# npm
npm install @coldsurfers/ocean-road @coldsurfers/ocean-road-design-tokens
# yarn
yarn add @coldsurfers/ocean-road @coldsurfers/ocean-road-design-tokens
Peer Dependencies 설치
필수
pnpm add @emotion/css @emotion/react @emotion/styled framer-motion lucide-react overlay-kit
| 패키지 |
버전 |
용도 |
@emotion/css |
^11.10.6 |
CSS-in-JS 스타일링 |
@emotion/react |
^11.10.6 |
Emotion React 통합 |
@emotion/styled |
^11.10.6 |
styled 컴포넌트 |
framer-motion |
^11.11.13 |
애니메이션 |
lucide-react |
^0.469.0 |
아이콘 |
overlay-kit |
^1.8.6 |
Modal/Toast 오버레이 |
선택 (Next.js 사용 시)
./next 진입점을 사용한다면 next 패키지가 필요합니다.
진입점 (Entry Points)
| 진입점 |
import 경로 |
용도 |
| 기본 (웹) |
@coldsurfers/ocean-road |
React 웹 컴포넌트 |
| Next.js |
@coldsurfers/ocean-road/next |
Next.js 전용 컴포넌트 |
빠른 시작
1. ColorSchemeProvider 설정
앱 최상단에서 ColorSchemeProvider로 트리를 감쌉니다.
import { ColorSchemeProvider } from '@coldsurfers/ocean-road'
export default function App({ children }: { children: React.ReactNode }) {
return (
<ColorSchemeProvider colorScheme="light">
{children}
</ColorSchemeProvider>
)
}
| prop |
타입 |
기본값 |
설명 |
colorScheme |
'light' | 'dark' | 'userPreference' |
'light' |
초기 색상 테마 |
2. 컴포넌트 사용
import { Button, Text } from '@coldsurfers/ocean-road'
export default function MyPage() {
return (
<>
<Text weight="bold">Hello, Ocean Road</Text>
<Button variant="indigo" onClick={() => alert('clicked!')}>
시작하기
</Button>
</>
)
}
3. Next.js 전용 컴포넌트 사용
./next 진입점의 컴포넌트는 반드시 해당 경로로 import해야 합니다.
import { AppHeader, RouteLoading } from '@coldsurfers/ocean-road/next'