Packages

@reupload/client

Browser client for uploading through your backend file router. The Reupload API key stays on the server — the browser only calls your API and PUTs to the signed CDN URL.

All packages · @reupload/sdk · reupload-sdk · @reupload/react · Client-side uploads (API)

Install

terminal

npm install @reupload/client

Environment

Point at your Node (or other) API — not the Reupload API URL.

.env.local

# Next.js
NEXT_PUBLIC_API_URL=http://localhost:3001
 
# Vite
VITE_API_URL=http://localhost:3001

Quick start

CDN flow: prepare → PUT uploadUrl → complete.

upload.ts

import { createReuploadClientFromEnv } from "@reupload/client";
 
const client = createReuploadClientFromEnv();
 
async function onFileSelected(file: File) {
  const { uploadId, fileId } = await client.uploadFile(file);
 
  const final = await client.pollUploadStatus(uploadId);
  if (final.status === "COMPLETED") {
    console.log("Ready:", fileId);
  }
}

Backend file router

Default routes (override with routes in the constructor). Implement these on your server with @reupload/sdk:

Method	Path	Purpose
`POST`	`/uploads/prepare`	Create session → `uploadUrl`, `uploadId`, `fileId`
`POST`	`/uploads/complete`	Finalize CDN upload (`{ uploadId }`)
`GET`	`/uploads/:uploadId/status`	Poll `{ status, fileId }`
`GET`	`/files/:fileId/access`	Signed download URL

Custom paths

client.ts

import { ReuploadClient } from "@reupload/client";
 
const client = new ReuploadClient({
  apiUrl: "https://api.myapp.com",
  routes: {
    prepare: "/api/v1/files/prepare",
    status: (id) => `/api/v1/files/uploads/${id}`,
  },
});

API

Method	Description
`uploadFile(file)`	Full CDN flow via your backend
`prepareUpload()` / `completeUpload()`	Individual CDN steps
`putFileToUploadUrl()`	CDN PUT with optional progress (XHR)
`pollUploadStatus()`	Poll until terminal status
`getFileAccess()`	Signed URL from your backend
`validateFile()`	Client-side size / MIME checks

React hook

Headless hook at @reupload/client/react. For UI components, prefer @reupload/react.

FileUpload.tsx

"use client";
 
import { useReuploadUpload } from "@reupload/client/react";
 
export function FileUpload() {
  const { upload, state, reset, isUploading } = useReuploadUpload({
    validation: { maxBytes: 52_428_800, accept: ["image/*"] },
  });
 
  return (
    <div>
      <input
        type="file"
        disabled={isUploading}
        onChange={(e) => {
          const file = e.target.files?.[0];
          if (file) void upload(file);
        }}
      />
      {state.status === "completed" ? <p>Done — {state.fileId}</p> : null}
      {state.status === "error" ? <p>{state.message}</p> : null}
      <button type="button" onClick={reset}>Reset</button>
    </div>
  );
}

Errors

errors.ts

import { isReuploadClientError } from "@reupload/client";
 
try {
  await client.uploadFile(file);
} catch (error) {
  if (isReuploadClientError(error)) {
    // error.phase === "backend" | "cdn"
    console.error(error.status, error.message);
  }
}

What this package does not do

Call the Reupload API directly (no ru_ key in the browser)
Server direct upload — use @reupload/sdk on your API; see Server-side upload

React/Next + Node.js — CDN flow (Express + React)
Server-side upload — direct proxy guide
Browser uploads — CDN CORS