Skip to content

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} 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"
}
}

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 BucketNotificationsOutput

Subscribe to event notifications from this bucket.

Notify a function.

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

Notify on specific S3 events.

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

Notify on specific S3 events from a specific folder.

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

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

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

You can notify it by passing in the queue.

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

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

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

You can notify it by passing in the topic.

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

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 the notification.

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

notifications[].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/"
}

notifications[].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"
}

notifications[].function?

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

The function that’ll be notified.

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

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

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

Or pass in the ARN of an existing Lambda function.

sst.config.ts
{
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 = sst.aws.Queue("MyQueue");

You can subscribe to this bucket with it.

sst.config.ts
{
name: "MySubscriber",
queue: myQueue,
}

Or pass in the ARN of an existing SQS queue.

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

notifications[].topic?

Type Input<string | SnsTopic>

The topic that’ll be notified.

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

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

You can subscribe to this bucket with it.

sst.config.ts
{
name: "MySubscriber",
topic: myTopic,
}

Or pass in the ARN of an existing SNS topic.

sst.config.ts
{
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.

BucketNotificationsOutput

nodes

Type Object

The underlying resources this function creates.

nodes.functions

Type Output<Function[]>

The functions that will be notified.

nodes.notification

Type BucketNotification

The notification resource that’s created.