vane-file-download

React download component with chunked transfer, resume support, IndexedDB persistence, and Worker-based merge.

Install

npm i vane-file-download

Required peer dependencies:

• react
• react-dom
• antd

Exports

• vane-file-download: ZustandFileDownload
• vane-file-download/hooks: download store + core hooks
• vane-file-download/types: component props and domain types

Quick Start

import { ZustandFileDownload } from "vane-file-download";

export default function App() {
  return (
    <ZustandFileDownload
      baseURL="http://localhost:3000"
      listApi="/api/file/list"
      downloadApi="/api/file/download"
    />
  );
}

ZustandFileDownload Props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | baseURL | string | "" | API base URL. | | listApi | string | "/api/file/list" | Server file list endpoint. | | downloadApi | string | "/api/file/download" | File download endpoint. | | chunkSize | number | 5242880 | Download chunk size in bytes. | | maxConcurrency | number | 3 | Parallel chunk download count. | | maxRetries | number | 3 | Retry count per failed chunk. | | retryDelay | number | 1000 | Retry delay in milliseconds. | | autoStart | boolean | false | Auto start when queue is prepared. | | showProgress | boolean | true | Show progress section. | | showStorageStats | boolean | true | Show IndexedDB storage stats. | | showNetworkStatus | boolean | true | Show network status badge. | | customDownloadHandler | (file, config) => Promise<boolean> | undefined | Custom download path. | | customProgressHandler | (file, progress) => void | undefined | Custom progress hook. |

Callbacks

| Callback | Signature | Trigger | | --- | --- | --- | | onDownloadStart | (file) => void | Single file starts downloading. | | onDownloadProgress | (file, progress) => void | Progress updates while downloading. | | onDownloadComplete | (file, success) => void | Single file finishes. | | onDownloadError | (file, error) => void | Single file enters error state. | | onBatchComplete | ({ success, failed, total }) => void | Queue is drained. | | onStorageChange | (stats) => void | Storage usage changes. |

Hooks API (vane-file-download/hooks)

• useDownloadStore
• useDownloadFiles
• useFileDownloader
• useEffectiveDownloadConfig
• useNetworkDetection
• useStorageManager

Browser + Runtime Notes

• Requires browser support for IndexedDB, Web Worker, Blob, and URL.createObjectURL.
• For cross-origin APIs, configure CORS and ensure Range/partial download behavior is supported on server side.
• Worker assets are bundled in package output and loaded by URL during runtime.

v1 Boundaries

• Ant Design 5 UI is built-in (not headless).
• Some callbacks are exposed in types for forward compatibility, but runtime wiring is still evolving.

Release

npm run lint
npm run test
npm run build
npm pack
npm publish --tag next
# after validation
npm publish --tag latest