uppy/docs/uploader/aws-s3.mdx

---
sidebar_position: 3
slug: /aws-s3
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import UppyCdnExample from '/src/components/UppyCdnExample';

# AWS S3 (legacy)

The `@uppy/aws-s3` plugin can be used to upload files directly to a S3 bucket or
a S3-compatible provider, such as Google Cloud Storage or DigitalOcean Spaces.
Uploads can be signed using either [Companion][companion docs] or a custom
signing function.

This documents the legacy version of this plugin that we plan to remove on the
next version.

## When should I use it?

:::tip

Not sure which uploader is best for you? Read
“[Choosing the uploader you need](/docs/guides/choosing-uploader)”.

:::

:::warning

This plugin is deprecated, you should switch to using the
[modern version of this plugin](/docs/aws-s3-multipart).

:::

You can use this plugin when you prefer a _client-to-storage_ over a
_client-to-server-to-storage_ (such as [Transloadit](/docs/transloadit) or
[Tus](/docs/tus)) setup. This may in some cases be preferable, for instance, to
reduce costs or the complexity of running a server and load balancer with
[Tus](/docs/tus).

This plugin can be used with AWS S3, DigitalOcean Spaces, Google Cloud Storage,
or any S3-compatible provider. Although all S3-compatible providers are
supported, we don’t test against them, this plugin was developed against S3 so a
small risk is involved in using the others.

`@uppy/aws-s3` is best suited for small files and/or lots of files. If you are
planning to upload mostly large files (100 MB+), consider using
[`@uppy/aws-s3-multipart`](/docs/aws-s3-multipart).

## Install

<Tabs>
  <TabItem value="npm" label="NPM" default>

```shell
npm install @uppy/aws-s3
```

  </TabItem>

  <TabItem value="yarn" label="Yarn">

```shell
yarn add @uppy/aws-s3
```

  </TabItem>

  <TabItem value="cdn" label="CDN">
    <UppyCdnExample>
      {`
        import { Uppy, AwsS3 } from "{{UPPY_JS_URL}}"
        new Uppy().use(AwsS3, { /* see options */ })
      `}
    </UppyCdnExample>
  </TabItem>
</Tabs>

## Use

A quick overview of the complete API.

```js {10} showLineNumbers
import Uppy from '@uppy/core';
import Dashboard from '@uppy/dashboard';
import AwsS3 from '@uppy/aws-s3';

import '@uppy/core/dist/style.min.css';
import '@uppy/dashboard/dist/style.min.css';

const uppy = new Uppy()
	.use(Dashboard, { inline: true, target: 'body' })
	.use(AwsS3, { companionUrl: 'http://companion.uppy.io' });
```

### With a AWS S3 bucket

To use this plugin with S3 we need to setup a bucket with the right permissions
and CORS settings.

S3 buckets do not allow public uploads for security reasons. To allow Uppy and
the browser to upload directly to a bucket, its CORS permissions need to be
configured.

CORS permissions can be found in the
[S3 Management Console](https://console.aws.amazon.com/s3/home). Click the
bucket that will receive the uploads, then go into the `Permissions` tab and
select the `CORS configuration` button. A JSON document will be shown that
defines the CORS configuration. (AWS used to use XML but now only allow JSON).
More information about the
[S3 CORS format here](https://docs.amazonaws.cn/en_us/AmazonS3/latest/userguide/ManageCorsUsing.html).

The configuration required for Uppy and Companion is this:

```json
[
	{
		"AllowedOrigins": ["https://my-app.com"],
		"AllowedMethods": ["GET", "POST"],
		"MaxAgeSeconds": 3000,
		"AllowedHeaders": [
			"Authorization",
			"x-amz-date",
			"x-amz-content-sha256",
			"content-type"
		]
	},
	{
		"AllowedOrigins": ["*"],
		"AllowedMethods": ["GET"],
		"MaxAgeSeconds": 3000
	}
]
```

A good practice is to use two CORS rules: one for viewing the uploaded files,
and one for uploading files. This is done above where the first object in the
array defines the rules for uploading, and the second for viewing. The example
above **makes files publicly viewable**. You can change it according to your
needs.

If you are using an IAM policy to allow access to the S3 bucket, the policy must
have at least the `s3:PutObject` and `s3:PutObjectAcl` permissions scoped to the
bucket in question. In-depth documentation about CORS rules is available on the
[AWS documentation site](https://docs.aws.amazon.com/AmazonS3/latest/dev/cors.html).

### With a DigitalOcean Spaces bucket

:::tip

Checkout the
[DigitalOcean Spaces example](https://github.com/transloadit/uppy/tree/main/examples/digitalocean-spaces)
in the Uppy repository for a complete, runnable example.

:::

DigitalOcean Spaces is S3-compatible so you only need to change the endpoint and
bucket. Make sure you have a `key` and `secret`. If not, refer to
“[How To Create a DigitalOcean Space and API Key](https://www.digitalocean.com/community/tutorials/how-to-create-a-digitalocean-space-and-api-key)”.

When using [Companion](/docs/companion) as standalone, you can set these as
environment variables:

```bash
export COMPANION_AWS_KEY="xxx"
export COMPANION_AWS_SECRET="xxx"
export COMPANION_AWS_REGION="us-east-1"
export COMPANION_AWS_ENDPOINT="https://{region}.digitaloceanspaces.com"
export COMPANION_AWS_BUCKET="my-space-name"
```

The `{region}` string will be replaced by the contents of the
`COMPANION_AWS_REGION` environment variable.

When using [Companion](/docs/companion) as an Express integration, configure the
`s3` options:

```js
const options = {
	s3: {
		key: 'xxx',
		secret: 'xxx',
		bucket: 'my-space-name',
		region: 'us-east-1',
		endpoint: 'https://{region}.digitaloceanspaces.com',
	},
};
```

### With a Google Cloud Storage bucket

For the `@uppy/aws-s3` plugin to be able to upload to a GCS bucket, it needs the
Interoperability setting enabled. You can enable the Interoperability setting
and
[generate interoperable storage access keys](https://cloud.google.com/storage/docs/migrating#keys)
by going to [Google Cloud Storage](https://console.cloud.google.com/storage) »
Settings » Interoperability. Then set the environment variables for Companion
like this:

```bash
export COMPANION_AWS_ENDPOINT="https://storage.googleapis.com"
export COMPANION_AWS_BUCKET="YOUR-GCS-BUCKET-NAME"
export COMPANION_AWS_KEY="GOOGxxxxxxxxx" # The Access Key
export COMPANION_AWS_SECRET="YOUR-GCS-SECRET" # The Secret
```

You do not need to configure the region with GCS.

You also need to configure CORS with their HTTP API. If you haven’t done this
already, see
[Configuring CORS on a Bucket](https://cloud.google.com/storage/docs/configuring-cors#Configuring-CORS-on-a-Bucket)
in the GCS documentation, or follow the steps below to do it using Google’s API
playground.

The JSON format consists of an array of CORS configuration objects. For
instance:

```json
{
	"cors": [
		{
			"origin": ["https://my-app.com"],
			"method": ["GET", "POST"],
			"maxAgeSeconds": 3000
		},
		{
			"origin": ["*"],
			"method": ["GET"],
			"maxAgeSeconds": 3000
		}
	]
}
```

When using presigned `PUT` uploads, replace the `"POST"` method by `"PUT"` in
the first entry.

If you have the [gsutil](https://cloud.google.com/storage/docs/gsutil)
command-line tool, you can apply this configuration using the
[gsutil cors](https://cloud.google.com/storage/docs/configuring-cors#configure-cors-bucket)
command.

```bash
gsutil cors set THAT-FILE.json gs://BUCKET-NAME
```

Otherwise, you can manually apply it through the OAuth playground:

1.  Get a temporary API token from the
    [Google OAuth2.0 playground](https://developers.google.com/oauthplayground/)
2.  Select the `Cloud Storage JSON API v1` » `devstorage.full_control` scope
3.  Press `Authorize APIs` and allow access
4.  Click `Step 3 - Configure request to API`
5.  Configure it as follows:
    1.  HTTP Method: PATCH
    2.  Request URI: `https://www.googleapis.com/storage/v1/b/YOUR_BUCKET_NAME`
    3.  Content-Type: application/json (should be the default)
    4.  Press `Enter request body` and input your CORS configuration
6.  Press `Send the request`.

### Use with your own server

The recommended approach is to integrate `@uppy/aws-s3` with your own server.
You will need to do the following things:

1. Setup a bucket
2. Create endpoints in your server. You can create them as edge functions (such
   as AWS Lambdas), inside Next.js as an API route, or wherever your server runs
   - `POST` > `/uppy/s3`: get upload parameters
3. [Setup Uppy](https://github.com/transloadit/uppy/blob/main/examples/aws-nodejs/public/index.html)

### Use with Companion

[Companion](/docs/companion) has S3 routes built-in for a plug-and-play
experience with Uppy.

:::caution

Generally it’s better for access control, observability, and scaling to
integrate `@uppy/aws-s3` with your own server. You may want to use
[Companion](/docs/companion) for creating, signing, and completing your S3
uploads if you already need Companion for remote files (such as from Google
Drive). Otherwise it’s not worth the hosting effort.

:::

```js {10} showLineNumbers
import Uppy from '@uppy/core';
import Dashboard from '@uppy/dashboard';
import AwsS3 from '@uppy/aws-s3';

import '@uppy/core/dist/style.min.css';
import '@uppy/dashboard/dist/style.min.css';

const uppy = new Uppy.use(Dashboard, { inline: true, target: 'body' }).use(
	AwsS3,
	{ companionUrl: 'http://companion.uppy.io' },
);
```

## Options

The `@uppy/aws-s3` plugin has the following configurable options:

#### `id`

A unique identifier for this plugin (`string`, default: `'AwsS3'`).

#### `companionUrl`

Companion instance to use for signing S3 uploads (`string`, default: `null`).

#### `companionHeaders`

Custom headers that should be sent along to [Companion](/docs/companion) on
every request (`Object`, default: `{}`).

#### `allowedMetaFields`

Pass an array of field names to limit the metadata fields that will be added to
upload as query parameters (`Array`, default: `null`).

- Set this to `['name']` to only send the `name` field.
- Set this to `null` (the default) to send _all_ metadata fields.
- Set this to an empty array `[]` to not send any fields.

#### `getUploadParameters(file)`

:::note

When using [Companion][companion docs] to sign S3 uploads, do not define this
option.

:::

A function that returns upload parameters for a file (`Promise`, default:
`null`).

Parameters should be returned as an object, or as a `Promise` that fulfills with
an object, with keys `{ method, url, fields, headers }`.

- The `method` field is the HTTP method to be used for the upload. This should
  be one of either `PUT` or `POST`, depending on the type of upload used.
- The `url` field is the URL to which the upload request will be sent. When
  using a presigned PUT upload, this should be the URL to the S3 object with
  signing parameters included in the query string. When using a POST upload with
  a policy document, this should be the root URL of the bucket.
- The `fields` field is an object with form fields to send along with the upload
  request. For presigned PUT uploads, this should be left empty.
- The `headers` field is an object with request headers to send along with the
  upload request. When using a presigned PUT upload, it’s a good idea to provide
  `headers['content-type']`. That will make sure that the request uses the same
  content-type that was used to generate the signature. Without it, the browser
  may decide on a different content-type instead, causing S3 to reject the
  upload.

#### `timeout`

When no upload progress events have been received for this amount of
milliseconds, assume the connection has an issue and abort the upload (`number`,
default: `30_000`).

This is passed through to [XHRUpload](/docs/xhr-upload#timeout-30-1000); see its
documentation page for details. Set to `0` to disable this check.

#### `limit`

Limit the amount of uploads going on at the same time (`number`, default: `5`).

Setting this to `0` means no limit on concurrent uploads, but we recommend a
value between `5` and `20`.

#### `getResponseData(responseText, response)`

:::note

This is an advanced option intended for use with _almost_ S3-compatible storage
solutions.

:::

Customize response handling once an upload is completed. This passes the
function through to @uppy/xhr-upload, see its
[documentation](https://uppy.io/docs/xhr-upload/#getResponseData-responseText-response)
for API details.

This option is useful when uploading to an S3-like service that doesn’t reply
with an XML document, but with something else such as JSON.

#### `locale: {}`

```js
export default {
	strings: {
		timedOut: 'Upload stalled for %{seconds} seconds, aborting.',
	},
};
```

## Frequently Asked Questions

### How can I generate a presigned URL server-side?

The `getUploadParameters` function can return a `Promise`, so upload parameters
can be prepared server-side. That way, no private keys to the S3 bucket need to
be shared on the client. For example, there could be a PHP server endpoint that
prepares a presigned URL for a file:

```js
uppy.use(AwsS3, {
	getUploadParameters(file) {
		// Send a request to our PHP signing endpoint.
		return fetch('/s3-sign.php', {
			method: 'post',
			// Send and receive JSON.
			headers: {
				accept: 'application/json',
				'content-type': 'application/json',
			},
			body: JSON.stringify({
				filename: file.name,
				contentType: file.type,
			}),
		})
			.then((response) => {
				// Parse the JSON response.
				return response.json();
			})
			.then((data) => {
				// Return an object in the correct shape.
				return {
					method: data.method,
					url: data.url,
					fields: data.fields,
					// Provide content type header required by S3
					headers: {
						'Content-Type': file.type,
					},
				};
			});
	},
});
```

See either the
[aws-nodejs](https://github.com/transloadit/uppy/tree/HEAD/examples/aws-nodejs)
or [aws-php](https://github.com/transloadit/uppy/tree/HEAD/examples/aws-php)
examples in the uppy repository for a demonstration of how to implement handling
of presigned URLs on both the server-side and client-side.

### How can I retrieve the presigned parameters of the uploaded file?

Once the file is uploaded, it’s possible to retrieve the parameters that were
generated in `getUploadParameters(file)` via the `file.meta` field:

```js
uppy.on('upload-success', (file, data) => {
	const s3Key = file.meta['key']; // the S3 object key of the uploaded file
});
```

[companion docs]: /docs/companion