File System
Durable file management on Bunny.net
git clone https://github.com/bijectionhq/convex-fs.git
cd convex-fs
git checkout fa7b3cf05c5e36903c690a267e6b5125a1210fadBijection repository access is required. Request access.
Description
Durable file management on Bunny.net
Explore the package README for API concepts, configuration, and examples. Check the Bijection source for adaptation-specific setup.
Review the source and its dependencies before adopting this package. Source availability does not establish npm publication or runtime qualification.
Getting started
- Get the source at the revision above and read its package documentation.
- Check the required Bijection SDK version, dependencies, and external service credentials.
- Follow the package setup instructions and the guide to using components.
- Exercise the component in your deployment according to your project’s verification rules.
Open source
Maintained source: bijectionhq/convex-fs. Based on jamwt/convex-fs. License: Apache-2.0. Consult the repository for license terms, notices, and contributor attribution.
From the upstream publisher
A fs component for Convex.
Explore the demo ↗Demo video
Upstream overview
From the upstream package documentation.
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
From the upstream package documentation.
- 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
From the upstream package documentation.
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 package FAQ
How does ConvexFS integrate with Convex mutations and queries?
ConvexFS provides APIs that work directly within Convex mutations and queries, allowing you to store files as part of your database transactions. You can upload files in mutations and reference them in queries using the same patterns as other Convex operations.
Does ConvexFS require external service configuration?
Yes. ConvexFS uses bunny.net for blob storage and CDN delivery. You'll need to create a bunny.net account, set up a storage zone and pull zone, and configure four environment variables (storage zone name, CDN hostname, token key, and API key).
What file types and sizes does ConvexFS support?
ConvexFS supports standard web file types, including images, documents, and media files. The specific size limits and supported formats depend on the component's current implementation details.
How does ConvexFS pricing work compared to external storage services?
ConvexFS itself is a free open-source component, but bunny.net storage and CDN costs are separate. bunny.net offers a trial period and affordable pay-as-you-go pricing. Your Convex usage (database, functions) is billed normally through Convex.
Use with agents and CLI
Give your coding agent the component’s source identity and setup guidance.
Help me integrate File System with Bijection.
Read: https://bijection.com/components/convex-fs/SKILL.md
Check SDK compatibility and dependency availability.
Follow this project's execution and verification rules.Upstream README.md
View repository ↗Documentation from jamwt/convex-fs, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.
ConvexFS
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
Alpha — This project is in active development. APIs may change before 1.0.
Documentation
For installation instructions, guides, and API reference, visit:
License
Apache-2.0