aws-sdk-js-v3

aws-sdk-js-v3

Last updated Oct 26, 2026 You must generate an Access Key before getting started. All examples will utilize access_key_id and access_key_secret variables which represent the Access Key ID and Secret Access Key values you generated.

JavaScript or TypeScript users may continue to use the @aws-sdk/client-s3 ↗︎ npm package as per normal. You must pass in the R2 configuration credentials when instantiating your S3 service client.

Using the SDK in a Worker

The AWS SDK for JavaScript v3 works in Workers with the nodejs_compat compatibility flag enabled. Operations that parse an XML response, such as ListObjectsV2, CopyObject, DeleteObjects, and multipart uploads, can fail with ReferenceError: DOMParser is not defined when Wrangler bundles the SDK. This happens because the browser field of @aws-sdk/xml-builder swaps in a parser that depends on DOMParser, which the Workers runtime does not provide. To work around this, install @aws-sdk/xml-builder as a direct dependency (for example, npm i @aws-sdk/xml-builder) so that it resolves from your project root, then alias the package to its CommonJS build in your Wrangler configuration file:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  // Set this to today's date
  "compatibility_date": "2026-10-27",
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "alias": {
    "@aws-sdk/xml-builder": "@aws-sdk/xml-builder/dist-cjs/index.js"
  }
}

# Set this to today's date
compatibility_date = "2026-10-27"
compatibility_flags = ["nodejs_compat"]

[alias]
"@aws-sdk/xml-builder" = "@aws-sdk/xml-builder/dist-cjs/index.js"

If you only need object reads and writes from a Worker, the R2 Workers API binding does not require the SDK. aws4fetch is a lighter alternative for S3-compatible requests and presigned URLs.

Note

Currently, you cannot use AWS S3-compatible API while developing locally via wrangler dev.

import {
    S3Client,
    ListBucketsCommand,
    ListObjectsV2Command,
    GetObjectCommand,
    PutObjectCommand,
} from "@aws-sdk/client-s3";

const S3 = new S3Client({
    region: "auto", // Required by SDK but not used by R2
    // Provide your Cloudflare account ID
    endpoint: `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`,
    // Retrieve your S3 API credentials for your R2 bucket via API tokens (see: https://developers.cloudflare.com/r2/api/tokens)
    credentials: {
        accessKeyId: ACCESS_KEY_ID,
        secretAccessKey: SECRET_ACCESS_KEY,
    },
});

console.log(await S3.send(new ListBucketsCommand({})));
// {
//     '$metadata': {
//     httpStatusCode: 200,
//         requestId: undefined,
//         extendedRequestId: undefined,
//         cfId: undefined,
//         attempts: 1,
//         totalRetryDelay: 0
// },
//     Buckets: [
//     { Name: 'user-uploads', CreationDate: 2022-04-13T21:23:47.102Z },
//     { Name: 'my-bucket', CreationDate: 2022-05-07T02:46:49.218Z }
//     ],
//     Owner: {
//         DisplayName: '...',
//         ID: '...'
//     }
// }

console.log(await S3.send(new ListObjectsV2Command({ Bucket: "my-bucket" })));
// {
//     '$metadata': {
//       httpStatusCode: 200,
//       requestId: undefined,
//       extendedRequestId: undefined,
//       cfId: undefined,
//       attempts: 1,
//       totalRetryDelay: 0
//     },
//     CommonPrefixes: undefined,
//     Contents: [
//       {
//         Key: 'cat.png',
//         LastModified: 2022-05-07T02:50:45.616Z,
//         ETag: '"c4da329b38467509049e615c11b0c48a"',
//         ChecksumAlgorithm: undefined,
//         Size: 751832,
//         StorageClass: 'STANDARD',
//         Owner: undefined
//       },
//       {
//         Key: 'todos.txt',
//         LastModified: 2022-05-07T21:37:17.150Z,
//         ETag: '"29d911f495d1ba7cb3a4d7d15e63236a"',
//         ChecksumAlgorithm: undefined,
//         Size: 279,
//         StorageClass: 'STANDARD',
//         Owner: undefined
//       }
//     ],
//     ContinuationToken: undefined,
//     Delimiter: undefined,
//     EncodingType: undefined,
//     IsTruncated: false,
//     KeyCount: 8,
//     MaxKeys: 1000,
//     Name: 'my-bucket',
//     NextContinuationToken: undefined,
//     Prefix: undefined,
//     StartAfter: undefined
//   }

Generate presigned URLs

You can also generate presigned links that can be used to share public read or write access to a bucket temporarily.

import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

// Use the expiresIn property to determine how long the presigned link is valid.
console.log(
    await getSignedUrl(
        S3,
        new GetObjectCommand({ Bucket: "my-bucket", Key: "dog.png" }),
        { expiresIn: 3600 },
    ),
);
// You can also create links for operations such as PutObject to allow temporary write access to a specific key.
// Specify ContentType to restrict uploads to a specific file type.
console.log(
    await getSignedUrl(
        S3,
        new PutObjectCommand({
            Bucket: "my-bucket",
            Key: "dog.png",
            ContentType: "image/png",
        }),
        { expiresIn: 3600 },
    ),
);

https://my-bucket.<ACCOUNT_ID>.r2.cloudflarestorage.com/dog.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=<credential>&X-Amz-Date=<timestamp>&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=<signature>&x-id=GetObject
https://my-bucket.<ACCOUNT_ID>.r2.cloudflarestorage.com/dog.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=<credential>&X-Amz-Date=<timestamp>&X-Amz-Expires=3600&X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Signature=<signature>&x-id=PutObject

You can use the link generated by the PutObject example to upload to the specified bucket and key, until the presigned link expires. When using a presigned URL with ContentType, the client must include a matching Content-Type header in the request.

curl -X PUT "https://my-bucket.<ACCOUNT_ID>.r2.cloudflarestorage.com/dog.png?X-Amz-Algorithm=..." \
  -H "Content-Type: image/png" \
  --data-binary @dog.png

Restrict uploads with CORS and Content-Type

When generating presigned URLs for uploads, you can limit abuse and misuse by:

Restricting Content-Type: Specify the allowed content type in the PutObjectCommand. The upload will fail if the client sends a different Content-Type header.
Configuring CORS: Set up CORS rules on your bucket to control which origins can upload files. Configure CORS via the Cloudflare dashboard ↗︎ by adding a JSON policy to your bucket settings:

[
    {
        "AllowedOrigins": ["https://example.com"],
        "AllowedMethods": ["PUT"],
        "AllowedHeaders": ["Content-Type"],
        "ExposeHeaders": ["ETag"],
        "MaxAgeSeconds": 3600
    }
]

Then generate a presigned URL with a Content-Type restriction:

const putUrl = await getSignedUrl(
    S3,
    new PutObjectCommand({
        Bucket: "my-bucket",
        Key: "dog.png",
        ContentType: "image/png",
    }),
    { expiresIn: 3600 },
);

When a client uses this presigned URL, they must:

Make the request from an allowed origin (enforced by CORS)
Include the Content-Type: image/png header (enforced by the signature)

Was this helpful?

YesNo

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/r2/examples/aws/aws-sdk-js-v3/#page","headline":"aws-sdk-js-v3","description":"Configure the AWS SDK for JavaScript v3 to work with Cloudflare R2.","url":"https://developers.cloudflare.com/r2/examples/aws/aws-sdk-js-v3/","inLanguage":"en","image":"https://developers.cloudflare.com/r2/examples/aws/aws-sdk-js-v3/og.png?v=b3b1215c38bb1dfd","dateModified":"2026-10-26","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Configure the AWS SDK for Kotlin to work with Cloudflare R2 object storage. title: aws-sdk-kotlin image: https://developers.cloudflare.com/r2/examples/aws/aws-sdk-kotlin/og.png?v=d7c67471979f2ff4

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/r2/llms.txt
Use this file to discover all available pages before exploring further.

aws-sdk-js-v3

aws-sdk-js-v3

Generate presigned URLs

Restrict uploads with CORS and Content-Type

On this page