Bucket

The Bucket component lets you add an AWS S3 Bucket to your app.

Minimal example

sst.config.ts

const bucket = new sst.aws.Bucket("MyBucket");

Public read access

Enable public read access for all the files in the bucket. Useful for hosting public files.

sst.config.ts

new sst.aws.Bucket("MyBucket", {
  public: true
});

Add a subscriber

sst.config.ts

bucket.subscribe("src/subscriber.handler");

Link the bucket to a resource

You can link the bucket to other resources, like a function or your Next.js app.

sst.config.ts

new sst.aws.Nextjs("MyWeb", {
  link: [bucket]
});

Once linked, you can generate a pre-signed URL to upload files in your app.

app/page.tsx

import { Resource } from "sst";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const command = new PutObjectCommand({
   Key: "file.txt",
   Bucket: Resource.MyBucket.name
 });
 await getSignedUrl(new S3Client({}), command);

---

Constructor

new Bucket(name, args?, opts?)

Parameters

• name string

• args? BucketArgs

• opts? ComponentResourceOptions

BucketArgs

cors?

Type Input<false | Object>

• allowHeaders?

• allowMethods?

• allowOrigins?

• exposeHeaders?

• maxAge?

Default true

The CORS configuration for the bucket. Defaults to true, which is the same as:

{
  cors: {
    allowHeaders: ["*"],
    allowOrigins: ["*"],
    allowMethods: ["DELETE", "GET", "HEAD", "POST", "PUT"],
    exposeHeaders: [],
    maxAge: "0 seconds"
  }
}

cors.allowHeaders?

Type Input<Input<string>[]>

Default [”*“]

The HTTP headers that origins can include in requests to the bucket.

{
  cors: {
    allowHeaders: ["date", "keep-alive", "x-custom-header"]
  }
}

cors.allowMethods?

Type Input<Input<“DELETE” | “GET” | “HEAD” | “POST” | “PUT”>[]>

Default [“DELETE” | “GET” | “HEAD” | “POST” | “PUT”]

The HTTP methods that are allowed when calling the bucket.

{
  cors: {
    allowMethods: ["GET", "POST", "DELETE"]
  }
}

cors.allowOrigins?

Type Input<Input<string>[]>

Default [”*“]

The origins that can access the bucket.

{
  cors: {
    allowOrigins: ["https://www.example.com", "http://localhost:60905"]
  }
}

Or the wildcard for all origins.

{
  cors: {
    allowOrigins: ["*"]
  }
}

cors.exposeHeaders?

Type Input<Input<string>[]>

Default []

The HTTP headers you want to expose to an origin that calls the bucket.

{
  cors: {
    exposeHeaders: ["date", "keep-alive", "x-custom-header"]
  }
}

cors.maxAge?

Type Input<“${number} minute” | “${number} minutes” | “${number} hour” | “${number} hours” | “${number} second” | “${number} seconds” | “${number} day” | “${number} days”>

Default “0 seconds”

The maximum amount of time the browser can cache results of a preflight request. By default the browser doesn’t cache the results. The maximum value is 86400 seconds or 1 day.

{
  cors: {
    maxAge: "1 day"
  }
}

public?

Type Input<boolean>

Default false

Enable public read access for all the files in the bucket.

Tip

You don’t need to enable this if you’re using CloudFront to serve files from the bucket.

Should only be turned on if you want to host public files directly from the bucket.

{
  public: true
}

transform?

Type Object

• bucket?

• cors?

• policy?

• publicAccessBlock?

Transform how this component creates its underlying resources.

transform.bucket?

Type BucketV2Args | (args: BucketV2Args, opts: ComponentResourceOptions, name: string) => void

Transform the S3 Bucket resource.

transform.cors?

Type BucketCorsConfigurationV2Args | (args: BucketCorsConfigurationV2Args, opts: ComponentResourceOptions, name: string) => void

Transform the S3 Bucket CORS configuration resource.

transform.policy?

Type BucketPolicyArgs | (args: BucketPolicyArgs, opts: ComponentResourceOptions, name: string) => void

Transform the S3 Bucket Policy resource.

transform.publicAccessBlock?

Type BucketPublicAccessBlockArgs | (args: BucketPublicAccessBlockArgs, opts: ComponentResourceOptions, name: string) => void

Transform the public access block resource that’s attached to the Bucket.

Properties

arn

Type Output<string>

The ARN of the S3 Bucket.

domain

Type Output<string>

The domain name of the bucket

name

Type Output<string>

The generated name of the S3 Bucket.

nodes

Type Object

• bucket

The underlying resources this component creates.

nodes.bucket

Type Output<BucketV2>

The Amazon S3 bucket.

SDK

Use the SDK in your runtime to interact with your infrastructure.

---

Links

This is accessible through the Resource object in the SDK.

• name string

  The generated name of the S3 Bucket.

Methods

subscribe

subscribe(subscriber, args?)

Parameters

• subscriber string | FunctionArgs

  The function that’ll be notified.

• args? BucketSubscriberArgs

  Configure the subscription.

Returns Output<BucketLambdaSubscriber>

Subscribe to events from this bucket.

sst.config.ts

bucket.subscribe("src/subscriber.handler");

Subscribe to specific S3 events. The link ensures the subscriber can access the bucket.

sst.config.ts

bucket.subscribe({
  handler: "src/subscriber.handler",
  link: [bucket]
}, {
  events: ["s3:ObjectCreated:*", "s3:ObjectRemoved:*"]
});

Subscribe to specific S3 events from a specific folder.

sst.config.ts

bucket.subscribe("src/subscriber.handler", {
  filterPrefix: "images/",
  events: ["s3:ObjectCreated:*", "s3:ObjectRemoved:*"]
});

Customize the subscriber function.

sst.config.ts

bucket.subscribe({
  handler: "src/subscriber.handler",
  timeout: "60 seconds",
});

static get

Bucket.get(name, bucketName)

Parameters

• name string

  The name of the component.

• bucketName string

  The name of the S3 Bucket.

Returns Bucket

Reference an existing bucket with the given bucket name. This is useful when you created a bucket in one stage and you want to reference it in another stage.

Imagine you created a bucket in the dev stage. And in your perosonal stage, ie. frank, instead of creating a new bucket, you want to reuse the same bucket from dev.

sst.config.ts

const bucket = $app.stage === "frank"
  ? sst.aws.Bucket.get("MyBucket", "app-dev-mybucket-12345678")
  : new sst.aws.Bucket("MyBucket");

Here app-dev-mybucket-12345678 is the autogenerated bucket name for the bucket created in the dev stage.

static subscribe

Bucket.subscribe(bucketArn, subscriber, args?)

Parameters

• bucketArn Input<string>

  The ARN of the S3 bucket to subscribe to.

• subscriber string | FunctionArgs

  The function that’ll be notified.

• args? BucketSubscriberArgs

  Configure the subscription.

Returns Output<BucketLambdaSubscriber>

Subscribe to events of an S3 bucket that was not created in your app.

For example, let’s say you have an existing S3 bucket with the following ARN.

sst.config.ts

const bucketArn = "arn:aws:s3:::my-bucket";

You can subscribe to it by passing in the ARN.

sst.config.ts

sst.aws.Bucket.subscribe(bucketArn, "src/subscriber.handler");

Subscribe to specific S3 events.

sst.config.ts

sst.aws.Bucket.subscribe(bucketArn, "src/subscriber.handler", {
  events: ["s3:ObjectCreated:*", "s3:ObjectRemoved:*"]
});

Subscribe to specific S3 events from a specific folder.

sst.config.ts

sst.aws.Bucket.subscribe(bucketArn, "src/subscriber.handler", {
  filterPrefix: "images/",
  events: ["s3:ObjectCreated:*", "s3:ObjectRemoved:*"]
});

Customize the subscriber function.

sst.config.ts

sst.aws.Bucket.subscribe(bucketArn, {
  handler: "src/subscriber.handler",
  timeout: "60 seconds",
});

BucketSubscriberArgs

events?

Type Input<Input<“s3:ObjectCreated:*” | “s3:ObjectCreated:Put” | “s3:ObjectCreated:Post” | “s3:ObjectCreated:Copy” | “s3:ObjectCreated:CompleteMultipartUpload” | “s3:ObjectRemoved:*” | “s3:ObjectRemoved:Delete” | “s3:ObjectRemoved:DeleteMarkerCreated” | “s3:ObjectRestore:*” | “s3:ObjectRestore:Post” | “s3:ObjectRestore:Completed” | “s3:ObjectRestore:Delete” | “s3:ReducedRedundancyLostObject” | “s3:Replication:*” | “s3:Replication:OperationFailedReplication” | “s3:Replication:OperationMissedThreshold” | “s3:Replication:OperationReplicatedAfterThreshold” | “s3:Replication:OperationNotTracked” | “s3:LifecycleExpiration:*” | “s3:LifecycleExpiration:Delete” | “s3:LifecycleExpiration:DeleteMarkerCreated” | “s3:LifecycleTransition” | “s3:IntelligentTiering” | “s3:ObjectTagging:*” | “s3:ObjectTagging:Put” | “s3:ObjectTagging:Delete” | “s3:ObjectAcl:Put”>[]>

Default All S3 events

A list of S3 event types that’ll trigger the notification.

{
  events: ["s3:ObjectCreated:*", "s3:ObjectRemoved:*"]
}

filterPrefix?

Type Input<string>

An S3 object key prefix that will trigger the notification.

To filter for all the objects in the images/ folder.

{
  filterPrefix: "images/"
}

filterSuffix?

Type Input<string>

An S3 object key suffix that will trigger the notification.

To filter for all the objects with the .jpg suffix.

{
 filterSuffix: ".jpg"
}

transform?

Type Object

• notification?

Transform how this notification creates its underlying resources.

transform.notification?

Type BucketNotificationArgs | (args: BucketNotificationArgs, opts: ComponentResourceOptions, name: string) => void

Transform the S3 Bucket Notification resource.