설치
npm 패키지 또는 소스 복사로 PLY를 설치합니다.
npm 패키지
React 19 프로젝트에서 설치합니다. Base UI는 함께 설치됩니다.
pnpm add ply-uiVite의 src/main.tsx 또는 Next.js의 app/layout.tsx에서 공통 스타일을 한 번 불러옵니다.
import "ply-ui/styles.css";컴포넌트는 이름으로 가져옵니다. 필요한 컴포넌트만 개별 경로로 가져올 수도 있습니다.
import { Button } from "ply-ui/button";
import { Select } from "ply-ui/select";전체 진입점인 import { Button, Select } from "ply-ui"도 지원합니다. 타입은 패키지에 포함되어 있습니다. 기기의 테마를 자동으로 읽는 기능은 포함하지 않으며 html에 data-theme="light" 또는 data-theme="dark"를 지정합니다.
Next.js에서 상태나 이벤트를 다루는 화면에는 "use client"를 지정합니다. 패키지 내부 컴포넌트의 클라이언트 지시문은 보존됩니다.
문서 예제의 @/components/ui/select 같은 복사본 경로는 패키지를 사용할 때 ply-ui/select로 바꿉니다. 나머지 컴포넌트 사용법은 같습니다.
pnpm update ply-ui기본 설치는 외부 폰트를 요청하지 않습니다. 기존 Builder Sans 연결이 필요할 때만 import "ply-ui/fonts.css"를 추가합니다. 사용자 토큰은 패키지 스타일 다음에 불러오는 CSS에서 덮어씁니다.
소스 자동 추가
Node.js 22 이상과 pnpm이 있는 React 19 + TypeScript 프로젝트에서 실행합니다. PLY 저장소를 따로 받을 필요가 없습니다.
pnpm dlx ply-ui add button select선택한 TSX·CSS와 내부 의존 컴포넌트, 공통 토큰을 프로젝트에 복사합니다. 필요한 Base UI 의존성을 설치하고, Next.js·Vite 시작 파일에 공통 스타일 import를 추가합니다. 기존 테마 설정과 "use client"는 유지합니다. 별도 테마 지정이 없으면 라이트 테마입니다.
src 폴더가 있는 프로젝트에는 src/components/ui, 루트 app 구조의 Next.js에는 components/ui로 추가합니다. 감지한 소스·시작 파일 경로는 ply-ui.json에 저장해 다음 추가에서도 사용합니다.
# 추가 가능한 컴포넌트 목록
pnpm dlx ply-ui list
# 실제로 바꾸기 전에 계획 확인
pnpm dlx ply-ui add button --dry-run
# 모든 컴포넌트 추가
pnpm dlx ply-ui add --all
# 다른 프로젝트 또는 사용자 지정 구조
pnpm dlx ply-ui add select --cwd ../my-app --src src --entry src/main.tsx시작 파일을 하나로 판단할 수 없으면 --entry를 요청하고 중단합니다. --src·--entry는 대상 프로젝트 내부 상대 경로입니다.
기존 파일 내용이 다르면 어떤 컴포넌트도 복사하기 전에 중단합니다. 비교한 후 --overwrite를 지정하면 공통 파일을 포함한 충돌 파일을 교체합니다. 같은 파일은 다시 쓰지 않으며 스타일 import도 중복으로 추가하지 않습니다.
--no-install은 의존성 설치만, --no-setup은 의존성 설치와 시작 파일 연결을 모두 생략합니다. 다음 수동 설정은 이 옵션을 사용했을 때 참고합니다.
의존성
대상 프로젝트에서 설치합니다. React 19와 TypeScript를 기준으로 작성되었습니다.
pnpm add @base-ui/react@1.8.0Lucide 아이콘을 import하는 예제를 사용할 때는 pnpm add lucide-react도 실행합니다.
스타일
Vite에서는 src/main.tsx, Next.js에서는 src/app/layout.tsx에서 공통 스타일을 가져옵니다.
// src/main.tsx
import "./styles/theme.css";
// 선택 사항: Builder Sans. 생략하면 시스템 글꼴을 사용합니다.
import "./styles/fonts.css";html의 data-theme를 light 또는 dark로 지정합니다.
// src/app/layout.tsx
import "../styles/theme.css";
export default function Layout({ children }: { children: React.ReactNode }) {
return (
<html lang="ko" data-theme="light">
<body>{children}</body>
</html>
);
}사용
문서의 사용 코드는 @/가 src/를 가리킨다고 가정합니다. 별칭을 사용하지 않으면 상대 경로로 바꿉니다.
import { Button } from "@/components/ui/button";
export function SubmitButton() {
return <Button type="submit">저장</Button>;
}업데이트
복사한 파일은 대상 프로젝트에서 관리합니다. 원본을 업데이트해도 복사본은 자동으로 바뀌지 않습니다. --overwrite는 수정한 파일도 교체하므로 변경 내용을 비교한 뒤 사용합니다.
레지스트리 JSON은 public/r/에 생성됩니다. HTTP로 제공하는 경우 shadcn CLI에서도 해당 JSON 주소로 설치할 수 있습니다.