@antelopejs/file-storage-local

Local-filesystem implementation of the AntelopeJS file-storage interface. It provides signed upload and read URLs, public and private visibility, named storage roots, metadata, and staged-file promotion.

Use this module for local development and single-instance deployments. Files are stored on one machine and are not shared between replicas. Use @antelopejs/file-storage-s3 for clustered or horizontally scaled deployments.

Installation

pnpm add @antelopejs/file-storage-local

The module implements @antelopejs/interface-file-storage. Install an AntelopeJS API module as well to expose its upload and download routes.

Configuration

Add the module to antelope.config.ts:

import { defineConfig } from "@antelopejs/interface-core/config";

export default defineConfig({
  name: "my-app",
  modules: {
    storage: {
      source: {
        type: "package",
        package: "@antelopejs/file-storage-local",
      },
      config: {
        storagePath: ".antelope/storage",
        baseUrl: "http://localhost:3000",
        defaultVisibility: "private",
        uploadTokenExpiration: 3600,
        readTokenExpiration: 300,
        cleanupInterval: 300,
      },
    },
  },
});

Expiration and cleanup values are expressed in seconds. Set stagingExpiration to periodically remove staged files that were never promoted.

Named storage roots can provide independent policies:

config: {
  storagePath: ".antelope/storage",
  baseUrl: "http://localhost:3000",
  defaultVisibility: "private",
  uploadTokenExpiration: 3600,
  readTokenExpiration: 300,
  cleanupInterval: 300,
  storages: {
    media: {
      storagePath: ".antelope/media",
      baseUrl: "http://localhost:3000",
      defaultVisibility: "public",
      uploadTokenExpiration: 3600,
      readTokenExpiration: 300,
      cleanupInterval: 300,
    },
  },
}

Storage roots must not overlap. The name default is reserved.

Development

pnpm install
pnpm lint
pnpm format:check
pnpm test

See the organization-wide contribution guidelines and security policy.

License

Apache-2.0