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