@filepack/client

Headless browser uploader for Filepack. It uses fetch for authenticated control requests and XMLHttpRequest for file bytes and upload progress.

Quickstart

Export only the router type from server code:

export type AppFilepackRouter = typeof routes;

Create the browser client:

import { createFilepackClient } from "@filepack/client";
import type { AppFilepackRouter } from "./filepack-server.js";

const filepack = createFilepackClient<AppFilepackRouter>({
  basePath: "/api/filepack",
  controlHeaders: () => ({
    authorization: `Bearer ${getAccessToken()}`,
  }),
});

const task = filepack.upload({
  route: "messageAttachment",
  input: { conversationId: "conversation-1" },
  files: [selectedFile],
  onProgress(event) {
    console.log(event.transferredBytes, event.confirmedBytes, event.phase);
  },
});

task.pause();
task.resume();

const results = await task.result;

Use { blob, name } for a Blob that has no file name. Results preserve input order. One failed file does not hide successful files.

Multipart recovery

Multipart progress is durable at recorded part boundaries. After a reload, the application must ask the user for the original file again:

const task = filepack.resumeUpload({
  attemptId,
  file: originalFile,
});

const [result] = await task.result;

Filepack compares the supplied size and MIME type with server state. It then uploads only missing parts. Filepack does not persist browser bytes or prove full content identity.

maxConcurrentFiles bounds files in one task. maxConcurrentParts bounds all multipart XHR transfers in that task, including transfers from different files.

Cancellation

task.cancel() stops active XHR and ordinary control requests, stops retry delays, and asks the server to abort every known incomplete attempt. Pause stops only active XHR transfers. An aborted result means server abort was confirmed. If confirmation fails, the result is a retryable UPLOAD_ABORT_UNCONFIRMED failure and includes the attempt ID.

Provider CORS

Direct S3-compatible targets must allow the signed PUT headers. Multipart buckets must expose the ETag response header to browser JavaScript. Control headers are sent only to the Filepack handler and are never copied to storage targets. basePath must be a same-origin path that starts with one /.

The package has no React, UI, framework binding, Node runtime API, tus client, browser byte persistence, service worker, or cross-device recovery behavior.