# @payloadcms/storage-s3

> Payload storage adapter for Amazon S3

Latest version **3.90.2** (published 2026-09-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install @payloadcms/storage-s3
pnpm add @payloadcms/storage-s3
yarn add @payloadcms/storage-s3
bun add @payloadcms/storage-s3
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; popular repo.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.90.2 |
| Published | 2026-09-23 |
| First published | 2024-04-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^18.20.2 \|\| >=20.9.0 |
| Dependencies | 4 |
| Unpacked size | 84.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 44947 |
| Author | Payload <dev@payloadcms.com> (https://payloadcms.com) |
| Maintainers | payloadjs, german.jablo, elliotpayload, danribbens, seanpayload, jmikrut, jacobsfletch, jesschow, alessiogr, patrikkozak, jarrodmflesch |

## Links

- npm: https://www.npmjs.com/package/@payloadcms/storage-s3
- Repository: https://github.com/payloadcms/payload
- Homepage: https://payloadcms.com
- npm.io page: https://npm.io/package/@payloadcms/storage-s3

## Dependencies (4)

- [@aws-sdk/client-s3](https://npm.io/package/@aws-sdk/client-s3.md) ^3.614.0
- [@aws-sdk/lib-storage](https://npm.io/package/@aws-sdk/lib-storage.md) ^3.614.0
- [@aws-sdk/s3-request-presigner](https://npm.io/package/@aws-sdk/s3-request-presigner.md) ^3.614.0
- [@payloadcms/plugin-cloud-storage](https://npm.io/package/@payloadcms/plugin-cloud-storage.md) 3.90.2

## Recent versions

- 3.90.2 (latest) — 2026-09-23
- 4.0.0-internal.b8a92d2 (internal) — 2026-09-28
- 4.0.0-canary.37 (canary) — 2026-09-24
- 3.81.0-internal-debug.1a0f4d0 (internal-debug) — 2026-03-25
- 3.0.0-beta.135 (beta) — 2024-11-19
- 3.91.0-internal.c1569dc — 2026-09-25
- 4.0.0-internal.77191e5 — 2026-09-25
- 4.0.0-canary.36 — 2026-09-21
- 3.91.0-internal.6e3dc85 — 2026-09-21
- 4.0.0-canary.35 — 2026-09-18
- 3.90.1 — 2026-09-18
- 4.0.0-canary.34 — 2026-09-18
- 3.90.0 — 2026-09-18
- 4.0.0-internal.b8e7c89 — 2026-09-14
- 3.89.0 — 2026-09-10
- … 1342 more at https://npm.io/package/@payloadcms/storage-s3/versions

## README

# S3 Storage for Payload

This package provides a simple way to use S3 with Payload.

**NOTE:** This package removes the need to use `@payloadcms/plugin-cloud-storage` as was needed in Payload 2.x.

## Installation

```sh
pnpm add @payloadcms/storage-s3
```

## Usage

- Configure the `collections` object to specify which collections should use the AWS S3 adapter. The slug _must_ match one of your existing collection slugs.
- The `config` object can be any [`S3ClientConfig`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3) object (from [`@aws-sdk/client-s3`](https://github.com/aws/aws-sdk-js-v3)). _This is highly dependent on your AWS setup_. Check the AWS documentation for more information.
- When enabled, this package will automatically set `disableLocalStorage` to `true` for each collection.
- When deploying to Vercel, server uploads are limited with 4.5MB. Set `clientUploads` to `true` to do uploads directly on the client. You must allow CORS PUT method for the bucket to your website.
- Configure `signedDownloads` (either globally of per-collection in `collections`) to use [presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html) for files downloading. This can improve performance for large files (like videos) while still respecting your access control. Additionally, with `signedDownloads.shouldUseSignedURL` you can specify a condition whether Payload should use a presigned URL, if you want to use this feature only for specific files.

```ts
import { s3Storage } from '@payloadcms/storage-s3'
import { Media } from './collections/Media'
import { MediaWithPrefix } from './collections/MediaWithPrefix'

export default buildConfig({
  collections: [Media, MediaWithPrefix],
  plugins: [
    s3Storage({
      collections: {
        media: true,
        'media-with-prefix': {
          prefix,
        },
        'media-with-presigned-downloads': {
          // Filter only mp4 files
          signedDownloads: {
            shouldUseSignedURL: ({ collection, filename, req }) => {
              return filename.endsWith('.mp4')
            },
          },
        },
      },
      bucket: process.env.S3_BUCKET,
      config: {
        credentials: {
          accessKeyId: process.env.S3_ACCESS_KEY_ID,
          secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
        },
        region: process.env.S3_REGION,
        // ... Other S3 configuration
      },
    }),
  ],
})
```

### Configuration Options

See the the [AWS SDK Package](https://github.com/aws/aws-sdk-js-v3) and [`S3ClientConfig`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3) object for guidance on AWS S3 configuration.

---
_Source: https://npm.io/package/@payloadcms/storage-s3 · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._