@xyz/cdn

S3-compatible storage utilities with signed URL generation.

Installation

``bash
npm install @xyz/cdn
`

Quick Start

`typescript
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:

`typescript
// 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

$3

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) |

$3

Returns a signed URL for downloading a file.

$3

Returns a signed URL for uploading a file.

$3

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

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

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

License

MIT