Skip to content
SST
Blog Docs Examples
22K
Console

Bucket

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

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", {
  access: "public"
});

Add a subscriber

sst.config.ts
bucket.subscribe("src/subscriber.handler");

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

BucketArgs

access?

Type Input<“public” | “cloudfront”>

Enable public read access for all the files in the bucket. By default, no access is granted.

This adds a statement to the bucket policy that either allows public access or just cloudfront access.

{
  access: "public"
}

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<“GET” | “POST” | “PUT” | “DELETE” | “HEAD”>[]>

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} day” | “${number} second” | “${number} seconds” | “${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"
  }
}

transform?

Type Object

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 false | BucketPublicAccessBlockArgs | (args: BucketPublicAccessBlockArgs, opts: ComponentResourceOptions, name: string) => void

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

Returns false if the public access block resource should not be created.

transform.versioning?

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

Transform the S3 Bucket versioning resource.

versioning?

Type Input<boolean>

Default false

Enable versioning for the bucket.

Bucket versioning enables you to store multiple versions of an object, protecting against accidental deletion or overwriting.

{
  versioning: true
}

Properties

arn

Type Output<string>

The ARN of the S3 Bucket.

domain

Type Output<string>

The domain name of the bucket. Has the format ${bucketName}.s3.amazonaws.com.

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

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

This is accessible through the Resource object in the SDK.

  • name string

    The generated name of the S3 Bucket.

Methods

notify

notify(args)

Parameters

Returns BucketNotification

Subscribe to event notifications from this bucket. You can subscribe to these notifications with a function, a queue, or a topic.

For exmaple, to notify a function:

sst.config.ts
bucket.notify({
  notifications: [
    {
      name: "MySubscriber",
      function: "src/subscriber.handler"
    }
  ]
});

Or let’s say you have a queue.

sst.config.ts
const myQueue = new sst.aws.Queue("MyQueue");

You can notify it by passing in the queue.

sst.config.ts
bucket.notify({
  notifications: [
    {
      name: "MySubscriber",
      queue: myQueue
    }
  ]
});

Or let’s say you have a topic.

sst.config.ts
const myTopic = new sst.aws.SnsTopic("MyTopic");

You can notify it by passing in the topic.

sst.config.ts
bucket.notify({
  notifications: [
    {
      name: "MySubscriber",
      topic: myTopic
    }
  ]
});

You can also set it to only send notifications for specific S3 events.

bucket.notify({
  notifications: [
    {
      name: "MySubscriber",
      function: "src/subscriber.handler",
      events: ["s3:ObjectCreated:*", "s3:ObjectRemoved:*"]
    }
  ]
});

And you can add filters to be only notified from specific files in the bucket.

bucket.notify({
  notifications: [
    {
      name: "MySubscriber",
      function: "src/subscriber.handler",
      filterPrefix: "images/"
    }
  ]
});

static get

Bucket.get(name, bucketName, opts?)

Parameters

  • name string

    The name of the component.

  • bucketName string

    The name of the existing S3 Bucket.

  • opts? ComponentResourceOptions

Returns Bucket

Reference an existing bucket with the given bucket name. This is useful when you create a bucket in one stage and want to share it in another stage. It avoids having to create a new bucket in the other stage.

Imagine you create a bucket in the dev stage. And in your personal stage frank, instead of creating a new bucket, you want to share the 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 auto-generated bucket name for the bucket created in the dev stage. You can find this by outputting the bucket name in the dev stage.

sst.config.ts
return {
  bucket: bucket.name
};

BucketNotificationsArgs

notifications

Type Input<Input<Object>[]>

A list of subscribers that’ll be notified when events happen in the bucket.

notifications[].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 a notification.

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

notifications[].filterPrefix?

Type Input<string>

An S3 object key prefix that will trigger a notification.

To be notified for all the objects in the images/ folder.

{
  filterPrefix: "images/"
}

notifications[].filterSuffix?

Type Input<string>

An S3 object key suffix that will trigger the notification.

To be notified for all the objects with the .jpg suffix.

{
 filterSuffix: ".jpg"
}

notifications[].function?

Type Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

The function that’ll be notified.

{
  name: "MySubscriber",
  function: "src/subscriber.handler"
}

Customize the subscriber function. The link ensures the subscriber can access the bucket through the SDK.

{
  name: "MySubscriber",
  function: {
    handler: "src/subscriber.handler",
    timeout: "60 seconds",
    link: [bucket]
  }
}

Or pass in the ARN of an existing Lambda function.

{
  name: "MySubscriber",
  function: "arn:aws:lambda:us-east-1:123456789012:function:my-function"
}

notifications[].name

Type Input<string>

The name of the subscriber.

notifications[].queue?

Type Input<string | Queue>

The Queue that’ll be notified.

For example, let’s say you have a queue.

sst.config.ts
const myQueue = new sst.aws.Queue("MyQueue");

You can subscribe to this bucket with it.

{
  name: "MySubscriber",
  queue: myQueue
}

Or pass in the ARN of an existing SQS queue.

{
  name: "MySubscriber",
  queue: "arn:aws:sqs:us-east-1:123456789012:my-queue"
}

notifications[].topic?

Type Input<string | SnsTopic>

The SNS topic that’ll be notified.

For example, let’s say you have a topic.

sst.config.ts
const myTopic = new sst.aws.SnsTopic("MyTopic");

You can subscribe to this bucket with it.

{
  name: "MySubscriber",
  topic: myTopic
}

Or pass in the ARN of an existing SNS topic.

{
  name: "MySubscriber",
  topic: "arn:aws:sns:us-east-1:123456789012:my-topic"
}

transform?

Type Object

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.