SnsTopic

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

Note

The difference between an SnsTopic and a Queue is that with a topic you can deliver messages to multiple subscribers.

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");

Link the topic to a resource

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

• 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.

Caution

Changing a standard topic to a FIFO topic or the other way around will result in the destruction and recreation of the topic.

{
  fifo: true
}

transform?

Type Object

• topic?

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

• topic

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.

---

Links

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 get

SnsTopic.get(name, topicArn, opts?)

Parameters

• name string

  The name of the component.

• topicArn Input<string>

  The ARN of the existing SNS Topic.

• opts? ComponentResourceOptions

Returns SnsTopic

Reference an existing SNS topic with its topic ARN. This is useful when you create a topic in one stage and want to share it in another stage. It avoids having to create a new topic in the other stage.

Tip

You can use the static get method to share SNS topics across stages.

Imagine you create a topic in the dev stage. And in your personal stage frank, instead of creating a new topic, you want to share the topic from dev.

sst.config.ts

const topic = $app.stage === "frank"
  ? sst.aws.SnsTopic.get("MyTopic", "arn:aws:sns:us-east-1:123456789012:MyTopic")
  : new sst.aws.SnsTopic("MyTopic");

Here arn:aws:sns:us-east-1:123456789012:MyTopic is the ARN of the topic created in the dev stage. You can find this by outputting the topic ARN in the dev stage.

sst.config.ts

return topic.arn;

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.

Tip

Learn more about subscription filter policies.

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

Transform the SNS Topic Subscription resource.