vane-upload

React upload components with chunked upload, resumable queue, IndexedDB cache, and Worker-based preprocessing.

Install

npm i vane-upload

Required peer dependencies:

• react
• react-dom
• antd

Exports

• vane-upload: ZustandFileUpload, SimpleUploadList
• vane-upload/hooks: upload store + core hooks
• vane-upload/types: component props and domain types

Quick Start

import { ZustandFileUpload } from "vane-upload";

export default function App() {
  return (
    <ZustandFileUpload
      baseURL="http://localhost:3000"
      uploadApi="/api/file/upload"
      checkApi="/api/file/check"
      autoUpload
      autoCleanup
      cleanupDelay={5}
    />
  );
}

Simple Mode Example

import { SimpleUploadList } from "vane-upload";

export default function App() {
  return (
    <SimpleUploadList
      baseURL="http://localhost:3000"
      uploadApi="/api/file/upload"
      checkApi="/api/file/check"
      listApi="/api/file/list"
      onServerListChange={(files) => {
        console.log("latest server files:", files);
      }}
    />
  );
}

SimpleUploadList behavior:

• Page shows a read-only server file list.
• Click Upload to open modal.
• Modal uses upload component in uiMode="simple" + settingsSource="props".
• Each successful file upload triggers list refresh.
• Batch end closes modal automatically.

ZustandFileUpload Props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | baseURL | string | "" | API base URL. | | uploadApi | string | "/api/file/upload" | Upload endpoint. | | checkApi | string | "/api/file/check" | Instant upload check endpoint. | | chunkSize | number | 1048576 | Upload chunk size in bytes. | | fileConcurrency | number | 2 | Parallel file upload count. | | chunkConcurrency | number | 2 | Parallel chunk upload count per file. | | maxRetries | number | 3 | Retry count per failed chunk. | | maxFileSize | number | 104857600 | Max single file size in bytes. | | allowedFileTypes | string[] | [] | Allowed MIME types/extensions; empty means no restriction. | | maxFiles | number | 100 | Max selected file count per batch. | | autoUpload | boolean | true | Auto start upload after file selection. | | autoCleanup | boolean | true | Auto remove finished upload items. | | cleanupDelay | number | 10 | Cleanup delay in seconds. | | networkDisplayMode | "tooltip" \| "direct" | "tooltip" | Network hint display mode. | | uiMode | "full" \| "simple" | "full" | Full controls or simplified view. | | settingsSource | "localStorage" \| "props" | "localStorage" | Settings source; props ignores local history. | | customFileValidator | (file: File) => { valid: boolean; message?: string } | undefined | Custom validator before enqueue. | | customUploadHandler | (file, config) => Promise<boolean> | undefined | Reserved custom upload path. |

Callbacks

| Callback | Signature | Trigger | | --- | --- | --- | | onUploadStart | (files) => void | Batch starts. | | onUploadProgress | (file, progress) => void | File progress changes. | | onUploadComplete | (file, success) => void | Single file ends (success or fail). | | onUploadError | (file, error) => void | Single file enters error state. | | onBatchComplete | ({ success, failed, total }) => void | Batch queue fully drained. |

SimpleUploadList Props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | baseURL | string | "" | API base URL. | | uploadApi | string | "/api/file/upload" | Upload endpoint. | | checkApi | string | "/api/file/check" | Instant upload check endpoint. | | listApi | string | "/api/file/list" | Server file list endpoint. | | onServerListChange | (files) => void | undefined | Called after each successful list refresh. |

Browser + Runtime Notes

• Requires browser support for IndexedDB, Web Worker, and Blob.
• For cross-origin APIs, configure CORS and ensure upload/check/list endpoints are reachable from browser.
• Worker assets are bundled in package output and loaded by URL during runtime.

v1 Boundaries

• Ant Design 5 UI is built-in (not headless).
• Main focus is component-level integration with stable default behavior.
• customUploadHandler is exposed but considered an advanced extension path.

Release

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