[웹에서 파일업로드 쉽게하기] Dropzone.js 완전 정복 가이드

Dropzone.js 완전 정복 가이드

목표
- Dropzone.js가 무엇인지, 왜 사용해야 하는지 이해
- 설치부터 기본 사용법, 커스터마이징까지 단계별로 배워보기
- 실제 예제 코드와 함께 실전 팁 제공

1. Dropzone.js란?

Dropzone.js는 HTML5 파일 업로드를 손쉽게 구현할 수 있도록 해주는 오픈소스 자바스크립트 라이브러리입니다.
- 드래그 앤 드롭: 마우스로 파일을 끌어다 놓기만 하면 바로 업로드가 시작됩니다.
- 프리뷰: 이미지 파일은 썸네일이 자동으로 표시됩니다.
- 다중 파일: 한 번에 여러 파일을 업로드할 수 있습니다.
- 백엔드 연동: Ajax를 통해 서버에 파일을 전송하고, 응답을 받아 처리합니다.

왜 Dropzone.js를 쓰나요?
- 사용자 경험: 직관적인 UI로 파일 업로드가 편리합니다.
- 개발 편의성: 복잡한 파일 업로드 로직을 직접 구현할 필요가 없습니다.
- 확장성: 옵션과 이벤트를 통해 거의 모든 요구사항을 만족시킬 수 있습니다.

2. 설치 방법

2.1 CDN 사용

가장 간단한 방법은 CDN을 이용하는 것입니다. index.html에 아래 코드를 추가합니다.

<link rel="stylesheet" href="https://unpkg.com/dropzone@5/dist/min/dropzone.min.css" />
<script src="https://unpkg.com/dropzone@5/dist/min/dropzone.min.js"></script>

Tip: 최신 버전은 unpkg에서 확인하세요.

2.2 NPM / Yarn

프로젝트에 npm을 사용한다면 다음 명령어로 설치합니다.

npm install dropzone
# 또는
yarn add dropzone

설치 후에는 import 혹은 require를 통해 사용합니다.

import Dropzone from 'dropzone';

주의: Dropzone.autoDiscover = false; 를 꼭 설정해 주어야 자동 초기화가 방지됩니다.

3. 기본 사용법

3.1 HTML

<form action="/upload" class="dropzone" id="myDropzone"></form>

• action 속성은 파일이 전송될 서버 엔드포인트를 지정합니다.
• class="dropzone" 은 Dropzone이 자동으로 인식하도록 해줍니다.

3.2 JavaScript

Dropzone.autoDiscover = false; // 자동 초기화 방지

const myDropzone = new Dropzone('#myDropzone', {
  paramName: 'file',          // 서버에서 파일을 받을 파라미터 이름
  maxFilesize: 5,             // 최대 파일 크기 (MB)
  acceptedFiles: 'image/*',   // 허용 파일 타입
  dictDefaultMessage: '여기에 파일을 드래그하거나 클릭하세요',
  init: function () {
    this.on('success', function (file, response) {
      console.log('업로드 성공:', response);
    });
    this.on('error', function (file, errorMessage) {
      console.error('업로드 실패:', errorMessage);
    });
  }
});

핵심 옵션
- url : 파일을 전송할 URL (action 속성 대신 사용 가능)
- maxFiles : 한 번에 업로드 가능한 파일 수
- uploadMultiple : 다중 파일 업로드 여부
- autoProcessQueue : 파일을 자동으로 전송할지 여부 (수동 전송 시 processQueue() 호출)

4. 커스터마이징

4.1 파일 프리뷰 스타일 변경

Dropzone은 기본적으로 이미지 파일에 썸네일을 표시합니다. CSS를 이용해 스타일을 바꿀 수 있습니다.

/* 썸네일 크기 조정 */
.dropzone .dz-image img {
  width: 100px;
  height: 100px;
  object-fit: cover;
}

/* 파일 이름 폰트 */
.dropzone .dz-details .dz-filename {
  font-weight: bold;
}

4.2 서버와의 통신

서버에서 파일을 수신하고, JSON 형태로 응답을 반환해야 합니다. 예시 (Node.js + Express):

const express = require('express');
const multer  = require('multer');
const upload = multer({ dest: 'uploads/' });

const app = express();

app.post('/upload', upload.single('file'), (req, res) => {
  // 파일 정보는 req.file 에 저장됩니다.
  res.json({ success: true, filename: req.file.filename });
});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));

Tip: upload.single('file') 에서 'file' 은 Dropzone에서 지정한 paramName 과 일치해야 합니다.

4.3 파일 삭제 기능

Dropzone은 파일을 삭제할 때 DELETE 요청을 보낼 수 있도록 설정할 수 있습니다.

const myDropzone = new Dropzone('#myDropzone', {
  // ...
  dictRemoveFile: '삭제',
  init: function () {
    this.on('removedfile', function (file) {
      // 서버에 DELETE 요청
      fetch('/delete', {
        method: 'DELETE',
        body: JSON.stringify({ filename: file.upload.filename }),
        headers: { 'Content-Type': 'application/json' }
      });
    });
  }
});

5. 실전 팁

6. 마무리

Dropzone.js는 간단한 설정으로도 강력한 파일 업로드 UI를 제공해 주는 라이브러리입니다.
- 초기 설정: CDN 혹은 npm 설치 → autoDiscover = false → HTML 폼 + JS 인스턴스
- 커스터마이징: 옵션과 이벤트, CSS를 활용해 원하는 UI와 기능 구현
- 서버 연동: multer 같은 미들웨어와 함께 사용하면 손쉽게 파일을 저장하고 응답 처리

다음 단계로는 다중 파일 업로드와 프리뷰 커스터마이징을 더 깊이 파고들어 보세요. Dropzone.js를 활용하면 사용자 경험을 한층 끌어올릴 수 있습니다!

추가 자료
- 공식문서
- 예제 코드 저장소

Happy coding! 🚀