Registry / aws / amplify-storage-simulator

amplify-storage-simulator

library1.11.8jsnpmunverified

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.

aws testing

npm install amplify-storage-simulator

github ↗package ↗

INSTALL

IMPORT

SIG · AMPLIFY-STORAGE-SI

amplify-storage-simulator

awsjavascriptv1.11.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AmplifyStorageSimulator

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

✗ import AmplifyStorageSimulator from 'amplify-storage-simulator'

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

AmplifyStorageSimulatorServer

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

✗ const { AmplifyStorageSimulatorServer } = require('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+.

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();

Debug

Known issues

deprecatedThe 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" }]'

affects: >=1.8.0

gotchaThe 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.

affects: *

gotchaObject 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.

affects: *

breakingIn 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()

affects: >=1.6.0

gotchaThe simulator does not support multipart upload operations (CreateMultipartUpload, UploadPart, etc.).

fix

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

affects: *

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

fix

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

affects: >=1.10.0

gotchaThe 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.

affects: *

Errors

Common errors & fixes

Error: connect ECONNREFUSED ::1:20005

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.

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

CommonJS require used instead of ESM import.

fix

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

Error: bucket 'my-bucket' is not configured

Bucket not declared in options or name mismatch.

fix

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

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

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

fix

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

Upgrade

Version history

1.11.8latest on npm

Audit

Dependencies

@aws-amplify/amplify-cli-corerequiredUsed for shared configuration and path resolution

uuidrequiredGenerates unique ETags for uploaded objects

Agent activity

36 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/aws-amplify/amplify-cli ↗

packagehttps://www.npmjs.com/package/amplify-storage-simulator ↗