---
name: bijection-convex-fs
description: "Evaluate and integrate the File System component with Bijection."
---

# 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.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-fs. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses ConvexFS. Follow the installation and configuration steps exactly.

# ConvexFS

## Instructions

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.

### Installation

```bash
npm install convex-fs
```

Current npm version: `convex-fs@0.3.0`

## 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.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by ConvexFS is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-fs)
- [GitHub repository](https://github.com/jamwt/convex-fs)
- [Live demo](https://youtu.be/LK6EONQjhP0?si=xAGlEKE7rUGvQjIJ)
- [Convex Components Directory](https://www.convex.dev/components/convex-fs)
- [Convex documentation](https://docs.convex.dev)