@beignet/react-uploads

@beignet/react-uploads

Beignet is experimental alpha software. The 0.0.x package line is for early evaluation, and APIs may change between releases while the framework settles.

React upload hooks for Beignet upload clients.

Install

bun add @beignet/react-uploads @beignet/core react

Usage

Create a typed upload client with @beignet/core/uploads/client, then wrap it once for React components:

// client/uploads.ts
import { createUploadClient } from "@beignet/core/uploads/client";
import { createReactUploads } from "@beignet/react-uploads";
import type { postUploads } from "@/features/posts/uploads";

export type AppUploads = typeof postUploads;

export const uploads = createUploadClient<AppUploads>({
  baseUrl: "/api/uploads",
});

export const reactUploads = createReactUploads({
  uploads,
});

Use the hook in components:

"use client";

import { reactUploads } from "@/client/uploads";

export function AttachmentPicker({ postSlug }: { postSlug: string }) {
  const attachment = reactUploads.useUpload("posts.attachment");

  return (
    <input
      type="file"
      accept={attachment.accept}
      disabled={attachment.isUploading}
      onChange={(event) => {
        const files = Array.from(event.currentTarget.files ?? []);
        if (files.length === 0) return;

        attachment.upload({
          metadata: { postSlug },
          files,
        });
      }}
    />
  );
}

The hook exposes status, progress, error, result, reset, and abort. upload(...) is fire-and-forget: it never rejects, so the onChange handler above is safe without await or .catch(...). Failures land in hook state and the onError callback.

Use uploadAsync(...) when the caller needs to sequence work after the upload and handle the failure itself. It returns the completion result and rejects when the upload fails:

try {
  const result = await attachment.uploadAsync({
    metadata: { postSlug },
    files,
  });
  console.log(result.result);
} catch {
  // Failure is also stored in hook state and passed to onError.
}

The adapter keeps uploads imperative and does not hide React Query; invalidate queries in onSuccess when an upload changes visible app state.

const attachment = reactUploads.useUpload("posts.attachment", {
  onSuccess() {
    rq(getPost).invalidate(queryClient);
  },
});

Lifecycle callbacks run after the upload settles and never change upload state. When a callback throws, uploadAsync(...) rejects with the callback error and upload(...) reports it through console.error; a succeeded upload stays status: "success" either way.

Progress reporting

Progress depends on the upload transport selected by the core upload client:

• Direct uploads report real per-file progress from the browser's XMLHttpRequest upload events.
• Server-strategy uploads stream the whole multipart request through the app server and only report request completion, so progress jumps from 0 to 100 in one step when the request finishes.

Treat progress bars as an enhancement for direct uploads and prefer indeterminate pending UI when forcing strategy: "server".

API

• createReactUploads({ uploads }) creates an adapter bound to a typed upload client.
• adapter.useUpload(name, options?) returns state and methods for one upload workflow:
  • upload(options) starts an upload and never rejects.
  • uploadAsync(options) starts an upload and rejects on failure.
  • uploadFile(file, options) / uploadFileAsync(file, options) are single-file conveniences with the same semantics.
• adapter.useUploadMany(name, options?) returns the same state with file-first upload(files, options) and uploadAsync(files, options) convenience methods.

Related

• @beignet/core/uploads - upload definitions and runtime router
• @beignet/core/uploads/client - typed browser upload client