{"id":18104,"library":"amplify-storage-simulator","title":"Amplify Storage Simulator","description":"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.","status":"active","version":"1.11.8","language":"javascript","source_language":"en","source_url":"https://github.com/aws-amplify/amplify-cli","tags":["javascript","graphql","appsync","aws","typescript"],"install":[{"cmd":"npm install amplify-storage-simulator","lang":"bash","label":"npm"},{"cmd":"yarn add amplify-storage-simulator","lang":"bash","label":"yarn"},{"cmd":"pnpm add amplify-storage-simulator","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for shared configuration and path resolution","package":"@aws-amplify/amplify-cli-core","optional":false},{"reason":"Generates unique ETags for uploaded objects","package":"uuid","optional":false}],"imports":[{"note":"Named export only; default import is not available. ESM-only package.","wrong":"import AmplifyStorageSimulator from 'amplify-storage-simulator'","symbol":"AmplifyStorageSimulator","correct":"import { AmplifyStorageSimulator } from 'amplify-storage-simulator'"},{"note":"CommonJS require is not supported; the package is ESM-only since v1.0.","wrong":"const { AmplifyStorageSimulatorServer } = require('amplify-storage-simulator')","symbol":"AmplifyStorageSimulatorServer","correct":"import { AmplifyStorageSimulatorServer } from 'amplify-storage-simulator'"},{"note":"TypeScript type import only; not a runtime value. Available in v1.5+.","symbol":"StorageSimulatorConfig","correct":"import type { StorageSimulatorConfig } from 'amplify-storage-simulator'"}],"quickstart":{"code":"import { AmplifyStorageSimulator } from 'amplify-storage-simulator';\n\nconst sim = new AmplifyStorageSimulator({\n  port: 20005,\n  localDir: '/tmp/storage-sim',\n  buckets: ['my-bucket']\n});\n\nawait sim.start();\n\n// Now you can use any S3-compatible client to interact with the simulator\n// e.g., using @aws-sdk/client-s3\nimport { S3Client, PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';\n\nconst client = new S3Client({\n  region: 'us-east-1',\n  endpoint: `http://localhost:${sim.getPort()}`,\n  forcePathStyle: true,\n  credentials: {\n    accessKeyId: 'fake',\n    secretAccessKey: 'fake'\n  }\n});\n\nawait client.send(new PutObjectCommand({\n  Bucket: 'my-bucket',\n  Key: 'test.txt',\n  Body: 'Hello Simulator'\n}));\n\nconsole.log('Object stored!');\n\nawait sim.stop();","lang":"typescript","description":"Starts the storage simulator, uploads an object using an S3 client, and stops the simulator."},"warnings":[{"fix":"Change 'buckets: [\"my-bucket\"]' to 'buckets: [{ name: \"my-bucket\" }]'","message":"The constructor option 'buckets' as an array of strings is deprecated in v1.8+; use array of objects with 'name' property instead.","severity":"deprecated","affected_versions":">=1.8.0"},{"fix":"Do not use for security testing; implement your own authorization if needed.","message":"The simulator does not enforce S3 access control policies; all authenticated clients have full access to all buckets.","severity":"gotcha","affected_versions":"*"},{"fix":"If ETag validation is required, implement custom middleware to override responses.","message":"Object ETags are generated from UUIDs, not MD5 hashes of content. This may break clients that verify ETag integrity.","severity":"gotcha","affected_versions":"*"},{"fix":"Use 'await sim.start()' or chain with .then()","message":"In v1.6.0, the 'start()' method changed from synchronous to returning a Promise. Calling 'start()' without await may cause issues.","severity":"breaking","affected_versions":">=1.6.0"},{"fix":"Fall back to single PutObject calls or use a full S3 emulator.","message":"The simulator does not support multipart upload operations (CreateMultipartUpload, UploadPart, etc.).","severity":"gotcha","affected_versions":"*"},{"fix":"Replace 'sim.getPort()' with 'sim.port'","message":"The 'getPort()' method is deprecated in v1.10+; use the 'port' property instead.","severity":"deprecated","affected_versions":">=1.10.0"},{"fix":"Always set client region to 'us-east-1' when using the simulator.","message":"The simulator only supports the 'us-east-1' region; other regions are not validated but may cause client-side errors.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Ensure sim.start() is called and use 'localhost' (IPv4) or '127.0.0.1' as endpoint.","cause":"Simulator not started or wrong port; IPv6 localhost may not be bound.","error":"Error: connect ECONNREFUSED ::1:20005"},{"fix":"Use import statement: import { AmplifyStorageSimulator } from 'amplify-storage-simulator'","cause":"CommonJS require used instead of ESM import.","error":"TypeError: (0 , _amplifyStorageSimulator.AmplifyStorageSimulator) is not a constructor"},{"fix":"Add the bucket to options.buckets array as '{ name: \"my-bucket\" }'","cause":"Bucket not declared in options or name mismatch.","error":"Error: bucket 'my-bucket' is not configured"},{"fix":"Access 'sim.port' after start completes, or use 'await sim.start()' first.","cause":"Using deprecated 'getPort()' on simulator instance that hasn't started.","error":"TypeError: Cannot read properties of undefined (reading 'port')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}