fastify-xstorage
S3-compatible storage plugin for AWS S3, Cloudflare R2, and DigitalOcean Spaces.
fastify-xstorage
S3-compatible file storage supporting AWS S3, Cloudflare R2, and DigitalOcean Spaces with a simple, consistent API.
Installation
npm install @xenterprises/fastify-xstorage
Quick Start
await fastify.register(xStorage, {
bucket: process.env.STORAGE_BUCKET,
region: process.env.AWS_REGION || 'auto',
// For Cloudflare R2:
endpoint: `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`,
credentials: {
accessKeyId: process.env.AWS_ACCESS_KEY_ID,
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
},
})
API
fastify.xstorage.upload(options)
const url = await fastify.xstorage.upload({
key: `avatars/${userId}.jpg`,
body: fileBuffer,
contentType: 'image/jpeg',
acl: 'public-read', // optional
})
// Returns: public URL
fastify.xstorage.download(key)
const stream = await fastify.xstorage.download('documents/report.pdf')
fastify.xstorage.delete(key)
await fastify.xstorage.delete('avatars/old-avatar.jpg')
fastify.xstorage.getSignedUrl(key, expiresIn)
const url = await fastify.xstorage.getSignedUrl('private/report.pdf', 3600)
Configuration
| Option | Type | Description |
|---|---|---|
bucket | string | Bucket name |
region | string | AWS region or 'auto' for R2 |
endpoint | string | Custom endpoint for R2/DO |
credentials | object | { accessKeyId, secretAccessKey } |
AI Context
package: "@xenterprises/fastify-xstorage"
type: fastify-plugin
decorates: fastify.xstorage
use-when: File uploads, document storage, image hosting
providers: [AWS S3, Cloudflare R2, DigitalOcean Spaces]
methods:
upload: key + buffer → public URL
download: key → readable stream
delete: key → void
getSignedUrl: key + seconds → presigned URL
env-required: [STORAGE_BUCKET, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY]
env-r2: also needs STORAGE_ENDPOINT with account ID