# File System

Durable file management on Bunny.net

- Package: @bijectionhq/fs
- Category: Storage
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/convex-fs/tree/fa7b3cf05c5e36903c690a267e6b5125a1210fad
- Upstream: https://github.com/jamwt/convex-fs/tree/2729ea8bcca6e878106409991f307607bb960389
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/convex-fs

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/convex-fs.git
cd convex-fs
git checkout fa7b3cf05c5e36903c690a267e6b5125a1210fad
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Upstream package documentation

Recorded 2026-10-23. This describes convex-fs; check the Bijection adaptation separately.

ConvexFS provides filesystem-like operations for file management in Convex applications, backed by Bunny.net Edge Storage and CDN. Instead of working with raw blob storage, developers organize files using familiar paths and directories while getting global CDN performance. The component includes atomic file operations, reference-counted blob deduplication, signed CDN URLs, and configurable soft deletes for disaster recovery.

### Use cases

- **Building file galleries or media libraries** where you need to organize user uploads into logical folder structures with paths like `/users/123/photos/vacation.jpg`
- **Implementing secure file sharing** with time-limited download links that expire automatically and are served from a global CDN
- **Creating temporary upload workflows** where files need automatic expiration for session-scoped content or time-limited sharing scenarios
- **Managing large file collections** that benefit from automatic deduplication and reference counting to optimize storage costs
- **Building applications requiring atomic file operations** like moving or copying files with preconditions to prevent race conditions in multi-user environments

### How it works

ConvexFS acts as a Convex component that abstracts Bunny.net Edge Storage behind a filesystem interface. You install it as an npm package and configure it within your Convex backend to handle path-based file operations instead of direct blob management.

The component implements reference-counted blob storage with automatic deduplication, meaning multiple files can share the same underlying blob data while maintaining separate filesystem paths. File operations like move, copy, and delete support atomic transactions with preconditions to prevent data races in concurrent scenarios.

Authentication and access control integrate with your existing Convex functions, letting you implement custom auth logic for uploads and downloads. The component generates signed CDN URLs served through Bunny.net's global edge network, with support for custom parameters that can trigger edge-side transformations like image optimization or custom download filenames. Soft deletes with configurable grace periods provide disaster recovery capabilities for accidental file removal.

### Upstream README

# ConvexFS

<p align="center">
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/convex-fs"><img src="https://img.shields.io/npm/v/convex-fs.svg" alt="npm version" /></a>
  <a href="https://www.npmjs.com/package/convex-fs"><img src="https://img.shields.io/npm/dw/convex-fs.svg" alt="npm downloads" /></a>
  <a href="https://github.com/jamwt/convex-fs/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/convex-fs.svg" alt="license" /></a>
  <a href="https://github.com/jamwt/convex-fs/actions/workflows/test.yml"><img src="https://github.com/jamwt/convex-fs/actions/workflows/test.yml/badge.svg" alt="build status" /></a>
  <a href="https://convexfs.dev"><img src="https://img.shields.io/badge/docs-convexfs.dev-blue.svg" alt="docs" /></a>
</p>

<p align="center">
  <strong>Virtual filesystem for Convex, backed by Bunny.net Edge Storage & CDN</strong>
</p>

---

ConvexFS is a [Convex component](https://convex.dev/components) 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](./example).

## Status

**Alpha** — This project is in active development. APIs may change before 1.0.

## Documentation

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

**[convexfs.dev](https://convexfs.dev)**

## License

Apache-2.0