Local AWS SQS

Run AWS SQS locally without dependency.
Supports both AWS Query and JSON (x-amz-json-1.0) protocols.

Install

npm i local-aws-sqs --save-dev
# yarn add -D local-aws-sqs

Usage

import { createSqsServer } from "local-aws-sqs";
// const { createSqsServer } = require("local-aws-sqs");

const server = await createSqsServer({ port: 5432 });

Options

name	default	description
port		port for NodeJS http createServer
hostname	localhost	hostname for NodeJS http createServer
baseUrl	/	base url to prefix Queue URLs
region	us-east-1	(cosmetic) AWS Region used in Queue ARN
accountId	123456789012	(cosmetic) AWS Account Id used in Queue ARN and URL
validateDlqDestination	true	DLQ defined in RedrivePolicy must exist.
emulateQueueCreationLifecycle	true	AWS behaviour: If you delete a queue, you must wait at least 60 seconds before creating a queue with the same name.
emulateLazyQueues	false	AWS behaviour: After you create a queue, you must wait at least one second after the queue is created to be able to use the queue.
queues	[ ]	an array of Queue to be created when the server starts. Same Schema as CreateQueueCommandInput

Integration

AWS provides a feature called Service-specific endpoints which allows you to redirect all you AWS SQS API requests to a specific endoint.

If your app already runs with some AWS Credentials and Region, you can simply set the AWS_ENDPOINT_URL_SQS env variable to redirect all SQS requests to Local AWS SQS.

AWS_ENDPOINT_URL_SQS=http://localhost:5432 node ./myApp.js

Setup based on AWS Profile: inside ~/.aws/config file

[profile local]
aws_access_key_id=fake
aws_secret_access_key=fake
region=us-east-1
services = local-services

[services local-services]
sqs =
  endpoint_url = http://localhost:5432

Using with AWS SDK

with AWS_PROFILE=local (or AWS_ENDPOINT_URL_SQS) env variable

import { SQSClient, CreateQueueCommand } from "@aws-sdk/client-sqs";

const client = new SQSClient({});

const cmd = new CreateQueueCommand({ QueueName: "MyFirstLocalQueue" });

const res = await client.send(cmd);

console.log(res.QueueUrl);
// http://localhost:5432/123456789012/MyFirstLocalQueue

without AWS_PROFILE=local

import { SQSClient } from "@aws-sdk/client-sqs";

const client = new SQSClient({
  region: "us-east-1",
  endpoint: `http://localhost:5432`,
  credentials: {
    accessKeyId: "fake",
    secretAccessKey: "fake",
  },
});

Using with AWS CLI

with AWS_PROFILE=local or aws --profile local

aws --profile local sqs create-queue --queue-name MyFirstLocalQueue

# output
{
    "QueueUrl": "http://localhost:5432/123456789012/MyFirstLocalQueue"
}

without AWS_PROFILE

aws --region us-east-1 --endpoint-url http://localhost:5432 sqs create-queue --queue-name MyFirstLocalQueue

# output
{
    "QueueUrl": "http://localhost:5432/123456789012/MyFirstLocalQueue"
}

Using with Terraform

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.46.0"
    }

  }
}

# Without AWS_PROFILE

# provider "aws" {
#   region                      = "us-east-1"
#   access_key                  = "fake"
#   secret_key                  = "fake"
#   skip_credentials_validation = true
#   skip_requesting_account_id  = true
#   endpoints {
#     sqs = "http://localhost:5432"
#   }
# }


# With AWS Profile

provider "aws" {
  profile = "local"
  skip_credentials_validation = true
  skip_requesting_account_id  = true
}


resource "aws_sqs_queue" "queue" {
  name = "MyFirstLocalQueue"
}

Using with Jest

jest.config.js

/** @type {import('jest').Config} */
const config = {
  globalSetup: "./setup-sqs.js",
  globalTeardown: "./teardown-sqs.js",
};

module.exports = config;

setup-sqs.js

// @ts-check
const { createSqsServer } = require("local-aws-sqs");

module.exports = async () => {
  global.__SQS_SERVER__ = await createSqsServer({ port: 5432, queues: [{ QueueName: "MyFirstLocalQueue" }] });
};

teardown-sqs.js

module.exports = async () => {
  global.__SQS_SERVER__.close();
};

Using with Vitest

vitest.config.ts

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    globalSetup: ["sqs.config.ts"],
  },
});

sqs.config.ts

import { createSqsServer } from "local-aws-sqs";
import type { Server } from "http";

let server: Server;

export const setup = async () => {
  server = await createSqsServer({ port: 5432, queues: [{ QueueName: "MyFirstLocalQueue" }] });
};

export const teardown = () => {
  server.close();
};

Supported Commands

command name	support
AddPermission	✅
CancelMessageMoveTask	✅
ChangeMessageVisibility	✅
ChangeMessageVisibilityBatch	✅
CreateQueue	✅
DeleteMessage	✅
DeleteMessageBatch	✅
DeleteQueue	✅
GetQueueAttributes	✅
GetQueueUrl	✅
ListDeadLetterSourceQueues	✅
ListMessageMoveTasks	✅
ListQueues	✅
ListQueueTags	✅
PurgeQueue	✅
ReceiveMessage	✅
RemovePermission	✅
SendMessage	✅
SendMessageBatch	✅
SetQueueAttributes	✅
StartMessageMoveTask	✅
TagQueue	✅
UntagQueue	✅

Notes

As this tool is only for local development some behiavours are itentionally ignored.

No permission checks when calling the API (Access Key, Policy, KMS, etc.)
Bad region dont throw error

Inqnuam / local-aws-sqs