@farmzone/fz-react-ui

Farmzone 사내 프로젝트에서 공통으로 쓰는 React 컴포넌트 라이브러리입니다. Tailwind CSS 기반 스타일링, Radix UI 프리미티브, tiptap 기반 리치 에디터를 포함합니다.

요구 사항

• React >=18 / React DOM >=18
• Node.js 20+
• Tailwind CSS v4 (스타일을 직접 통합하는 경우)

설치

npm install @farmzone/fz-react-ui

필수 peer dependency

아래 패키지들은 peerDependencies로 선언되어 있어 직접 설치해야 합니다 (라이브러리 번들에 포함되지 않음):

npm install react react-dom lucide-react react-router

• lucide-react — 아이콘. Sidebar, Pagination, Input, RichEditorToolbar 등 다수 컴포넌트가 사용합니다.
• react-router — Sidebar가 내부적으로 useNavigate/useLocation을 사용합니다.

선택 peer dependency

특정 컴포넌트를 쓸 때만 필요합니다. 해당 컴포넌트를 쓰지 않으면 설치하지 않아도 됩니다.

| 패키지 | 필요한 컴포넌트 | |---|---| | react-hook-form, @hookform/resolvers, zod | SubmitForm | | react-daum-postcode | SearchAddress |

스타일 설정

두 가지 방법 중 하나를 선택합니다.

옵션 A — 컴파일된 CSS 그대로 사용 (Tailwind를 직접 쓰지 않는 프로젝트)

import "@farmzone/fz-react-ui/styles";

옵션 B — 컨슈머 프로젝트의 Tailwind v4 빌드에 통합 (권장, 트리쉐이킹됨)

/* 프로젝트의 Tailwind 진입 CSS 파일에 추가 */
@import "@farmzone/fz-react-ui/tw.css";

tw.css는 fz-react-ui의 컴파일된 JS를 @source로 스캔하고, 라이브러리 전용 색상 토큰(--color-main-red 등)을 @theme으로 노출합니다. 컨슈머 프로젝트도 Tailwind v4를 쓰고 있어야 합니다.

사용 예시

import { Button, Input, Table } from "@farmzone/fz-react-ui";
import type { Column } from "@farmzone/fz-react-ui";

function UserSearch() {
  const [name, setName] = useState("");

  return (
    <div className="flex flex-col gap-3">
      <div className="flex items-end gap-2">
        <Input label="이름" value={name} onChange={(e) => setName(e.target.value)} />
        <Button variant="search" size="sm">검색</Button>
      </div>
      <Table columns={columns as Array<Column<unknown>>} data={rows} rowKey="id" />
    </div>
  );
}

컴포넌트 조합 시 임의의 Tailwind 팔레트 클래스(bg-blue-600 등)보다 라이브러리 자체 semantic 토큰(bg-main, Button의 variant/size prop 등)을 우선 사용하세요 — 컴파일된 CSS에 없는 클래스는 조용히 무시됩니다.

컴포넌트

Form / Input Input, Textarea, Checkbox, Switch, Slider, Radio / RadioGroup, Select / SelectGroup, DatePicker, SearchBar, SearchAddress, SubmitForm, DebouncedButton

Feedback / Overlay Modal, ToastProvider (+ toast), Tooltip, Popover / SimplePopover, Empty, Loading / LoadingOverlay, Spinner, Skeleton, confirmModal

Layout / Navigation Sidebar, Tab, MultiTab, BreadCrumb, Pagination, PageFilter, ScrollArea

Data Display Table, Badge, Carousel, FilePreviewViewer, DetailModalFrame / DetailPageFrame / DetailContent

Upload BaseUploader, ExcelUploader, FileUploader

Editor RichEditor (+ RichEditorContent, RichEditorToolbar, useRichEditor) — tiptap 기반 리치 텍스트 에디터. 멘션, 테이블, 이미지, 정렬 등을 지원합니다.

Hooks useModal, useCustomBlocker, useBlockModalConfirm, useScrollToTop, useFilePreviewViewer, useParams, useMultiTabStore, useBreadCrumbItems

Utils cn, buttonVariants, textVariants, Z_INDEX

전체 export 목록과 정확한 타입은 dist/index.d.ts를 참고하세요.

로컬 개발

pnpm i --frozen-lockfile   # 이 리포는 pnpm 사용
pnpm dev                   # tsup watch 빌드
pnpm storybook              # Storybook (localhost:6006)
pnpm build                  # dist/ 전체 빌드 (JS + CSS)
pnpm lint
pnpm typecheck

배포

main 브랜치에 머지되면 GitLab CI가 npm publish를 실행합니다 (.gitlab-ci.yml). 배포 전 package.json의 version을 수동으로 올려야 합니다 — 특히 peerDependencies 변경처럼 컨슈머 쪽 설치 요구사항이 바뀌는 경우 최소 minor 버전을 올리세요.