First party fragmentStripe Forms WorkflowsUploadsAuth

File Uploads

Direct and proxy uploads with storage adapters, metadata, and progress tracking.

Install

npm install @fragno-dev/upload

npm install @fragno-dev/upload

Requires a Fragno database adapter to store upload and file records.

Upload modes

Pick direct or server-streamed based on security needs.

Direct

Signed URLs to S3/R2 for large files and efficient transfers.

Proxy

Server-streamed uploads for private storage or small files.

File + upload model

Track upload lifecycle and file metadata with durable records.

Multiple upload strategies

Direct single/multipart or server-streamed proxy uploads.

Storage adapters

S3/R2-compatible storage and Node filesystem adapters.

Setup blueprint

Configure storage, mount routes, and ship upload flows.

1. Install

Install the upload fragment.

npm install @fragno-dev/upload

npm install @fragno-dev/upload

2. Create the fragment server

Choose a storage adapter and mount the routes.

import { createUploadFragment, createFilesystemStorageAdapter } from "@fragno-dev/upload";
import { migrate } from "@fragno-dev/db";

const storage = createFilesystemStorageAdapter({ rootDir: "./uploads" });

const fragment = createUploadFragment(
  { storage },
  {
    databaseAdapter,
    mountRoute: "/api/uploads",
  },
);

await migrate(fragment);

import { createUploadFragment, createFilesystemStorageAdapter } from "@fragno-dev/upload";import { migrate } from "@fragno-dev/db";const storage = createFilesystemStorageAdapter({ rootDir: "./uploads" });const fragment = createUploadFragment(  { storage },  {    databaseAdapter,    mountRoute: "/api/uploads",  },);await migrate(fragment);

3. Create a client

Generate typed helpers for direct and proxy uploads.

import { createUploadFragmentClient } from "@fragno-dev/upload/react";

export const uploadClient = createUploadFragmentClient({
  mountRoute: "/api/uploads",
});

import { createUploadFragmentClient } from "@fragno-dev/upload/react";export const uploadClient = createUploadFragmentClient({  mountRoute: "/api/uploads",});

Use it

The client helper picks direct or server-streamed uploads automatically.

const { useUploadHelpers } = uploadClient;

const helpers = useUploadHelpers();
await helpers.createUploadAndTransfer(file, {
  keyParts: ["users", userId, "avatar"],
  onProgress: (progress) => {
    console.log(progress.bytesUploaded, progress.totalBytes);
  },
});

const { useUploadHelpers } = uploadClient;const helpers = useUploadHelpers();await helpers.createUploadAndTransfer(file, {  keyParts: ["users", userId, "avatar"],  onProgress: (progress) => {    console.log(progress.bytesUploaded, progress.totalBytes);  },});

Storage adapters

Switch adapters without changing fragment APIs.

Works with AWS S3 and compatible providers like R2.

import { createS3CompatibleStorageAdapter } from "@fragno-dev/upload";

const storage = createS3CompatibleStorageAdapter({
  bucket: process.env.UPLOAD_S3_BUCKET!,
  endpoint: process.env.UPLOAD_S3_ENDPOINT!,
  signer,
});

import { createS3CompatibleStorageAdapter } from "@fragno-dev/upload";const storage = createS3CompatibleStorageAdapter({  bucket: process.env.UPLOAD_S3_BUCKET!,  endpoint: process.env.UPLOAD_S3_ENDPOINT!,  signer,});

Adapter docs

Upload CLI

Manage upload sessions and files with `fragno-upload`.

fragno-upload uploads create -b https://host/api/uploads \
  --file-key s~Zm9v --filename demo.txt --size-bytes 10 --content-type text/plain

fragno-upload uploads transfer -b https://host/api/uploads -f ./demo.txt --file-key s~Zm9v

fragno-upload files list -b https://host/api/uploads --prefix s~Zm9v

fragno-upload files download -b https://host/api/uploads --file-key s~Zm9v -o ./download.txt

fragno-upload uploads create -b https://host/api/uploads \  --file-key s~Zm9v --filename demo.txt --size-bytes 10 --content-type text/plainfragno-upload uploads transfer -b https://host/api/uploads -f ./demo.txt --file-key s~Zm9vfragno-upload files list -b https://host/api/uploads --prefix s~Zm9vfragno-upload files download -b https://host/api/uploads --file-key s~Zm9v -o ./download.txt

Use cases

Profile avatars

Upload user images with a predictable file key and progress tracking.

Large assets

Use multipart uploads for big files with resumable transfers.

Multi-tenant storage

Store files in R2 or S3 with keys that map to orgs or projects.