File Uploads

Files stored in your database, with atomic writes, batch publication, and search.

Install

npm install @fragno-dev/upload

npm install @fragno-dev/upload

Requires a Fragno database adapter, which stores files and their content.

Publishing files

Publish each upload on its own, or several together.

Immediate

Storing an upload's content publishes the file in the same transaction.

Batch

Prepare several uploads, then publish them all in one commit.

File + upload model

Track upload lifecycle and file metadata with durable records.

Atomic writes

A file's content and metadata commit in the same database transaction.

Search and edits

Text search, server-side edits, and signed file links over stored files.

Setup blueprint

Mount the 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

Set the largest file and mount the routes.

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

const fragment = createUploadFragment(
  { maxFileBytes: 10 * 1024 * 1024 },
  {
    databaseAdapter,
    mountRoute: "/api/uploads",
  },
);

await migrate(fragment);

import { createUploadFragment } from "@fragno-dev/upload";import { migrate } from "@fragno-dev/db";const fragment = createUploadFragment(  { maxFileBytes: 10 * 1024 * 1024 },  {    databaseAdapter,    mountRoute: "/api/uploads",  },);await migrate(fragment);

3. Create a client

Generate typed hooks and upload helpers.

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 creates the upload, streams its content, and reports progress.

const { useUploadHelpers } = uploadClient;

const helpers = useUploadHelpers();
await helpers.createUploadAndTransfer(file, {
  fileKey: `users/${userId}/avatar.png`,
  onProgress: (progress) => {
    console.log(progress.bytesUploaded, progress.totalBytes);
  },
});

const { useUploadHelpers } = uploadClient;const helpers = useUploadHelpers();await helpers.createUploadAndTransfer(file, {  fileKey: `users/${userId}/avatar.png`,  onProgress: (progress) => {    console.log(progress.bytesUploaded, progress.totalBytes);  },});

Large files

Files live in database rows, so keep them within your database's limits. Keep recordings, videos, and other large files in S3-compatible object storage with the @fragno-dev/blobs fragment instead.

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.

Agent workspaces

Let agents search, edit, and atomically rewrite sets of files.

Multi-tenant files

Keep each tenant's files under its own key prefix.