@gentleduck/upload

Resumable, strategy-based file upload engine. PUT / POST / multipart / tus strategies, abort & resume, XHR + fetch transports, React bindings.

MIT - Changelog - Contributing - Docs

---

Install

bun add @gentleduck/upload

Quick start

import { createUploadStore } from '@gentleduck/upload/core'
import { PutStrategy, createStrategyRegistry } from '@gentleduck/upload/strategies'

const strategies = createStrategyRegistry()
strategies.set(PutStrategy({ allowedHosts: ['uploads.example.com'] }))

const store = createUploadStore({
  strategies,
  api: {
    async createIntent({ filename, contentType, size }) {
      const res = await fetch('/api/sign', {
        method: 'POST',
        body: JSON.stringify({ filename, contentType, size }),
      })
      return res.json() // -> { strategy: 'put', fileId, url, headers? }
    },
    async complete({ fileId }) {
      return { fileId, key: `uploads/${fileId}` }
    },
  },
  config: { maxConcurrentUploads: 3, autoStart: ['avatar'] },
})

store.dispatch({ type: 'addFiles', files, purpose: 'avatar' })

React

import { useDropzone, useUploader } from '@gentleduck/upload/react'

function Avatar() {
  const { getRootProps, getInputProps } = useDropzone({ purpose: 'avatar', accept: 'image/*' })
  const { uploading } = useUploader()
  return (
    <div {...getRootProps()}>
      <input {...getInputProps()} />
      {uploading.length > 0 && <span>uploading…</span>}
    </div>
  )
}

See the package README for the full API.

Workspace

Path	Package	Role
packages/duck-upload	@gentleduck/upload	Core engine, strategies, React bindings

Subpath exports

Subpath	Target
@gentleduck/upload	Top-level public API (core + react + strategies)
@gentleduck/upload/core	Engine, contracts, persistence, errors, XHR + fetch transports
@gentleduck/upload/react	React provider + hooks (useUploader, useDropzone)
@gentleduck/upload/strategies	PutStrategy, PostStrategy, multipartStrategy, TusStrategy, registry

Build

bun install
bunx turbo run build --filter='./packages/*'
bunx turbo run test --filter='./packages/*'
bunx turbo run check-types --filter='./packages/*'

Docs

• Site: gentleduck.org/duck-upload
• Sibling repos: @gentleduck/ui, @gentleduck/iam, @gentleduck/md

Contributing

PR checklist + style notes in CONTRIBUTING.md. Security: SECURITY.md. Behaviour: CODE_OF_CONDUCT.md.

License

MIT. See LICENSE.