# @storyshelf/storage-s3

> Store StoryShelf artifacts in AWS S3, Cloudflare R2, MinIO, or another S3-compatible service.

Source: https://storyshelf.js.org/packages/storage-s3/

`@storyshelf/storage-s3` stores StoryShelf blobs in an S3-compatible object store. It supports AWS S3, Cloudflare R2, MinIO, and DigitalOcean Spaces.

## Install

```sh
npm i @storyshelf/storage-s3
```

[![JSR](https://jsr.io/badges/@storyshelf/storage-s3)](https://jsr.io/@storyshelf/storage-s3) [![JSR Score](https://jsr.io/badges/@storyshelf/storage-s3/score)](https://jsr.io/@storyshelf/storage-s3)

- [npm package](https://www.npmjs.com/package/@storyshelf/storage-s3) — install tarballs and version history.
- [JSR package](https://jsr.io/@storyshelf/storage-s3) — TypeScript-first registry page.
- [Public API reference](https://storyshelf.js.org/reference/storage-s3/) — generated docs for every export; start here to learn the API. (The same reference is on [JSR](https://jsr.io/@storyshelf/storage-s3/doc).)
- [Source on GitHub](https://github.com/GuptaSiddhant/storyshelf/tree/main/packages/storage-s3) — package directory on `main`.

## Configure

```ts
import { createS3Storage } from "@storyshelf/storage-s3";
import { createShelfApp } from "@storyshelf/app";

const storage = createS3Storage({
  bucket: "my-shelf",
  prefix: "storyshelf",
  endpoint: process.env.S3_ENDPOINT, // optional, e.g. for MinIO/R2
  region: "us-east-1", // optional
});

const app = createShelfApp({ database, storage });
```

### `S3StorageOptions`

```ts
interface S3StorageOptions {
  bucket: string; // required bucket name
  prefix?: string; // optional key prefix, defaults to ""
  endpoint?: string; // optional custom endpoint (MinIO, R2, etc.)
  region?: string; // optional region, defaults to "us-east-1"
}
```

### `createS3Storage(options: S3StorageOptions): StorageAdapter`

Creates an S3 client (with `forcePathStyle` enabled for compatibility with MinIO/R2) and returns a `StorageAdapter`. The returned adapter implements every method of the `StorageAdapter` interface (`read`, `write`, `delete`, `exists`, `list(prefix)`).

### `s3Key(prefix: string, path: string): string`

Helper that joins a storage prefix with a relative path into an object key.

## When to use it

Choose S3 storage for cloud or multi-node deployments. It is a drop-in replacement for [local storage](../storage-local/), and pairs naturally with the [Turso preset](../db-sqlite/#presets-same-schema-different-driver) when the application is deployed without shared local disk.