@beignet/react-uploads

Runtime: Beignet requires Node.js 22.12 or newer. Bun is optional.

[!CAUTION] 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

Agent skills

This package ships a TanStack Intent skill for coding agents: @beignet/react-uploads#uploads-client. Load it when adding React upload UI, typed upload client setup, createReactUploads, useUpload, useUploadMany, progress, abort/reset behavior, upload versus uploadAsync semantics, React Query invalidation after uploads, or client/server boundary fixes.

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.

reset() returns the hook to idle state and aborts any active request. The invalidated upload cannot later overwrite the reset state. It does not delete objects or application records that were already persisted.

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