@stack-upload-orchestrator/storage-s3

AWS S3 storage adapter for @stack-upload-orchestrator/node.

Streams uploaded files directly to S3 using the AWS SDK v3 multipart upload API.

Installation

npm install @stack-upload-orchestrator/storage-s3 @stack-upload-orchestrator/node
npm install @aws-sdk/client-s3 @aws-sdk/lib-storage
# optional — only needed for getSignedUrl:
npm install @aws-sdk/s3-request-presigner

Usage

import { S3Client } from '@aws-sdk/client-s3';
import { S3Storage } from '@stack-upload-orchestrator/storage-s3';

const storage = new S3Storage({
  client: new S3Client({ region: 'us-east-1' }),
  bucket: 'my-uploads-bucket',
  prefix: 'uploads/',
  acl: 'public-read',
});

Pass it to any handler:

// With Next.js
import { createUploadHandler } from '@stack-upload-orchestrator/next';
export const POST = createUploadHandler({ storage });

// With Node.js / Express
import { handleUpload } from '@stack-upload-orchestrator/node';
const files = await handleUpload(req, { storage });

S3Storage

new S3Storage(options: S3StorageOptions)

Options

| Option | Type | Description | |---|---|---| | client | S3Client | Configured AWS SDK v3 S3 client | | bucket | string | S3 bucket name | | prefix | string | Key prefix applied to every object, e.g. "uploads/" | | acl | ObjectCannedACL | S3 canned ACL, e.g. "public-read". Omit for private buckets. | | key | (meta) => string \| Promise<string> | Custom key resolver. Defaults to <uuid><original-extension> | | baseUrl | string | Base URL for returned file URLs. Defaults to https://<bucket>.s3.amazonaws.com |

Methods

| Method | Description | |---|---| | upload(stream, meta) | Streams the file to S3 and returns UploadResult | | delete(fileId) | Deletes the S3 object by its key | | getSignedUrl(fileId, expiresIn?) | Returns a pre-signed GET URL. expiresIn defaults to 3600 seconds. Requires @aws-sdk/s3-request-presigner. |

Custom key

const storage = new S3Storage({
  client,
  bucket: 'my-bucket',
  prefix: 'avatars/',
  key: (meta) => `${meta.filename}`,
});

Custom base URL (CDN)

const storage = new S3Storage({
  client,
  bucket: 'my-bucket',
  baseUrl: 'https://cdn.example.com',
});

UploadResult

{
  url: string;      // baseUrl + "/" + key
  fileId: string;   // full S3 object key (use this for delete / getSignedUrl)
  name: string;     // original filename from the upload
  size: number;     // always 0 (S3 multipart upload does not return final size)
  type: string;     // MIME type
}

License

MIT