ファイルアップロードライブラリ徹底比較：設計思想と実装スタイルの違い

ファイルアップロードは一見単純に見えるが、実際にはドラッグ＆ドロップ、プログレス表示、サムネイル生成、キャンセル・再開、バリデーション、クラウド統合など、多くの要件が絡む複雑な機能だ。ここでは、代表的な6つの npm パッケージを、実際のコードと設計思想の観点から比較する。

⚠️ 非推奨ライブラリの確認

まず重要な前提として、fine-uploader と blueimp-file-upload は 新規プロジェクトでの使用を避けるべき ライブラリである。

• fine-uploader は npm ページ で「This package has been deprecated」の明確な表示があり、GitHub リポジトリも2021年以降更新されていない。
• blueimp-file-upload も同様に、npm ページ で「This project is no longer actively maintained」と記載されており、jQuery に依存する旧来のアーキテクチャを持つ。

以下では、これら2つを参考までに含めるが、主に dropzone、filepond、react-dropzone、uppy の4つに焦点を当てる。

🖼️ サムネイル生成とプレビュー：画像処理の深さ

dropzone

dropzone は基本的なサムネイル生成をサポートするが、回転補正や EXIF 処理は含まれない。開発者が自前で Canvas API を使って処理を追加する必要がある。

// dropzone: 基本的なサムネイル
new Dropzone('#my-dropzone', {
  thumbnail: function(file, dataUrl) {
    // dataUrl を img 要素に設定
    file.previewElement.querySelector('.dz-image').style.backgroundImage = `url(${dataUrl})`;
  }
});

filepond

filepond は画像の EXIF 回転補正、自動向き修正、プレビュー時の圧縮を内蔵しており、開発者の手間を大幅に削減する。

// filepond: 自動で正しい向きのサムネイル
FilePond.create(document.querySelector('input[type="file"]'), {
  imagePreviewHeight: 170,
  imageCropAspectRatio: '1:1',
  imageResizeTargetWidth: 200,
  imageResizeTargetHeight: 200
});

react-dropzone

react-dropzone はサムネイル生成を一切提供しない。開発者が URL.createObjectURL() や FileReader を使って自前で実装する必要がある。

// react-dropzone: サムネイルは自分で作る
import { useDropzone } from 'react-dropzone';

function MyDropzone() {
  const [preview, setPreview] = useState(null);
  const { getRootProps, getInputProps, acceptedFiles } = useDropzone({
    onDrop: (files) => setPreview(URL.createObjectURL(files[0]))
  });

  return (
    <div {...getRootProps()}>
      <input {...getInputProps()} />
      {preview && <img src={preview} alt="preview" style={{ width: 100 }} />}
    </div>
  );
}

uppy

uppy は @uppy/thumbnail-generator プラグインを通じてサムネイルを生成し、EXIF 情報に基づく回転補正も可能だ。

// uppy: プラグインでサムネイル
import Uppy from '@uppy/core';
import ThumbnailGenerator from '@uppy/thumbnail-generator';

const uppy = new Uppy();
uppy.use(ThumbnailGenerator, {
  thumbnailWidth: 200,
  thumbnailHeight: 200
});

🧩 UI の制御度：「与えられるもの」vs「自分で作るもの」

dropzone と filepond

これらは「完成された UI コンポーネント」を提供する。HTML 要素に適用すると、自動でドラッグ領域、プログレスバー、キャンセルボタンなどが描画される。

// dropzone: 完成された UI
Dropzone.options.myDropzone = {
  url: '/upload',
  maxFilesize: 2,
  addRemoveLinks: true
};

// HTML: <form id="my-dropzone" class="dropzone"></form>

// filepond: 同様に完成された UI
FilePond.parse(document.body); // すべての input[type=file] を変換

react-dropzone

逆に、react-dropzone は UI は何も提供しない。あくまで「ファイルがドロップされたかどうか」を通知するフックであり、見た目は完全に開発者の責任だ。

// react-dropzone: UI は全部自分で書く
const { getRootProps, getInputProps, isDragActive } = useDropzone();

return (
  <div
    {...getRootProps()}
    style={{
      border: '2px dashed #ccc',
      padding: 20,
      backgroundColor: isDragActive ? '#f0f0f0' : 'white'
    }}
  >
    <input {...getInputProps()} />
    {isDragActive ? <p>ここにドロップ！</p> : <p>ファイルをドラッグ or クリック</p>}
  </div>
);

uppy

uppy は中間的で、@uppy/dashboard のような UI プラグインをオプションで使うことができる。つまり、「必要な UI だけを追加」できる柔軟性がある。

// uppy: 必要に応じて UI を追加
import Dashboard from '@uppy/dashboard';

uppy.use(Dashboard, {
  inline: true,
  target: '#uppy-container'
});

🔌 拡張性とプラグインモデル

uppy のモジュール設計

uppy はコアとプラグインで構成されており、必要な機能だけを追加できる。

// uppy: プラグインで機能追加
import Uppy from '@uppy/core';
import GoogleDrive from '@uppy/google-drive';
import Webcam from '@uppy/webcam';
import XHRUpload from '@uppy/xhr-upload';

const uppy = new Uppy();
uppy
  .use(GoogleDrive, { companionUrl: 'https://companion.example.com' })
  .use(Webcam)
  .use(XHRUpload, { endpoint: '/upload' });

filepond のプラグイン

filepond も同様に、画像編集、圧縮、ファイルサイズ制限などを別パッケージで提供する。

// filepond: プラグイン追加
import FilePondPluginImageExifOrientation from 'filepond-plugin-image-exif-orientation';
import FilePondPluginImagePreview from 'filepond-plugin-image-preview';

FilePond.registerPlugin(
  FilePondPluginImageExifOrientation,
  FilePondPluginImagePreview
);

dropzone と react-dropzone

これらは拡張モデルを持たず、すべてのカスタムロジックをコールバック関数で実装する必要がある。

// dropzone: カスタムロジックはすべてイベントで
Dropzone.options.myDropzone = {
  init: function() {
    this.on('success', function(file, response) {
      // アップロード成功後の処理
    });
  }
};

📦 フレームワーク統合

React 環境での選択

• react-dropzone: React のライフサイクルと完全に統合され、hooks として自然に使える。ただし UI は自前実装。
• uppy: @uppy/react で React コンポーネントとして使える。<Dashboard /> や <DragDrop /> といったコンポーネントが提供される。
• filepond: react-filepond という公式ラッパーがあり、React の props として扱える。
• dropzone: jQuery に依存しないため React でも使えるが、refs や useEffect で DOM 操作が必要で、やや不自然。

// uppy + React
import { Dashboard } from '@uppy/react';

function App() {
  return <Dashboard uppy={uppy} />;
}

// filepond + React
import { FilePond } from 'react-filepond';

function App() {
  return <FilePond onupdatefiles={setFiles} />;
}

📤 アップロード処理のカスタマイズ

全ライブラリで、アップロード先やリクエスト形式をカスタマイズできるが、その方法は異なる。

dropzone

new Dropzone('#dz', {
  url: '/custom-upload',
  headers: { 'X-CSRF-Token': '...' },
  paramName: 'myFile'
});

filepond

FilePond.create(input, {
  server: {
    process: '/upload',
    headers: { 'X-CSRF-Token': '...' }
  }
});

uppy

uppy.use(XHRUpload, {
  endpoint: '/upload',
  headers: { 'X-CSRF-Token': '...' },
  fieldName: 'myFile'
});

react-dropzone

react-dropzone はアップロード処理を一切提供しないため、fetch や axios を使って自分で実装する。

const onDrop = useCallback((acceptedFiles) => {
  const formData = new FormData();
  formData.append('file', acceptedFiles[0]);
  fetch('/upload', { method: 'POST', body: formData });
}, []);

📊 まとめ：どのライブラリを選ぶべきか

💡 最終的なアドバイス

• 新規プロジェクトでは、uppy か filepond を第一候補に。どちらもアクティブにメンテナンスされ、豊富な機能と美しい UX を提供する。
• React でデザインシステムに厳密に従う必要があるなら react-dropzone。ただし、UI 実装コストは高くなる。
• 軽量さとシンプルさが最優先なら dropzone。ただし、高度な機能は自前実装になる。
• blueimp-file-upload と fine-uploader は絶対に新規で使わないこと。セキュリティリスクや将来のメンテナンス負荷が高すぎる。