Skip to content

Localstack

Install

1
npm install @testcontainers/localstack --save-dev

Examples

These examples use the following libraries:

Choose an image from the container registry and substitute IMAGE.

Auth token requirement for latest images (from March 23, 2026)

Starting from March 23, 2026, localstack/localstack:latest requires a LOCALSTACK_AUTH_TOKEN environment variable. If you are using the latest tag, or a LocalStack image version that includes this change, you must provide your auth token:

Ensure LOCALSTACK_AUTH_TOKEN is set in your environment before starting the container.

1
2
3
const container = await new LocalstackContainer("localstack/localstack:latest")
  .withEnvironment({ LOCALSTACK_AUTH_TOKEN: process.env.LOCALSTACK_AUTH_TOKEN })
  .start();

You can obtain your auth token from localstack.cloud. Users pinning to a specific version prior to this change are not affected.

Create a S3 bucket

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
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);