@blastlabs/utils

⚠️ 주의: 이 라이브러리는 사내 개발용이며, 현재 테스트 단계입니다.

React 프로젝트에서 자주 사용하는 유틸리티 훅(Hooks)과 개발용 컴포넌트 모음입니다.

설치

npm install @blastlabs/utils
# or
yarn add @blastlabs/utils
# or
pnpm add @blastlabs/utils

기능

📦 Hooks

프로젝트에서 자주 사용하는 커스텀 훅들을 제공합니다.

import { useDebounce, useToggle, useCopyToClipboard } from '@blastlabs/utils/hooks';

사용 가능한 Hooks

• useDebounce - 값의 변경을 지연시켜 성능 최적화
• useThrottle - 함수 실행 빈도를 제한하여 성능 최적화
• useToggle - boolean 상태를 쉽게 토글
• useCopyToClipboard - 클립보드 복사 기능
• useWindowSize - 윈도우 크기 추적
• usePrevious - 이전 값 추적
• useIntersectionObserver - Intersection Observer API 활용
• useEventListener - 이벤트 리스너 관리

🛠️ Development Components

개발 환경에서만 사용하는 유틸리티 컴포넌트들입니다.

import { DevPanel, FormDevTools, ApiLogger } from '@blastlabs/utils/components/dev';

IdSelector

개발 환경에서 여러 계정으로 빠르게 로그인할 수 있는 컴포넌트입니다.

import { IdSelector } from '@blastlabs/utils/components/dev';

const devAccounts = [
  { id: 'admin', pw: 'admin123', memo: '관리자' },
  { id: 'user1', pw: 'user123', memo: '일반 사용자' },
];

function App() {
  const handleLogin = async (id: string, pw: string) => {
    // 로그인 로직
    await loginApi(id, pw);
  };

  return (
    <div>
      {import.meta.env.DEV && (
        <IdSelector onLogin={handleLogin} infos={devAccounts} />
      )}
    </div>
  );
}

FormDevTools

react-hook-form의 상태를 실시간으로 시각화하는 개발용 컴포넌트입니다. DevPanel과 통합하거나 별도로 사용할 수 있습니다.

DevPanel과 함께 사용 (권장):

import { DevToolsProvider, DevPanel, useRegisterForm } from '@blastlabs/utils/components/dev';
import { useForm } from 'react-hook-form';

// Layout.tsx - Provider로 감싸기
function Layout() {
  return (
    <DevToolsProvider>
      <YourApp />
    </DevToolsProvider>
  );
}

// 페이지에서 form 등록
function MyFormPage() {
  const form = useForm({
    defaultValues: { username: '', email: '' }
  });

  // form을 DevPanel에 등록
  useRegisterForm(form);

  return (
    <form>
      <input {...form.register('username')} />
      <input {...form.register('email')} />
      <button>Submit</button>
    </form>
  );
}

// App.tsx - DevPanel 렌더링
function App() {
  return (
    <div>
      {import.meta.env.DEV && <DevPanel />}
    </div>
  );
}

별도 사용:

import { FormDevTools } from '@blastlabs/utils/components/dev';

function MyForm() {
  const form = useForm({
    defaultValues: { username: '', email: '' }
  });

  return (
    <form>
      <input {...form.register('username')} />
      <input {...form.register('email')} />
      <button>Submit</button>

      {import.meta.env.DEV && <FormDevTools form={form} />}
    </form>
  );
}

주요 기능:

• 폼 값(values) 실시간 확인
• 에러(errors) 상태 확인
• 변경된 필드(dirtyFields) 추적
• 터치된 필드(touchedFields) 확인
• 드래그 & 리사이즈 가능한 패널

DevPanel

여러 개발 도구를 하나의 패널에서 통합 관리하는 컴포넌트입니다.

import { DevToolsProvider, DevPanel, useRegisterForm } from '@blastlabs/utils/components/dev';

// Layout.tsx - 앱 상단에서 한 번만 감싸기
function Layout() {
  return (
    <DevToolsProvider>
      <YourApp />
    </DevToolsProvider>
  );
}

// 페이지에서 form 등록
function MyFormPage() {
  const form = useForm({
    defaultValues: { username: '', email: '' }
  });

  // Form DevTools 사용을 위해 form 등록
  useRegisterForm(form);

  return (
    <form>
      <input {...form.register('username')} />
      <input {...form.register('email')} />
      <button>Submit</button>
    </form>
  );
}

// App.tsx - DevPanel 렌더링
function App() {
  return (
    <div>
      {import.meta.env.DEV && <DevPanel />}
    </div>
  );
}

주요 기능:

• 📝 Form DevTools - react-hook-form 상태 시각화 (form 등록 필요)
• 🌍 Timezone DevTools - 타임존 정보 확인
• 📐 Window Size - 윈도우 크기 표시 (토글 가능)
• 🔍 Z-Index Debugger - z-index 값 시각화 (토글 가능)
• 각 도구 독립적 토글
• 드래그 & 리사이즈 가능한 패널

주의사항:

• DevPanel을 사용하려면 앱 상단에서 DevToolsProvider로 감싸야 합니다
• Form DevTools를 사용하려면 페이지에서 useRegisterForm로 form을 등록해야 합니다

ApiLogger

API 요청/응답을 로깅하고 모니터링하는 컴포넌트입니다.

import axios from 'axios';
import { ApiLogger, addApiLog } from '@blastlabs/utils/components/dev';

// Axios interceptor 설정
axios.interceptors.request.use(
  (config) => {
    config.metadata = { startTime: Date.now() };
    return config;
  },
  (error) => Promise.reject(error)
);

axios.interceptors.response.use(
  (response) => {
    const duration = Date.now() - response.config.metadata?.startTime;

    addApiLog({
      method: response.config.method?.toUpperCase() || 'GET',
      url: response.config.url || '',
      status: response.status,
      statusText: response.statusText,
      duration,
      requestBody: response.config.data,
      responseBody: response.data,
    });

    return response;
  },
  (error) => {
    const duration = Date.now() - error.config?.metadata?.startTime;

    addApiLog({
      method: error.config?.method?.toUpperCase() || 'GET',
      url: error.config?.url || '',
      status: error.response?.status,
      statusText: error.response?.statusText,
      duration,
      requestBody: error.config?.data,
      responseBody: error.response?.data,
      error: error.message,
    });

    return Promise.reject(error);
  }
);

function App() {
  return (
    <div>
      {import.meta.env.DEV && <ApiLogger />}
    </div>
  );
}

주요 기능:

• API 요청/응답 로그 수집
• 요청 메서드, URL, 상태 코드 표시
• 응답 시간(duration) 측정
• Request/Response Body 확인
• 로그 복사 및 삭제 기능

DevPanel

여러 개발 도구를 하나의 패널에서 관리할 수 있는 통합 컴포넌트입니다.

import { DevPanel } from '@blastlabs/utils/components/dev';

function App() {
  return (
    <div>
      {import.meta.env.DEV && <DevPanel />}
    </div>
  );
}

주요 기능:

• 윈도우 크기 표시
• 렌더 카운트 표시
• LocalStorage 삭제
• SessionStorage 삭제

ZIndexDebugger

페이지의 모든 z-index 값을 시각화하고 디버깅하는 도구입니다.

import { ZIndexDebugger } from '@blastlabs/utils/components/dev';

function App() {
  return (
    <div>
      {import.meta.env.DEV && <ZIndexDebugger />}
    </div>
  );
}

주요 기능:

• 모든 요소의 z-index 값 스캔
• 요소에 마우스 오버 시 하이라이트
• 클릭 시 해당 요소로 스크롤
• z-index 값 정렬 (높은 순/낮은 순)

WindowSizeDisplay

현재 윈도우 크기를 화면에 표시하는 간단한 컴포넌트입니다.

import { WindowSizeDisplay } from '@blastlabs/utils/components/dev';

function App() {
  return (
    <div>
      {import.meta.env.DEV && <WindowSizeDisplay />}
    </div>
  );
}

개발 환경 구분

Vite 프로젝트

{import.meta.env.DEV && <DevPanel />}

Create React App 프로젝트

{process.env.NODE_ENV === 'development' && <DevPanel />}

TypeScript 지원

모든 컴포넌트와 훅은 TypeScript로 작성되었으며, 타입 정의가 포함되어 있습니다.

import type { FormDevToolsProps, ApiLogEntry } from '@blastlabs/utils/components/dev';

🚀 CLI 도구

이 패키지는 프로젝트 설정을 자동화하는 CLI 도구를 제공합니다.

FSD Entity Generator

Feature-Sliced Design 아키텍처용 엔티티 스캐폴딩을 자동으로 생성합니다.

# entities 폴더로 이동
cd src/entities

# 엔티티 생성
npx blastlabs-generate-entity user
npx blastlabs-generate-entity my-new-entity

생성되는 구조:

user/
├── index.ts
├── api/
│   ├── get-user-list.ts
│   ├── get-user-detail.ts
│   ├── user-queries.ts
│   ├── index.ts
│   ├── mapper/
│   │   ├── map-user.ts
│   │   └── map-user-detail.ts
│   └── query/
│       └── user-list-query.ts
└── model/
    ├── user.ts
    └── user-detail.ts

특징:

• TanStack Query queryOptions 패턴 지원
• Zod 스키마 자동 생성
• API mapper 패턴 적용
• TypeScript 타입 안정성 보장

AI Rules Installer

Cursor, Claude Code용 AI 규칙을 프로젝트에 설치합니다.

# 프로젝트 루트에서 실행
npx blastlabs-init-ai-rules [options]

옵션:

• --fsd - FSD 아키텍처 규칙 포함
• --all - 모든 규칙 설치 (base + fsd)
• --list, -l - 설치 가능한 규칙 목록 보기
• --help, -h - 도움말 보기

예시:

# 기본 규칙만 설치
npx blastlabs-init-ai-rules

# FSD 아키텍처 규칙 포함
npx blastlabs-init-ai-rules --fsd

# 모든 규칙 설치
npx blastlabs-init-ai-rules --all

설치되는 파일:

.cursor/rules/*.mdc  # Cursor용 규칙
.claude/rules/*.md   # Claude Code용 규칙

포함된 규칙:

• TypeScript 표준
• React Hooks 가이드라인
• 테스트 작성 가이드
• 문서화 가이드라인
• Git 커밋 컨벤션
• FSD 아키텍처 (선택)

주의사항

• 개발용 컴포넌트(components/dev)는 프로덕션 환경에서 제외하는 것을 권장합니다.
• 개발 환경 구분을 위해 import.meta.env.DEV (Vite) 또는 process.env.NODE_ENV === 'development' (CRA)를 사용하세요.

문의

• [email protected]
• [email protected]

라이선스

ISC

기여

이슈나 PR은 언제든 환영합니다!