{"id":18103,"library":"amplify-appsync-simulator","title":"Amplify AppSync Simulator","description":"A local simulator for AWS AppSync APIs, enabling developers to test GraphQL operations and resolvers without direct cloud resources. Part of the Amplify CLI ecosystem, this package (version 2.4.1 as per npm) allows offline development by mimicking AppSync behavior including VTL and JavaScript resolvers, pipeline functions, and authentication modes. It supports unit testing of resolvers and mocking of data sources, reducing deployment cycles. Maintained by AWS, it releases in lockstep with Amplify CLI (~monthly). Unlike alternatives like appsync-simulator, it integrates tightly with Amplify's schema and configuration files.","status":"active","version":"2.4.1","language":"javascript","source_language":"en","source_url":"https://github.com/aws-amplify/amplify-cli","tags":["javascript","graphql","appsync","aws","simulator"],"install":[{"cmd":"npm install amplify-appsync-simulator","lang":"bash","label":"npm"},{"cmd":"yarn add amplify-appsync-simulator","lang":"bash","label":"yarn"},{"cmd":"pnpm add amplify-appsync-simulator","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required to use simulator with Amplify projects; the simulator is a plugin.","package":"amplify-cli","optional":true}],"imports":[{"note":"ESM-only package; CommonJS require will fail if bundler doesn't support ESM.","wrong":"const AmplifyAppSyncSimulator = require('amplify-appsync-simulator')","symbol":"AmplifyAppSyncSimulator","correct":"import { AmplifyAppSyncSimulator } from 'amplify-appsync-simulator'"},{"note":"TypeScript type for configuration object. Not available in CJS.","symbol":"SimulatorConfig","correct":"import { SimulatorConfig } from 'amplify-appsync-simulator'"},{"note":"CommonJS require will not work; use dynamic import if needed.","wrong":"const AppSyncSimulatorDataSourceType = require('amplify-appsync-simulator').AppSyncSimulatorDataSourceType","symbol":"AppSyncSimulatorDataSourceType","correct":"import { AppSyncSimulatorDataSourceType } from 'amplify-appsync-simulator'"}],"quickstart":{"code":"import { AmplifyAppSyncSimulator } from 'amplify-appsync-simulator';\n\nconst simulator = new AmplifyAppSyncSimulator({\n  schema: {\n    // Minimal schema\n    code: `\n      type Query {\n        hello: String\n      }\n      schema {\n        query: Query\n      }\n    `\n  },\n  resolvers: {\n    'Query.hello': {\n      request: { code: '{}' },\n      response: { code: \"$util.toJson(\\\"World\\\")\" }\n    }\n  },\n  dataSources: {},\n  appSync: { name: 'test', defaultAuthenticationType: { authenticationType: 'API_KEY' } },\n  authenticationType: 'API_KEY'\n});\n\nasync function main() {\n  const result = await simulator.simulate({\n    operationName: 'hello',\n    query: 'query { hello }'\n  });\n  console.log(result);\n  await simulator.stop();\n}\nmain();","lang":"typescript","description":"Shows creating a minimal simulator with a static schema, a lambda resolver, and running a query inline."},"warnings":[{"fix":"Ensure VTL templates follow AppSync conventions; for JS resolvers, export async function handler(event, context).","message":"VTL resolver code must use $util functions; custom JavaScript resolvers require explicit async handlers.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Replace with 'authModes: [{ authenticationType: 'API_KEY' }]'.","message":"The 'authenticationType' config option is deprecated; use 'authModes' instead.","severity":"deprecated","affected_versions":">=2.3.0"},{"fix":"Check release notes for unsupported features; consider integration tests on real AppSync for full coverage.","message":"Simulator does not support all AppSync features (e.g., HTTP resolvers with full headers, built-in caching).","severity":"gotcha","affected_versions":"*"},{"fix":"Use fs.readFileSync to load schema from file and pass as string.","message":"Schema must be provided as string or AST; file paths are not resolved automatically.","severity":"gotcha","affected_versions":"*"},{"fix":"Use mock data sources or replace with local implementations.","message":"Simulator uses in-memory data sources; external data sources (e.g., DynamoDB) are not connected.","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 resolver object has 'request' and 'response' properties each containing a 'code' string.","cause":"Missing 'code' property in resolver request/response object when using VTL template.","error":"TypeError: Cannot read properties of undefined (reading 'code')"},{"fix":"Add a resolver entry for 'Query.hello' with a 'request' and 'response' object.","cause":"Resolver for the field 'Query.hello' is not defined in the resolvers map.","error":"Error: No resolver found for type 'Query' field 'hello'"},{"fix":"Set 'authenticationType' to a valid value or use 'authModes' array.","cause":"Authentication type provided is not one of the allowed values (API_KEY, AWS_IAM, AMAZON_COGNITO_USER_POOLS, OPENID_CONNECT).","error":"SimulatorError: Unsupported authentication type"},{"fix":"Run 'npm install amplify-appsync-simulator' and use import syntax or ensure bundler supports ESM.","cause":"Package not installed or CommonJS require used with ESM-only package.","error":"Error: Cannot find module 'amplify-appsync-simulator'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}