Skip to content
Ion
Docs Console Examples

Bucket

Reference doc for the `sst.aws.Bucket` component.

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

Minimal example

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.

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

Add a subscriber

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

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

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

BucketArgs

cors?

Type Input<false | Object>

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} second” | “${number} seconds” | “${number} minute” | “${number} minutes” | “${number} hour” | “${number} hours” | “${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.

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

{
  public: true
}

transform?

Type Object

Transform how this component creates its underlying resources.

transform.bucket?

Type BucketV2Args | (args: BucketV2Args => void)

Transform the S3 Bucket resource.

transform.cors?

Type BucketCorsConfigurationV2Args | (args: BucketCorsConfigurationV2Args => void)

Transform the S3 Bucket CORS configuration resource.

transform.policy?

Type BucketPolicyArgs | (args: BucketPolicyArgs => void)

Transform the S3 Bucket Policy resource.

transform.publicAccessBlock?

Type BucketPublicAccessBlockArgs | (args: BucketPublicAccessBlockArgs => 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

The underlying resources this component creates.

nodes.bucket

Type Output<BucketV2>

The Amazon S3 bucket.

SDK

The following are accessible through the SDK at runtime.

name

Type string

The generated name of the S3 Bucket.

Methods

subscribe

subscribe(subscriber, args?)

Parameters

Returns Output<BucketLambdaSubscriber>

Subscribe to events from this bucket.

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

Subscribe to specific S3 events.

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

Subscribe to specific S3 events from a specific folder.

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

Customize the subscriber function.

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

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.

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

You can subscribe to it by passing in the ARN.

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

Subscribe to specific S3 events.

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

Subscribe to specific S3 events from a specific folder.

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

Customize the subscriber function.

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

The S3 event types that will trigger the notification.

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

filterPrefix?

Type Input<string>

An S3 object key prefix that will trigger the notification.

All the objects in the images/ folder.

{
  filterPrefix: "images/"
}

filterSuffix?

Type Input<string>

An S3 object key suffix that will trigger the notification.

All the objects with the .jpg suffix.

{
 filterSuffix: ".jpg"
}

transform?

Type Object

Transform how this notification creates its underlying resources.

transform.notification?

Type BucketNotificationArgs | (args: BucketNotificationArgs => void)

Transform the S3 Bucket Notification resource.