Amplify Storage Simulator

1.11.8 verified Sat Apr 25 auth: no javascript

Amplify Storage Simulator (v1.11.8) is an S3 API simulator designed for local testing of AWS Amplify projects that use S3 storage. It implements a subset of S3 REST APIs (ListObjects, GetObject, PutObject, DeleteObject, etc.) using a local file system backend, enabling offline development without actual AWS credentials. Part of the AWS Amplify CLI monorepo, it is updated irregularly alongside Amplify CLI releases. Unlike mock AWS services such as localstack or moto, it is lightweight, Amplify-specific, and integrates seamlessly with Amplify's storage category. It ships TypeScript types and is ESM-only. Key differentiators: automatic Amplify resource path mapping, no Docker dependency, and direct integration with Amplify's local mock server.

Common errors

error Error: connect ECONNREFUSED ::1:20005 ↓

cause Simulator not started or wrong port; IPv6 localhost may not be bound.

fix

Ensure sim.start() is called and use 'localhost' (IPv4) or '127.0.0.1' as endpoint.

error TypeError: (0 , _amplifyStorageSimulator.AmplifyStorageSimulator) is not a constructor ↓

cause CommonJS require used instead of ESM import.

fix

Use import statement: import { AmplifyStorageSimulator } from 'amplify-storage-simulator'

error Error: bucket 'my-bucket' is not configured ↓

cause Bucket not declared in options or name mismatch.

fix

Add the bucket to options.buckets array as '{ name: "my-bucket" }'

error TypeError: Cannot read properties of undefined (reading 'port') ↓

cause Using deprecated 'getPort()' on simulator instance that hasn't started.

fix

Access 'sim.port' after start completes, or use 'await sim.start()' first.

Warnings

deprecated The constructor option 'buckets' as an array of strings is deprecated in v1.8+; use array of objects with 'name' property instead. ↓

fix Change 'buckets: ["my-bucket"]' to 'buckets: [{ name: "my-bucket" }]'

gotcha The simulator does not enforce S3 access control policies; all authenticated clients have full access to all buckets. ↓

fix Do not use for security testing; implement your own authorization if needed.

gotcha Object ETags are generated from UUIDs, not MD5 hashes of content. This may break clients that verify ETag integrity. ↓

fix If ETag validation is required, implement custom middleware to override responses.

breaking In v1.6.0, the 'start()' method changed from synchronous to returning a Promise. Calling 'start()' without await may cause issues. ↓

fix Use 'await sim.start()' or chain with .then()

gotcha The simulator does not support multipart upload operations (CreateMultipartUpload, UploadPart, etc.). ↓

fix Fall back to single PutObject calls or use a full S3 emulator.

deprecated The 'getPort()' method is deprecated in v1.10+; use the 'port' property instead. ↓

fix Replace 'sim.getPort()' with 'sim.port'

gotcha The simulator only supports the 'us-east-1' region; other regions are not validated but may cause client-side errors. ↓

fix Always set client region to 'us-east-1' when using the simulator.

Install

npm install amplify-storage-simulator

yarn add amplify-storage-simulator

pnpm add amplify-storage-simulator

Imports

AmplifyStorageSimulator

wrong

import AmplifyStorageSimulator from 'amplify-storage-simulator'

correct

import { AmplifyStorageSimulator } from 'amplify-storage-simulator'

Named export only; default import is not available. ESM-only package.

AmplifyStorageSimulatorServer

wrong

const { AmplifyStorageSimulatorServer } = require('amplify-storage-simulator')

correct

import { AmplifyStorageSimulatorServer } from 'amplify-storage-simulator'

CommonJS require is not supported; the package is ESM-only since v1.0.

StorageSimulatorConfig
```
import type { StorageSimulatorConfig } from 'amplify-storage-simulator'
```
TypeScript type import only; not a runtime value. Available in v1.5+.

Quickstart

Starts the storage simulator, uploads an object using an S3 client, and stops the simulator.

import { AmplifyStorageSimulator } from 'amplify-storage-simulator';

const sim = new AmplifyStorageSimulator({
  port: 20005,
  localDir: '/tmp/storage-sim',
  buckets: ['my-bucket']
});

await sim.start();

// Now you can use any S3-compatible client to interact with the simulator
// e.g., using @aws-sdk/client-s3
import { S3Client, PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';

const client = new S3Client({
  region: 'us-east-1',
  endpoint: `http://localhost:${sim.getPort()}`,
  forcePathStyle: true,
  credentials: {
    accessKeyId: 'fake',
    secretAccessKey: 'fake'
  }
});

await client.send(new PutObjectCommand({
  Bucket: 'my-bucket',
  Key: 'test.txt',
  Body: 'Hello Simulator'
}));

console.log('Object stored!');

await sim.stop();