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

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

Make it a FIFO topic

You can optionally make it a FIFO topic.

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

Add a subscriber

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

Link the topic to a resource

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

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

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

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

name string
args? SnsTopicArgs
opts? ComponentResourceOptions

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

topic?

Transform how this component creates its underlying resources.

transform.topic?

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

topic

The underlying resources this component creates.

nodes.topic

Type Topic

The Amazon SNS topic.

SDK

The following are accessible through the SDK at runtime.

arn

Type string

The ARN of the SNS topic.

Methods

subscribe(subscriber, args?)

Parameters

subscriber string | FunctionArgs
The function that’ll be notified.
args? SnsTopicSubscriberArgs
Configure the subscription.

Returns Output<SnsTopicLambdaSubscriber>

Subscribe to this SNS topic.

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

Add a filter to the subscription.

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

Customize the subscriber function.

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

subscribeQueue

subscribeQueue(queueArn, args?)

Parameters

queueArn Input<string>
The ARN of the queue 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.

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

You can subscribe to this topic with it.

topic.subscribeQueue(queue.arn);

Add a filter to the subscription.

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

SnsTopic.subscribe(topicArn, subscriber, args?)

Parameters

topicArn Input<string>
The ARN of the SNS topic to subscribe to.
subscriber string | FunctionArgs
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.

const topicArn = "arn:aws:sns:us-east-1:123456789012:MyTopic";

You can subscribe to it by passing in the ARN.

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

Add a filter to the subscription.

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

Customize the subscriber function.

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

static subscribeQueue

SnsTopic.subscribeQueue(topicArn, queueArn, args?)

Parameters

topicArn Input<string>
The ARN of the SNS topic to subscribe to.
queueArn Input<string>
The ARN of the queue 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.

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.aws.SnsTopic.subscribeQueue(topicArn, queueArn);

Add a filter to the subscription.

sst.aws.SnsTopic.subscribeQueue(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

subscription?

Transform how this subscription creates its underlying resources.

transform.subscription?

Type TopicSubscriptionArgs | (args: TopicSubscriptionArgs => void)

Transform the SNS topic Subscription resource.