Localstack - Testcontainers for NodeJS

Install¶

npm install @testcontainers/localstack --save-dev

Examples¶

These examples use the following libraries:

@aws-sdk/client-s3
npm install @aws-sdk/client-s3

Choose an image from the container registry and substitute IMAGE.

Authentication requirements

Starting on March 23, 2026, LocalStack moved to authenticated image releases. Older pinned tags may continue to work without LOCALSTACK_AUTH_TOKEN, but newer releases require it.

Prefer pinning a specific image tag instead of using latest. If the image tag you use requires authentication, pass LOCALSTACK_AUTH_TOKEN when starting the container:

const token = process.env.LOCALSTACK_AUTH_TOKEN;

if (!token) {
  throw new Error("LOCALSTACK_AUTH_TOKEN must be set for authenticated LocalStack images");
}

const container = await new LocalstackContainer("localstack/localstack:IMAGE")
  .withEnvironment({ LOCALSTACK_AUTH_TOKEN: token })
  .start();

Refer to the LocalStack announcement for the current rollout details.

Create a S3 bucket¶

await using container = await new LocalstackContainer(IMAGE).start();

const client = new S3Client({
  endpoint: container.getConnectionUri(),
  forcePathStyle: true,
  region: "us-east-1",
  credentials: {
    secretAccessKey: "test",
    accessKeyId: "test",
  },
});

const input = { Bucket: "testcontainers" };
const command = new CreateBucketCommand(input);

expect((await client.send(command)).$metadata.httpStatusCode).toEqual(200);
expect((await client.send(new HeadBucketCommand(input))).$metadata.httpStatusCode).toEqual(200);