@beignet/provider-storage-local

Local filesystem storage provider for Beignet.

The provider installs the app-facing ctx.ports.storage port. Use it for local development, tests that need durable files, and small deployments where a filesystem-backed object store is enough.

Install

bun add @beignet/provider-storage-local
Copy

Provider setup

import { localStorageProvider } from "@beignet/provider-storage-local";
import { createServer } from "@beignet/core/server";

const server = await createServer({
  ports: basePorts,
  providers: [localStorageProvider],
  createContext: ({ ports }) => ({ ports }),
  routes,
});
Copy

Environment variables:

STORAGE_PUBLIC_BASE_URL may be an absolute URL such as https://assets.example.com or an app-relative path such as /storage. The provider only returns URLs. If you use an app-relative path in a Next.js app, serve public objects with createStorageRoute:

// app/storage/[...key]/route.ts
import { createStorageRoute } from "@beignet/next";
import { server } from "@/server";

export const { GET, HEAD } = createStorageRoute(server.ports.storage, {
  basePath: "/storage",
});
Copy

Direct port factory

import { createLocalStorage } from "@beignet/provider-storage-local";

const storage = createLocalStorage({
  root: "storage/app",
  publicBaseUrl: "/storage",
});
Copy

The same StoragePort works with local files, memory tests, and cloud object stores:

await ctx.ports.storage.put("avatars/user_123.png", avatarBytes, {
  contentType: "image/png",
  visibility: "public",
});

const object = await ctx.ports.storage.get("avatars/user_123.png");
const url = await ctx.ports.storage.publicUrl("avatars/user_123.png");
Copy

Files on disk

Objects are written below root using their storage key. Object metadata is stored in a .beignet-storage-meta sidecar directory below the same root.

Storage keys must be relative object keys: no empty strings, empty path segments, leading or trailing /, backslashes, or . / .. path segments. The .beignet-storage-meta path segment is reserved for the provider's sidecar metadata.

Devtools

When ctx.ports.devtools is installed, the provider records storage operations under the storage watcher. Events include operation name, key, duration, object size, visibility, and whether a lookup hit. Object bodies are never recorded.

License

MIT