@jyh-dev/kit

개발 과정에서 반복적으로 사용하던 훅, 유틸, UI 흐름을 정리한 React/TypeScript 라이브러리입니다.

여러 프로젝트를 진행하며 자주 필요했던 패턴과 아쉬웠던 부분들을 직접 다듬어왔고, 그동안은 가장 최근 프로젝트의 소스에서 필요한 코드를 복사해 재사용하는 방식으로 활용해왔습니다. 이번에는 이를 하나의 재사용 가능한 패키지로 정리해 npm으로 배포했습니다.

특정 프로젝트나 디자인 시스템에 강하게 종속되지 않도록 설계했으며, 실제 서비스 개발 경험을 바탕으로 다양한 프론트엔드 환경에서 자연스럽게 사용할 수 있는 범용성을 목표로 만들었습니다.

링크

• npm: https://www.npmjs.com/package/@jyh-dev/kit
• 문서: https://jyh-dev-kit.vercel.app/

설치

npm install @jyh-dev/kit

React Query를 사용하는 기능은 앱에서 QueryClientProvider가 설정되어 있어야 합니다.

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Page />
    </QueryClientProvider>
  );
}

사용 방식

기능별 subpath import를 권장합니다.

import { usePagination } from "@jyh-dev/kit/use-pagination";
import { useFileUploader } from "@jyh-dev/kit/use-file";
import { createQueryService } from "@jyh-dev/kit/create-query-service";

한 번에 가져오는 방식도 제공합니다.

import { usePagination, useSelection } from "@jyh-dev/kit";

제공 기능

Registry

• create-api-registry: API 함수 객체에 query key helper를 붙입니다.
• create-query-service: API 함수, query key, React Query hook을 한 선언에서 생성합니다.

Form

• use-file: 파일 선택, 검증, 기존 파일 반영, presigned URL 업로드 흐름을 다룹니다.
• use-draft-form: 폼 값을 storage에 임시 저장하고 복구합니다. React Hook Form과도 연결할 수 있습니다.

State

• use-object-state: 객체 상태를 patch, replace, reset 중심으로 다룹니다.
• use-selection: 체크박스/테이블 선택 상태를 scope-aware하게 관리합니다.
• use-url-state: 필터, 페이지, 정렬 상태를 URL query string과 동기화합니다.
• use-async-action: async action의 loading, data, error, abort 흐름을 관리합니다.
• use-pagination: page range, ellipsis, 이동 target, page size 변경 흐름을 계산합니다.

Realtime

• realtime: SSE, WebSocket, React Query invalidation bridge를 제공합니다.

UI

• promise-modal: alert, confirm, choice, custom modal을 Promise 흐름으로 다룹니다.
• table-primitives: HTML table 기반 loading, empty, skeleton, colgroup, 커스텀 UI 흐름을 제공합니다.

예시

import { usePagination } from "@jyh-dev/kit/use-pagination";

function PaginationView() {
  const pagination = usePagination({
    page: 10,
    totalPages: 30,
    onPageChange: (page) => {
      console.log(page);
    },
  });

  return (
    <nav>
      <button disabled={!pagination.canPrevious} onClick={pagination.previous}>
        이전
      </button>

      {pagination.items.map((item) =>
        item.type === "page" ? (
          <button key={item.key} onClick={() => pagination.setPage(item.page)}>
            {item.page}
          </button>
        ) : (
          <button
            key={item.key}
            onClick={() => pagination.setPage(item.targetPage)}
          >
            ...
          </button>
        ),
      )}

      <button disabled={!pagination.canNext} onClick={pagination.next}>
        다음
      </button>
    </nav>
  );
}

배포 구성

이 패키지는 ESM 기준으로 배포됩니다.

dist/kit/
  create-api-registry/
  create-query-service/
  promise-modal/
  realtime/
  table-primitives/
  use-async-action/
  use-draft-form/
  use-file/
  use-object-state/
  use-pagination/
  use-selection/
  use-url-state/