ConvexFS

Virtual filesystem for Convex, backed by Bunny.net Edge Storage & CDN

---

ConvexFS is a Convex component that provides filesystem-like operations for managing files in your Convex application. Instead of dealing with raw blob storage, you work with familiar concepts like paths, files, and directories—while getting the performance benefits of a global CDN.

Features

• Path-based file management — Organize files with familiar filesystem paths
• Atomic transactions — Move, copy, and delete files with preconditions to prevent data races
• Reference-counted blobs — Efficient storage with automatic deduplication
• Signed CDN URLs — Secure, time-limited download links served from Bunny.net's global edge network
• Soft deletes & disaster recovery — Configurable grace periods let you recover from accidental deletions
• Flexible authentication — Bring your own auth logic for uploads and downloads
• File expiration — Set automatic expiration times on files for temporary uploads, time-limited sharing, or session-scoped content
• Custom CDN parameters — Pass parameters to Bunny.net edge rules for on-the-fly transformations like custom download filenames and image optimization

Example app

The repository includes a runnable example app that allows you to curate a photo gallery.

Status

Beta — Running in production applications. The API is stable; any breaking change will be called out in the changelog and gated behind a minor version bump until 1.0.

Documentation

For installation instructions, guides, and API reference, visit:

convexfs.dev

Installing This Fork

Install the package directly from GitHub:

bun add github:celados/convex-fs#v0.3.1

Use version tags for downstream projects. main is the source branch and does not track generated dist/ artifacts; release tags are consumable snapshots that include dist/ for stable runtime and TypeScript resolution.

Bunny Edge Upload Signer Provisioning

uploadMode: "bunny-edge-presigned" uses a standalone Bunny Edge Script signer. Provision it from setup scripts, CI, or admin tooling:

import { provisionBunnyEdgeUploadSigner } from "convex-fs/bunny-edge-tools";

const result = await provisionBunnyEdgeUploadSigner({
  bunnyAccountApiKey: process.env.BUNNY_ACCOUNT_API_KEY!,
  storageZoneName: process.env.BUNNY_STORAGE_ZONE!,
  storageAccessKey: process.env.BUNNY_STORAGE_API_KEY!,
  region: process.env.BUNNY_REGION,
  signerHostname: "uploads.example.com",
  signerAccessKey: process.env.BUNNY_EDGE_UPLOAD_ACCESS_KEY,
});

if (!result.ok) {
  throw new Error(result.error.message);
}

console.log(result.env);

This helper is not a Convex runtime API. Keep BUNNY_ACCOUNT_API_KEY and BUNNY_STORAGE_API_KEY in provisioning environments only; Convex runtime config only needs edgeUpload.signUrl and edgeUpload.accessKey.

If you're upgrading an existing integration, read the migration guide:

Migration: Streaming-Only Fork

License

Apache-2.0