Run Cloud Storage locally
Storage support is incomplete. Check its generated conformance page for the exact public API coverage before depending on a feature.
Files land in your sandbox the way documents do: locally, with rules deciding what gets in.
Upload and download
import { initializeSandbox } from 'pyric/sandbox';
import { getStorageSandbox, ref, uploadBytes, getBlob } from 'pyric/storage';
const sandbox = initializeSandbox();
const storage = getStorageSandbox(sandbox.withAuth({ uid: 'alice' }));
const bytes = new TextEncoder().encode(JSON.stringify({ task: 'build a notes app' }));
await uploadBytes(ref(storage, 'sessions/s1'), bytes, { contentType: 'application/json' });
const blob = await getBlob(ref(storage, 'sessions/s1'));
console.log(JSON.parse(await blob.text()));
uploadString covers text without the encoder, and getBytes returns an ArrayBuffer when you want raw bytes instead of a Blob. Under pyric sandbox, a served page’s firebase/storage imports resolve to the sandbox’s shared object store, so uploads show up across tabs like every other write. pyric sandbox enforces storage.rules the same as firestore.rules and database.rules.json. Saving storage.rules, or the file firebase.json names under storage.rules, reloads the rules without a restart, including a file created after the server started. A save that fails to parse keeps the last rules that loaded. Deleting the file returns Storage to denying every client operation, the state the server starts in without the file.
List and delete
import { listAll, deleteObject } from 'pyric/storage';
const listing = await listAll(ref(storage, 'sessions'));
console.log(listing.items.map((item) => item.name)); // ['s1']
await deleteObject(ref(storage, 'sessions/s1'));
Metadata rides along
Set it at upload, read it back, patch it later:
import { getMetadata, updateMetadata } from 'pyric/storage';
await uploadBytes(ref(storage, 'sessions/s1'), bytes, {
contentType: 'application/json',
customMetadata: { sessionId: 's1', version: '1.0' },
});
const meta = await getMetadata(ref(storage, 'sessions/s1'));
console.log(meta.size, meta.customMetadata?.sessionId);
await updateMetadata(ref(storage, 'sessions/s1'), {
customMetadata: { ...meta.customMetadata, version: '1.1' },
});
Two contracts worth knowing, both matching the upstream SDK:
updateMetadatareplaces the settable fields rather than merging. Fetch first and spread, as above.customMetadatais string-to-string, so numbers and objects need serializing.
Enforce storage rules in-process
Pass rules when you configure the handle, and every operation evaluates against them, no deploy anywhere:
const RULES = `service firebase.storage {
match /b/{bucket}/o {
match /sessions/{id} {
allow read: if request.auth != null;
allow write: if request.auth != null
&& (request.method == 'delete'
|| (request.resource.size < 10 * 1024 * 1024
&& request.resource.contentType == 'application/json'));
}
}
}`;
const storage = getStorageSandbox(sandbox.withAuth({ uid: 'alice' }), { rules: RULES });
An anonymous upload and an 11 MiB payload both throw FirebaseError with storage/unauthorized.
Notice the request.method == 'delete' carve-out. deleteObject carries no incoming payload, and production treats reading or null-checking the absent request.resource as an error. Testing the method lets deletes through while keeping payload checks on creates and updates.
One rule-shape gotcha carried over faithfully from production: listAll requires read on the listed folder itself. A rule scoped to match /sessions/{id} grants nothing on /sessions, so give the folder its own read rule.
Serve production download URLs from your service worker
A page that loads a production download URL directly, such as <img src="https://firebasestorage.googleapis.com/v0/b/<bucket>/o/<path>?alt=media&token=<token>">, never reaches the sandbox. If your app has its own service worker, sandboxStorageFetch from pyric/storage/sw answers those requests from the Node host’s byte route (pyric sandbox, or the Vite plugin with hosted: true) and returns whether it answered:
import { sandboxStorageFetch } from 'pyric/storage/sw';
self.addEventListener('fetch', (event) => {
if (import.meta.env.DEV && sandboxStorageFetch(event)) return;
});
It maps the same URLs as localStorageUrl from @pyric/cli/remote: the firebasestorage.googleapis.com download form and the storage.googleapis.com and storage.cloud.google.com forms. It keeps the bucket, the path and the token, drops production-only parameters such as generation, and carries the method and headers such as Range. It answers only GET and HEAD, and leaves every other request untouched for the browser or your own handlers. The byte route is on the service worker’s own origin unless you pass { origin }.
It answers every production Storage URL, so gating it to development is your app’s job, as the import.meta.env.DEV check above does. The module imports nothing beyond its URL mapping, so it adds little to a service worker bundle.
With the Vite plugin, you can leave your service worker without a Pyric import. Name its source file with the serviceWorker option, for example a vite-plugin-pwa injectManifest source:
pyric({ hosted: true, serviceWorker: 'src/sw.ts' })
In vite dev, the plugin adds a fetch listener to that module ahead of your code. The listener calls sandboxStorageFetch and stops other fetch listeners for the requests it answers. The plugin imports the helper from its own install, so it works when Pyric is installed outside your app’s node_modules. vite build leaves the file as written.
Check support before choosing an operation
Per-feature support is tracked on the Cloud Storage conformance page.
Where to go next
For structured documents and queries, use Store and query data.