Skip to content
Abdulrahman Magdy

Projects

nestjs-sqs-transporter

A NestJS microservice transporter for AWS SQS, with S3 offloading for large messages, FIFO queues, and OpenTelemetry tracing.

Year
2026
Role
Author and maintainer
Stack
TypeScript, NestJS, AWS SQS, AWS S3, OpenTelemetry

Visit live siteView source

The problem

NestJS has a clean model for message-driven services: handlers decorated with @EventPattern, and a ClientProxy to publish. SQS is a common queue on AWS, but using it from NestJS usually means a separate consumer library with its own conventions, plus hand-written code for the cases that matter in production, like payloads over the 256 KB SQS limit.

What it does

The package is a custom transporter, so SQS works like any other NestJS transport:

main.ts
app.connectMicroservice<MicroserviceOptions>({
  strategy: new ServerSqs({
    sqs: new SQSClient({ region: 'us-east-1' }),
    consumerOptions: { queueUrl: process.env.SQS_QUEUE_URL },
  }),
});
  • Official NestJS patterns. Handlers use @EventPattern, and producers use a ClientProxy.
  • Large messages. Payloads over 256 KB are offloaded to S3 automatically.
  • FIFO queues. messageGroupId and deduplicationId can be computed per message.
  • Observability. Optional OpenTelemetry tracing and metrics.
  • Testing. MockServerSqs and MockClientSqs let you unit test handlers without AWS. The package is tested against AWS SQS and LocalStack.

Decisions and trade-offs

Building on the framework’s transporter interface keeps application code portable between transports, at the cost of following NestJS’s fire-and-forget event model rather than exposing every SQS feature directly. A custom patternKey covers the main escape hatch: routing messages produced by systems that don’t speak NestJS.