Skip to content

SnsTopic

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

The SnsTopic component lets you add an Amazon SNS Topic to your app.

Create a topic

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

Make it a FIFO topic

You can optionally make it a FIFO topic.

sst.config.ts
new sst.aws.SnsTopic("MyTopic", {
fifo: true
});

Add a subscriber

sst.config.ts
topic.subscribe("MySubscriber", "src/subscriber.handler");

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

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

Once linked, you can publish messages to the topic from your function code.

app/page.tsx
import { Resource } from "sst";
import { SNSClient, PublishCommand } from "@aws-sdk/client-sns";
const sns = new SNSClient({});
await sns.send(new PublishCommand({
TopicArn: Resource.MyTopic.arn,
Message: "Hello from Next.js!"
}));

Constructor

new SnsTopic(name, args?, opts?)

Parameters

SnsTopicArgs

fifo?

Type Input<boolean>

Default false

FIFO (First-In-First-Out) topics are designed to provide strict message ordering.

{
fifo: true
}

transform?

Type Object

Transform how this component creates its underlying resources.

transform.topic?

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

Transform the SNS Topic resource.

Properties

arn

Type Output<string>

The ARN of the SNS Topic.

name

Type Output<string>

The name of the SNS Topic.

nodes

Type Object

The underlying resources this component creates.

nodes.topic

Type Topic

The Amazon SNS Topic.

SDK

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


This is accessible through the Resource object in the SDK.

  • arn string

    The ARN of the SNS Topic.

Methods

subscribe

subscribe(name, subscriber, args?)

Parameters

  • name string

    The name of the subscriber.
  • subscriber Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

    The function that’ll be notified.
  • args? SnsTopicSubscriberArgs

    Configure the subscription.

Returns Output<SnsTopicLambdaSubscriber>

Subscribe to this SNS Topic.

sst.config.ts
topic.subscribe("MySubscriber", "src/subscriber.handler");

Add a filter to the subscription.

sst.config.ts
topic.subscribe("MySubscriber", "src/subscriber.handler", {
filter: {
price_usd: [{numeric: [">=", 100]}]
}
});

Customize the subscriber function.

sst.config.ts
topic.subscribe("MySubscriber", {
handler: "src/subscriber.handler",
timeout: "60 seconds"
});

Or pass in the ARN of an existing Lambda function.

sst.config.ts
topic.subscribe("MySubscriber", "arn:aws:lambda:us-east-1:123456789012:function:my-function");

subscribeQueue

subscribeQueue(name, queue, args?)

Parameters

  • name string

    The name of the subscriber.
  • queue Input<string | Queue>

    The ARN of the queue or Queue component that’ll be notified.
  • args? SnsTopicSubscriberArgs

    Configure the subscription.

Returns Output<SnsTopicQueueSubscriber>

Subscribe to this SNS Topic with an SQS Queue.

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

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

You can subscribe to this topic with it.

sst.config.ts
topic.subscribeQueue("MySubscriber", queue.arn);

Add a filter to the subscription.

sst.config.ts
topic.subscribeQueue("MySubscriber", queue.arn, {
filter: {
price_usd: [{numeric: [">=", 100]}]
}
});

static subscribe

SnsTopic.subscribe(name, topicArn, subscriber, args?)

Parameters

  • name string

    The name of the subscriber.
  • topicArn Input<string>

    The ARN of the SNS Topic to subscribe to.
  • subscriber Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

    The function that’ll be notified.
  • args? SnsTopicSubscriberArgs

    Configure the subscription.

Returns Output<SnsTopicLambdaSubscriber>

Subscribe to an SNS Topic that was not created in your app.

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

sst.config.ts
const topicArn = "arn:aws:sns:us-east-1:123456789012:MyTopic";

You can subscribe to it by passing in the ARN.

sst.config.ts
sst.aws.SnsTopic.subscribe("MySubscriber", topicArn, "src/subscriber.handler");

Add a filter to the subscription.

sst.config.ts
sst.aws.SnsTopic.subscribe("MySubscriber", topicArn, "src/subscriber.handler", {
filter: {
price_usd: [{numeric: [">=", 100]}]
}
});

Customize the subscriber function.

sst.config.ts
sst.aws.SnsTopic.subscribe("MySubscriber", topicArn, {
handler: "src/subscriber.handler",
timeout: "60 seconds"
});

static subscribeQueue

SnsTopic.subscribeQueue(name, topicArn, queue, args?)

Parameters

  • name string

    The name of the subscriber.
  • topicArn Input<string>

    The ARN of the SNS Topic to subscribe to.
  • queue Input<string | Queue>

    The ARN of the queue or Queue component that’ll be notified.
  • args? SnsTopicSubscriberArgs

    Configure the subscription.

Returns Output<SnsTopicQueueSubscriber>

Subscribe to an existing SNS Topic with a previously created SQS Queue.

For example, let’s say you have an existing SNS Topic and SQS Queue with the following ARNs.

sst.config.ts
const topicArn = "arn:aws:sns:us-east-1:123456789012:MyTopic";
const queueArn = "arn:aws:sqs:us-east-1:123456789012:MyQueue";

You can subscribe to the topic with the queue.

sst.config.ts
sst.aws.SnsTopic.subscribeQueue("MySubscriber", topicArn, queueArn);

Add a filter to the subscription.

sst.config.ts
sst.aws.SnsTopic.subscribeQueue("MySubscriber", topicArn, queueArn, {
filter: {
price_usd: [{numeric: [">=", 100]}]
}
});

SnsTopicSubscriberArgs

filter?

Type Input<Record<string, any>>

Filter the messages that’ll be processed by the subscriber.

If any single property in the filter doesn’t match an attribute assigned to the message, then the policy rejects the message.

For example, if your SNS Topic message contains this in a JSON format.

{
store: "example_corp",
event: "order-placed",
customer_interests: [
"soccer",
"rugby",
"hockey"
],
price_usd: 210.75
}

Then this filter policy accepts the message.

{
filter: {
store: ["example_corp"],
event: [{"anything-but": "order_cancelled"}],
customer_interests: [
"rugby",
"football",
"baseball"
],
price_usd: [{numeric: [">=", 100]}]
}
}

transform?

Type Object

Transform how this subscription creates its underlying resources.

transform.subscription?

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

Transform the SNS Topic Subscription resource.