@lucidcms/plugin-s3/README.md

The official S3 plugin for Lucid CMS

# Lucid CMS - S3 Plugin

> The official S3 plugin for Lucid

The Lucid CMS S3 plugin registers the required media strategy functions to stream, upload, update and delete media from any S3 compatible storage solution. This plugin supports AWS S3, Cloudflare R2, and other S3-compatible storage providers.

## Installation

```bash
npm install @lucidcms/plugin-s3
```

## Setup

To use the S3 plugin, you need to add it to your Lucid CMS config file. You'll need to provide your S3 endpoint, bucket name, and client configuration.

```typescript
import { configureLucid } from "@lucidcms/core";
import { node } from "@lucidcms/runtime-node";
import { s3Plugin } from "@lucidcms/plugin-s3";
import { sqlite } from "@lucidcms/db-sqlite";

export default configureLucid({
	runtime: node,
	db: sqlite,
	config: (env) => ({
		plugins: [
			s3Plugin({
				endpoint: env.S3_ENDPOINT,
				bucket: env.S3_BUCKET,
				clientOptions: {
					region: "auto",
					accessKeyId: env.S3_ACCESS_KEY_ID,
					secretAccessKey: env.S3_SECRET_ACCESS_KEY,
				},
			}),
		],
	}),
});
```

## Configuration

This plugin offers the following configuration options to control S3 storage behavior.

| Property | Type | Description |
|----------|------|-------------|
| `endpoint` | `string` | The S3 endpoint URL |
| `bucket` | `string` | The name of your S3 bucket |
| `clientOptions` | `object` | S3 client configuration options |

### endpoint

The S3 endpoint URL for your storage provider. This will vary depending on your provider, please refer to their documentation for the correct endpoint.

### bucket

The name of your S3 bucket where media files will be stored.

### clientOptions

Configuration options for the S3 client connection.

| Property | Type | Description |
|----------|------|-------------|
| `region` | `string` | The AWS region (use "auto" for Cloudflare R2) |
| `accessKeyId` | `string` | Your S3 access key ID |
| `secretAccessKey` | `string` | Your S3 secret access key |

## Bucket Configuration

Lucid CMS uploads media from the client using upload sessions. Single-upload sessions and resumable multipart upload parts are signed by the S3 adapter, so your bucket CORS policy must allow `PUT` requests, along with the `Content-Type`, `Origin`, and `x-amz-meta-*` headers.
Expose the `ETag` response header if possible so the admin UI can complete multipart uploads without an extra server-side reconciliation request.

### Example Cloudflare R2 CORS Policy

```json
[
    {
        "AllowedOrigins": [
            "YOUR_CMS_ORIGIN_URL"
        ],
        "AllowedMethods": [
            "GET",
            "PUT"
        ],
        "AllowedHeaders": [
            "Origin",
            "Content-Type",
            "x-amz-meta-*"
        ],
        "ExposeHeaders": [
            "ETag"
        ]
    }
]
```