fastify-xstorage

S3-compatible file storage for Fastify v5. Register once and get fastify.xStorage — a full-featured decorator covering upload, download, delete, copy, move, list, existence checks, metadata, signed download URLs, and presigned upload URLs. Works with AWS S3, Cloudflare R2, DigitalOcean Spaces, and any S3-compatible provider.

Installation

npm install @xenterprises/fastify-xstorage

For HTTP file uploads, also install:

npm install @fastify/multipart@9

Quick Start

import Fastify from "fastify";
import xStorage from "@xenterprises/fastify-xstorage";

const fastify = Fastify({ logger: true });

await fastify.register(xStorage, {
  accessKeyId: process.env.STORAGE_ACCESS_KEY_ID,
  secretAccessKey: process.env.STORAGE_SECRET_ACCESS_KEY,
  bucket: process.env.STORAGE_BUCKET,
  publicUrl: process.env.STORAGE_PUBLIC_URL,
  endpoint: process.env.STORAGE_ENDPOINT, // omit for AWS S3
});

// Upload a file
const result = await fastify.xStorage.upload(buffer, "photo.jpg", {
  folder: "avatars",
});
// { key: "avatars/photo-a1b2c3d4.jpg", url: "https://cdn.example.com/...", ... }

// Signed download URL (1 hour)
const url = await fastify.xStorage.getSignedUrl(result.key, 3600);

Options

Methods

Upload

• upload(file, filename, options?) — Upload a single file with auto-naming, folder prefix, and MIME detection.
• uploadMultiple(files, options?) — Upload multiple files concurrently.

Download

• download(key) — Download a file and return it as a Buffer.

Delete

• delete(key) — Delete a single file.
• deleteMultiple(keys) — Batch-delete multiple files via the S3 DeleteObjects API.

Copy & Move

• copy(sourceKey, destinationKey, options?) — Copy a file within the bucket.
• move(sourceKey, destinationKey, options?) — Move a file (copy then delete source).

Metadata & Existence

• exists(key) — Check whether a file exists without downloading it.
• getMetadata(key) — Get content type, size, last-modified, ETag, and custom metadata.

List

• list(prefix?, maxKeys?) — List files under a prefix (single page, up to maxKeys).
• listAll(prefix?) — List all files under a prefix with automatic pagination.

URLs

• getSignedUrl(key, expiresIn?) — Generate a temporary pre-signed download URL.
• getSignedUploadUrl(key, options?) — Generate a pre-signed upload URL for direct client-to-S3 uploads.
• getPublicUrl(key) — Synchronously construct the public URL for a file.

Error Reference

Registration errors

Registration fails fast with errors that name the plugin, the option, its type, and a usage example:

Method errors

Method calls validate inputs before touching S3 and throw Errors prefixed with [xStorage]:

exists() is the only method that swallows an S3 error — a 404/NotFound returns false; any other error is rethrown.

Environment Variables

The plugin never reads process.env — all configuration arrives via the options object passed to app.register(). The variables below are a consumer convention: your application owns env access, reads these variables, and passes the values in as options:

await fastify.register(xStorage, {
  accessKeyId: process.env.STORAGE_ACCESS_KEY_ID,
  secretAccessKey: process.env.STORAGE_SECRET_ACCESS_KEY,
  bucket: process.env.STORAGE_BUCKET,
  publicUrl: process.env.STORAGE_PUBLIC_URL,
  endpoint: process.env.STORAGE_ENDPOINT, // omit for AWS S3
  region: process.env.STORAGE_REGION, // optional, defaults to "us-east-1"
});

Nothing is auto-detected: if you don't read an env var and pass it in, the plugin never sees it. Variable names are yours to choose — the plugin only validates the options object.

How It Works

On registration the plugin validates all required options, creates an S3Client with the provided credentials and optional custom endpoint, then decorates fastify.xStorage with all storage methods. The publicUrl trailing slash is normalised once at startup. Uploaded files get a random 8-byte hex suffix by default to avoid collisions (useRandomName: false disables this). MIME types are auto-detected from the filename extension via mime-types. list() returns a single page up to maxKeys; listAll() follows ContinuationToken until all results are fetched. move() is copy-then-delete. exists() uses HeadObject and returns false on 404 without throwing. getSignedUploadUrl() generates a PutObject presigned URL so clients can upload directly to storage without routing file payloads through your Fastify server.

AI Context

package: "@xenterprises/fastify-xstorage"
type: fastify-plugin
use-when: File storage with AWS S3, Cloudflare R2, or DigitalOcean Spaces — upload, download, delete, copy/move, list, signed URLs
decorator: fastify.xStorage
env: STORAGE_ACCESS_KEY_ID, STORAGE_SECRET_ACCESS_KEY, STORAGE_BUCKET, STORAGE_PUBLIC_URL, STORAGE_ENDPOINT (optional), STORAGE_REGION (optional) — consumer convention; the app reads these and passes values into register options (the plugin never reads process.env)
requires: accessKeyId, secretAccessKey, bucket, publicUrl at registration