# Dropzone.js 완전 정복 가이드

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

---

## 1. Dropzone.js란? {#sec-2c56f42a85c2}

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

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


![Dropzone 페이지 스크린캡쳐 이미지](/media/editor_temp/6/1ed0b960-262c-4262-9b63-b4348d79574c.png)

---

## 2. 설치 방법 {#sec-39941200d972}

### 2.1 CDN 사용 {#sec-12316045aa37}

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

```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](https://unpkg.com/dropzone/)에서 확인하세요.

### 2.2 NPM / Yarn {#sec-ba57e40bccaf}

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

```bash
npm install dropzone
# 또는
yarn add dropzone
```

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

```js
import Dropzone from 'dropzone';
```

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

---

## 3. 기본 사용법 {#sec-acad8b13fc1d}

### 3.1 HTML {#sec-74bff21a0971}

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

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

### 3.2 JavaScript {#sec-b80012d66ac1}

```js
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. 커스터마이징 {#sec-eb528354528b}

### 4.1 파일 프리뷰 스타일 변경 {#sec-683ced43ced2}

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

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

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

### 4.2 서버와의 통신 {#sec-655f5280b95f}

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

```js
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 파일 삭제 기능 {#sec-efd642c1f4e0}

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

```js
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. 실전 팁 {#sec-c3d1df9ee031}

| 상황 | 해결책 |
|------|--------|
| **다중 파일 업로드 시 파일 수 제한** | `maxFiles: 10` 옵션 사용 |
| **업로드 진행률 표시** | `progress` 이벤트 활용 |
| **파일 업로드 중 취소** | `cancelUpload()` 메서드 사용 |
| **파일 업로드 실패 시 재시도** | `retry` 옵션 또는 `error` 이벤트에서 재시도 로직 구현 |
| **보안** | CSRF 토큰을 `headers` 옵션에 포함시키기 |

---


## 6. 마무리 {#sec-591ca4aef1b9}

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

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

> **추가 자료**  
> - [공식문서](https://www.dropzonejs.com/)  
> - [예제 코드 저장소](https://github.com/dropzone/dropzone/)

Happy coding! 🚀