Dropup 시작하기

Dropup은 복잡한 업로드 로직을 모두 처리하면서 UI를 완전히 제어할 수 있는 경량 헤드리스 React 파일 업로드 라이브러리입니다.

왜 Dropup인가?

🪶 경량 - 코어는 gzip 압축 시 약 10KB에 불과합니다
🎨 헤드리스 - 훅 기반 API로 UI를 완전히 제어할 수 있습니다
📁 드래그 앤 드롭 - 드래그 앤 드롭 기능이 내장되어 있습니다
📊 진행률 추적 - 각 파일의 실시간 업로드 진행률을 확인할 수 있습니다
🔄 청크 업로드 - 대용량 파일을 분할하여 안정적으로 업로드합니다
☁️ 클라우드 지원 - S3, GCS, Azure용 헬퍼가 내장되어 있습니다
🖼️ 이미지 처리 - 압축 및 미리보기 생성 기능이 내장되어 있습니다
📱 크로스 플랫폼 - React DOM 및 React Native와 함께 작동합니다
🔒 TypeScript - 완벽한 TypeScript 지원

설치

선호하는 패키지 관리자를 사용하여 Dropup을 설치하세요:

npm install @samithahansaka/dropup

피어 의존성

Dropup은 React 16.8 이상(훅 지원용)이 필요합니다:

npm install react

빠른 시작

시작하기 위한 간단한 예제입니다:

import { useDropup } from '@samithahansaka/dropup';

function FileUploader() {
  const {
    files,
    state,
    actions,
    getDropProps,
    getInputProps
  } = useDropup({
    accept: 'image/*',
    maxSize: 10 * 1024 * 1024, // 10MB
    multiple: true,
  });

  return (
    <div>
      {/* 드롭 영역 */}
      <div
        {...getDropProps()}
        style={{
          border: state.isDragging ? '2px dashed blue' : '2px dashed gray',
          padding: 40,
          textAlign: 'center',
          cursor: 'pointer',
        }}
      >
        <input {...getInputProps()} />
        <p>파일을 여기에 드래그 앤 드롭하거나 클릭하여 선택하세요</p>
      </div>

      {/* 파일 목록 */}
      <ul>
        {files.map((file) => (
          <li key={file.id}>
            {file.name} - {file.status}
            {file.status === 'uploading' && ` (${file.progress}%)`}
            <button onClick={() => actions.remove(file.id)}>제거</button>
          </li>
        ))}
      </ul>

      {/* 업로드 버튼 */}
      {files.length > 0 && (
        <button onClick={() => actions.upload()}>
          모두 업로드
        </button>
      )}
    </div>
  );
}

핵심 개념

1. `useDropup` 훅

useDropup 훅은 메인 진입점입니다. 파일 업로드 UI를 구축하는 데 필요한 모든 것을 반환합니다:

const {
  files,           // 상태, 진행률 등이 포함된 파일 배열
  state,           // 전체 상태 (isDragging, isUploading, progress)
  actions,         // 업로드, 제거, 취소, 초기화 메서드
  getDropProps,    // 드롭 영역 요소용 props
  getInputProps,   // 숨겨진 파일 입력용 props
} = useDropup(options);

2. 파일 객체

files 배열의 각 파일에는 다음이 포함됩니다:

{
  id: string;          // 고유 식별자
  file: File;          // 원본 File 객체
  name: string;        // 파일 이름
  size: number;        // 파일 크기 (바이트)
  type: string;        // MIME 타입
  preview?: string;    // 미리보기 URL (이미지용)
  status: 'idle' | 'uploading' | 'complete' | 'error';
  progress: number;    // 업로드 진행률 (0-100)
  error?: Error;       // 업로드 실패 시 오류 객체
  uploadedUrl?: string; // 업로드 성공 후 URL
}

3. 액션

actions 객체는 업로드를 제어하는 메서드를 제공합니다:

actions.upload(fileIds?)    // 업로드 시작 (전체 또는 특정 파일)
actions.cancel(fileId?)     // 업로드 취소
actions.remove(fileId)      // 목록에서 파일 제거
actions.reset()             // 모든 파일 초기화
actions.retry(fileIds?)     // 실패한 업로드 재시도

업로드 구성

실제 업로드를 활성화하려면 업로드 설정을 제공하세요:

const { files } = useDropup({
  upload: {
    url: '/api/upload',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer token',
    },
  },
  autoUpload: true, // 파일이 추가되면 자동으로 업로드
});

다음 단계

유효성 검사 옵션 알아보기
더 많은 예제 보기
클라우드 스토리지 통합 살펴보기
전체 API 레퍼런스 확인하기

왜 Dropup인가?​

설치​

피어 의존성​

빠른 시작​

핵심 개념​

1. useDropup 훅​

2. 파일 객체​

3. 액션​

업로드 구성​

다음 단계​