Files

Module for storing and serving files (avatars, attachments) in SpacetimeDB apps. Supports upload, rename, delete, listing, visibility controls, and HTTP serving with caching.

  • TypeScript
npm i @spacetimedb/files

A composable module for storing, serving, and managing user files (such as avatars and message attachments) directly inside a SpacetimeDB application. It sits in the server-side layer of a SpacetimeDB module, handling file metadata and binary content in the database while exposing upload, rename, delete, list, and HTTP download capabilities to the rest of the app.

  • User avatars and profile images: An app where each user uploads a profile picture that other users can view publicly via a cached HTTP route.
  • Chat attachments: A messaging app where users attach files to conversations, with per-owner storage quotas and private-by-default visibility.
  • Content management: A small CMS or dashboard where authenticated users manage a folder-like hierarchy of assets and need paginated directory listings.
  • Secure file downloads: An app that needs to gate file access behind application-level auth, serving private files only to verified callers while caching public ones efficiently.
  • Multi-tenant storage: A platform where many users share the same path namespace without collision, each subject to their own storage quota.

Files are stored in two parts: a metadata record and a separate binary record. Keeping them separate means that listing files, checking whether a file exists, or responding to a cache-validation request never requires loading the raw bytes. Each file belongs to an owner (identified by any opaque string the host application chooses, such as a user ID) and is addressed by a path within that owner's namespace. Two different owners can use the same path without conflict.

Visibility controls whether a file is accessible to anyone or only to its owner. The module enforces size limits per file and a total quota per owner at write time, and it computes a content fingerprint server-side so that HTTP clients can cache responses and skip re-downloading unchanged files. The HTTP serving layer handles cache headers, conditional responses, and content-type safety automatically, including forcing non-image types to download rather than render in the browser.

The host application wires the module into its own reducers and procedures, deciding how to derive the owner identity from the authenticated caller. Access control for private files over HTTP is left to the host, which can integrate with a separate auth module to verify the request before passing it through. This design keeps the file module focused on storage mechanics while letting the application own its own identity and permission model.

Related modules

S3

Manages private file uploads and downloads between browsers and Amazon S3, tracking ownership and file state in SpacetimeDB with automatic retry on failure.

SpacetimeDB0/wk

Agents

Stores conversations and runs AI assistants inside your SpacetimeDB module, with tools that can read and update your application's data.

SpacetimeDB0/wk

Auth

Adds user accounts, password and OAuth sign-in, email verification, and session management to a SpacetimeDB module. Exposes helpers to identify the caller in reducers and HTTP routes.

SpacetimeDB0/wk
Submodule

Edit details

One short paragraph describing the module.

A few bullets for scenarios where this is a good fit.

A few short paragraphs at the conceptual level.