@xyz/cdn

S3-compatible storage utilities with signed URL generation.

Installation

npm install @xyz/cdn

Quick Start

import { createStorage } from "@xyz/cdn";

const storage = createStorage({
  endpoint: process.env.S3_ENDPOINT!,
  accessKeyId: process.env.S3_ACCESS_KEY_ID!,
  secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
  bucket: "my-bucket",
});

// Get a signed download URL
const downloadUrl = await storage.getSignedUrl("/path/to/file.pdf", {
  expiresIn: 3600, // seconds
});

// Get a signed upload URL
const uploadUrl = await storage.getSignedUploadUrl("/path/to/new-file.pdf");

Nuxt Server Handler Example

Serve files directly from your Nuxt API routes:

// server/routes/files/[...path].ts
import { createStorage } from "@xyz/cdn";

const storage = createStorage({
  endpoint: process.env.S3_ENDPOINT!,
  accessKeyId: process.env.S3_ACCESS_KEY_ID!,
  secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
  bucket: process.env.S3_BUCKET!,
});

export default defineEventHandler(async (event) => {
  const path = event.context.params?.path;
  return storage.serve(path, { cacheMaxAge: 86400 });
});

API Reference

createStorage(config)

Creates a configured storage client.

Config options:

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | endpoint | string | ✓ | - | S3-compatible endpoint URL | | accessKeyId | string | ✓ | - | Access key ID | | secretAccessKey | string | ✓ | - | Secret access key | | bucket | string | - | - | Default bucket name | | region | string | - | "auto" | AWS region | | defaultExpiresIn | number | - | 3600 | Default URL expiration (seconds) |

storage.getSignedUrl(path, options?)

Returns a signed URL for downloading a file.

storage.getSignedUploadUrl(path, options?)

Returns a signed URL for uploading a file.

storage.serve(path, options?)

Fetches a file and returns a Response object. Handles errors, content-type detection, and caching headers automatically.

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | bucket | string | - | Bucket name (overrides default) | | expiresIn | number | 3600 | URL expiration (seconds) | | cacheMaxAge | number | 86400 | Cache-Control max-age (set to 0 to disable) |

Utilities

import { normalizePath, stripPrefix } from "@xyz/cdn";

normalizePath("//path//to/file"); // "/path/to/file"
stripPrefix("/avatars/user/photo.jpg", "/avatars"); // "/user/photo.jpg"

License

MIT