메인 콘텐츠로 건너뛰기

자주 묻는 질문

Dropup에 관한 일반적인 질문과 답변입니다.

일반​

Dropup이란 무엇인가요?​

Dropup은 파일 업로드를 위한 경량 헤드리스 React 라이브러리입니다. 드래그 앤 드롭 기능, 파일 유효성 검사, 업로드 진행률 추적, 클라우드 스토리지 지원을 모두 gzip 압축 시 10KB 미만의 패키지에 담았습니다.

"헤드리스"란 무엇인가요?​

헤드리스는 Dropup에 UI 컴포넌트가 포함되어 있지 않다는 의미입니다. 로직과 상태 관리를 제공하고, UI는 원하는 대로 구축할 수 있습니다. 이를 통해 모양과 느낌을 완전히 제어할 수 있습니다.

번들 크기는 어떻게 되나요?​

  • 코어 (@samithahansaka/dropup): gzip 압축 시 10KB 미만
  • 클라우드 지원 추가: 프로바이더당 +2KB
  • 이미지 처리 추가: +5KB
  • tus 프로토콜 추가: +3KB (tus-js-client 피어 의존성 필요)

TypeScript를 지원하나요?​

네! Dropup은 TypeScript로 작성되었으며 포괄적인 타입 정의를 포함합니다. @types 패키지가 필요 없습니다.

어떤 React 버전이 필요한가요?​

React 16.8+ (훅 지원 필요).

사용법​

파일을 어떻게 업로드하나요?​

const { files, actions } = useDropup({
  upload: { url: '/api/upload' },
});

// 모든 파일 업로드
actions.upload();

// 특정 파일 업로드
actions.upload(['file-id-1', 'file-id-2']);

유효성 검사 오류를 어떻게 처리하나요?​

useDropup({
  accept: 'image/*',
  maxSize: 5 * 1024 * 1024,

  onValidationError: (errors) => {
    errors.forEach(({ file, errors }) => {
      console.log(`${file.name}: ${errors.join(', ')}`);
    });
  },
});

커스텀 업로드 로직을 사용할 수 있나요?​

네! 설정 객체 대신 함수를 전달하세요:

useDropup({
  upload: async (file, options) => {
    const { signal, onProgress } = options;

    // 커스텀 업로드 로직
    const response = await customUpload(file.file, {
      signal,
      onProgress,
    });

    return { url: response.url };
  },
});

파일을 프로그래밍 방식으로 추가하려면 어떻게 하나요?​

const { actions } = useDropup();

// 클립보드에서
document.addEventListener('paste', (e) => {
  const files = e.clipboardData?.files;
  if (files) {
    actions.addFiles(files);
  }
});

여러 개의 드롭 영역을 사용할 수 있나요?​

네! 각 useDropup 호출은 독립적인 인스턴스를 생성합니다:

const images = useDropup({ accept: 'image/*' });
const documents = useDropup({ accept: '.pdf' });

// 별도로 사용
<div {...images.getDropProps()}>...</div>
<div {...documents.getDropProps()}>...</div>

업로드​

업로드 진행률을 어떻게 표시하나요?​

const { files } = useDropup({ upload: { url: '/api/upload' } });

{files.map(file => (
  <div key={file.id}>
    {file.name}: {file.progress}%
  </div>
))}

업로드를 어떻게 취소하나요?​

const { actions } = useDropup();

// 특정 파일 취소
actions.cancel('file-id');

// 모든 업로드 취소
actions.cancel();

실패한 업로드를 어떻게 재시도하나요?​

const { actions } = useDropup();

// 특정 파일 재시도
actions.retry(['file-id']);

// 모든 실패한 업로드 재시도
actions.retry();

청크 업로드를 지원하나요?​

네! createChunkedUploader를 사용하세요:

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

useDropup({
  upload: createChunkedUploader({
    url: '/api/upload/chunk',
    chunkSize: 5 * 1024 * 1024, // 5MB
  }),
});

S3에 직접 업로드할 수 있나요?​

네! 클라우드 업로더를 사용하세요:

import { createS3Uploader } from '@samithahansaka/dropup/cloud/s3';

useDropup({
  upload: createS3Uploader({
    getPresignedUrl: async (file) => {
      const res = await fetch('/api/s3/presign', {
        method: 'POST',
        body: JSON.stringify({ filename: file.name }),
      });
      return res.json();
    },
  }),
});

유효성 검사​

파일 유형을 어떻게 제한하나요?​

// MIME 타입으로
useDropup({ accept: 'image/*' });

// 확장자로
useDropup({ accept: '.pdf, .doc' });

// 여러 개
useDropup({ accept: ['image/*', 'application/pdf'] });

크기 제한을 어떻게 설정하나요?​

useDropup({
  maxSize: 10 * 1024 * 1024, // 최대 10MB
  minSize: 1024,             // 최소 1KB
});

파일 수를 어떻게 제한하나요?​

useDropup({
  maxFiles: 5,
});

커스텀 유효성 검사를 추가할 수 있나요?​

네! customRules를 사용하세요:

useDropup({
  customRules: [
    (file) => {
      if (file.name.includes('draft')) {
        return '초안 파일은 허용되지 않습니다';
      }
      return true;
    },
  ],
});

미리보기​

이미지 미리보기를 어떻게 표시하나요?​

미리보기는 기본적으로 활성화되어 있습니다:

const { files } = useDropup();

{files.map(file => (
  file.preview && <img src={file.preview} alt="" />
))}

미리보기 URL을 정리해야 하나요?​

아니요! Dropup은 파일이 제거되거나 컴포넌트가 언마운트될 때 자동으로 Object URL을 해제합니다.

미리보기를 비활성화할 수 있나요?​

useDropup({ generatePreviews: false });

문제 해결​

파일이 업로드되지 않습니다​

  1. upload가 구성되어 있는지 확인하세요:

    useDropup({ upload: { url: '/api/upload' } });

  2. actions.upload()를 호출했는지 확인하세요 (autoUpload: true가 아닌 경우)

  3. 브라우저 콘솔에서 네트워크 오류를 확인하세요

미리보기 URL이 작동하지 않습니다​

  1. 파일이 이미지인지 확인하세요
  2. generatePreviews가 false가 아닌지 확인하세요
  3. 파일 객체에 유효한 preview 속성이 있는지 확인하세요

드래그 앤 드롭이 작동하지 않습니다​

  1. 컨테이너 요소에 getDropProps()를 스프레드했는지 확인하세요
  2. 숨겨진 입력을 포함했는지 확인하세요: <input {...getInputProps()} />
  3. disabled가 true가 아닌지 확인하세요

TypeScript 오류​

  1. 최신 Dropup 버전으로 업데이트하세요
  2. tsconfig.json에 적절한 moduleResolution이 있는지 확인하세요
  3. @samithahansaka/dropup이 devDependencies가 아닌 dependencies에 있는지 확인하세요

메모리 누수​

  1. useDropup을 사용하는 컴포넌트가 제대로 언마운트되는지 확인하세요
  2. 필요한 경우 언마운트 전에 actions.reset()을 호출하세요
  3. 정리 없이 외부 상태에 파일을 저장하지 마세요

호환성​

Next.js와 함께 작동하나요?​

네! 'use client' 지시어를 사용하세요:

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

React Native와 함께 작동하나요?​

네! 네이티브 어댑터를 사용하세요:

import { NativeAdapter } from '@samithahansaka/dropup/native';

useDropup({ adapter: NativeAdapter });

SSR을 지원하나요?​

네! Dropup은 SSR 안전합니다. 브라우저 API를 사용할 수 있을 때만 사용합니다.

브라우저 지원은?​

모든 현대 브라우저:

  • Chrome 60+
  • Firefox 55+
  • Safari 12+
  • Edge 79+

기여​

어떻게 기여할 수 있나요?​

  1. 저장소를 포크하세요
  2. 기능 브랜치를 생성하세요
  3. 풀 리퀘스트를 제출하세요

자세한 내용은 CONTRIBUTING.md를 참조하세요.

버그를 어떻게 신고하나요?​

github.com/samithahansaka/dropup/issues에서 이슈를 열어주세요.

로드맵이 있나요?​

계획된 기능에 대해서는 GitHub 이슈 및 토론을 확인하세요.