Skip to content
Ion
Docs Console Examples

Queue

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

The Queue component lets you add a serverless queue to your app. It uses Amazon SQS.

Create a queue

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

Make it a FIFO queue

You can optionally make it a FIFO queue.

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

Add a subscriber

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

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

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

Once linked, you can send messages to the queue from your function code.

app/page.tsx
import { Resource } from "sst";
import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs";


const sqs = new SQSClient({});


await sqs.send(new SendMessageCommand({
  QueueUrl: Resource.MyQueue.url,
  MessageBody: "Hello from Next.js!"
}));

Constructor

new Queue(name, args?, opts?)

Parameters

QueueArgs

dlq?

Type Input<string | Object>

Optionally add a dead-letter queue or DLQ for this queue.

A dead-letter queue is used to store messages that can’t be processed successfully by the subscriber function after the retry limit is reached.

This takes either the ARN of the dead-letter queue or an object to configure how the dead-letter queue is used.

For example, here’s how you can create a dead-letter queue and link it to the main queue.

sst.config.ts
const deadLetterQueue = new sst.aws.Queue("MyDLQ");


new sst.aws.Queue("MyQueue", {
  dlq: deadLetterQueue.arn,
});

By default, the main queue will retry processing the message 3 times before sending it to the dead-letter queue. You can customize this.

sst.config.ts
new sst.aws.Queue("MyQueue", {
  dlq: {
    retry: 5,
    queue: deadLetterQueue.arn,
  }
});

dlq.queue

Type Input<string>

The ARN of the dead-letter queue.

dlq.retry

Type Input<number>

Default 3

The number of times the main queue will retry the message before sending it to the dead-letter queue.

fifo?

Type Input<boolean>

Default false

FIFO or first-in-first-out queues are designed to guarantee that messages are processed exactly once and in the order that they are sent.

{
  fifo: true
}

transform?

Type Object

Transform how this component creates its underlying resources.

transform.queue?

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

Transform the SQS Queue resource.

visibilityTimeout?

Type Input<“${number} minute” | “${number} minutes” | “${number} hour” | “${number} hours” | “${number} second” | “${number} seconds”>

Default “30 seconds”

Visibility timeout is a period of time during which a message is temporarily invisible to other consumers after a consumer has retrieved it from the queue. This mechanism prevents other consumers from processing the same message concurrently, ensuring that each message is processed only once.

This timeout can range from 0 seconds to 12 hours.

{
  visibilityTimeout: "1 hour"
}

Properties

arn

Type Output<string>

The ARN of the SQS Queue.

nodes

Type Object

The underlying resources this component creates.

nodes.queue

Type Queue

The Amazon SQS Queue.

url

Type Output<string>

The SQS Queue URL.

SDK

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

This is accessible through the Resource object in the SDK.

  • url string

    The SQS Queue URL.

Methods

subscribe

subscribe(subscriber, args?, opts?)

Parameters

Returns Output<QueueLambdaSubscriber>

Subscribe to this queue.

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

Add a filter to the subscription.

sst.config.ts
queue.subscribe("src/subscriber.handler", {
  filters: [
    {
      body: {
        RequestCode: ["BBBB"]
      }
    }
  ]
});

Customize the subscriber function.

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

static subscribe

Queue.subscribe(queueArn, subscriber, args?, opts?)

Parameters

Returns Output<QueueLambdaSubscriber>

Subscribe to an SQS Queue that was not created in your app.

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

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

You can subscribe to it by passing in the ARN.

sst.config.ts
sst.aws.Queue.subscribe(queueArn, "src/subscriber.handler");

Add a filter to the subscription.

sst.config.ts
sst.aws.Queue.subscribe(queueArn, "src/subscriber.handler", {
  filters: [
    {
      body: {
        RequestCode: ["BBBB"]
      }
    }
  ]
});

Customize the subscriber function.

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

QueueSubscriberArgs

filters?

Type Input<Input<Record<string, any>>[]>

Filter the records that’ll be processed by the subscriber function.

You can pass in up to 5 different filter policies. These will logically ORed together. Meaning that if any single policy matches, the record will be processed. Learn more about the filter rule syntax.

For example, if you Queue contains records in this JSON format.

{
  RecordNumber: 0000,
  RequestCode: "AAAA",
  TimeStamp: "yyyy-mm-ddThh:mm:ss"
}

To process only those records where the RequestCode is BBBB.

{
  filters: [
    {
      body: {
        RequestCode: ["BBBB"]
      }
    }
  ]
}

And to process only those records where RecordNumber greater than 9999.

{
  filters: [
    {
      body: {
        RecordNumber: [{ numeric: [ ">", 9999 ] }]
      }
    }
  ]
}

transform?

Type Object

Transform how this component creates its underlying resources.

transform.eventSourceMapping?

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

Transform the Lambda Event Source Mapping resource.