Amplify AppSync Simulator

2.4.1 verified Sat Apr 25 auth: no javascript

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.

Common errors

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

cause Missing 'code' property in resolver request/response object when using VTL template.

fix

Ensure resolver object has 'request' and 'response' properties each containing a 'code' string.

error Error: No resolver found for type 'Query' field 'hello' ↓

cause Resolver for the field 'Query.hello' is not defined in the resolvers map.

fix

Add a resolver entry for 'Query.hello' with a 'request' and 'response' object.

error SimulatorError: Unsupported authentication type ↓

cause Authentication type provided is not one of the allowed values (API_KEY, AWS_IAM, AMAZON_COGNITO_USER_POOLS, OPENID_CONNECT).

fix

Set 'authenticationType' to a valid value or use 'authModes' array.

error Error: Cannot find module 'amplify-appsync-simulator' ↓

cause Package not installed or CommonJS require used with ESM-only package.

fix

Run 'npm install amplify-appsync-simulator' and use import syntax or ensure bundler supports ESM.

Warnings

breaking VTL resolver code must use $util functions; custom JavaScript resolvers require explicit async handlers. ↓

fix Ensure VTL templates follow AppSync conventions; for JS resolvers, export async function handler(event, context).

deprecated The 'authenticationType' config option is deprecated; use 'authModes' instead. ↓

fix Replace with 'authModes: [{ authenticationType: 'API_KEY' }]'.

gotcha Simulator does not support all AppSync features (e.g., HTTP resolvers with full headers, built-in caching). ↓

fix Check release notes for unsupported features; consider integration tests on real AppSync for full coverage.

gotcha Schema must be provided as string or AST; file paths are not resolved automatically. ↓

fix Use fs.readFileSync to load schema from file and pass as string.

gotcha Simulator uses in-memory data sources; external data sources (e.g., DynamoDB) are not connected. ↓

fix Use mock data sources or replace with local implementations.

Install

npm install amplify-appsync-simulator

yarn add amplify-appsync-simulator

pnpm add amplify-appsync-simulator

Imports

AmplifyAppSyncSimulator

wrong

const AmplifyAppSyncSimulator = require('amplify-appsync-simulator')

correct

import { AmplifyAppSyncSimulator } from 'amplify-appsync-simulator'

ESM-only package; CommonJS require will fail if bundler doesn't support ESM.

SimulatorConfig
```
import { SimulatorConfig } from 'amplify-appsync-simulator'
```
TypeScript type for configuration object. Not available in CJS.

AppSyncSimulatorDataSourceType

wrong

const AppSyncSimulatorDataSourceType = require('amplify-appsync-simulator').AppSyncSimulatorDataSourceType

correct

import { AppSyncSimulatorDataSourceType } from 'amplify-appsync-simulator'

CommonJS require will not work; use dynamic import if needed.

Quickstart

Shows creating a minimal simulator with a static schema, a lambda resolver, and running a query inline.

import { AmplifyAppSyncSimulator } from 'amplify-appsync-simulator';

const simulator = new AmplifyAppSyncSimulator({
  schema: {
    // Minimal schema
    code: `
      type Query {
        hello: String
      }
      schema {
        query: Query
      }
    `
  },
  resolvers: {
    'Query.hello': {
      request: { code: '{}' },
      response: { code: "$util.toJson(\"World\")" }
    }
  },
  dataSources: {},
  appSync: { name: 'test', defaultAuthenticationType: { authenticationType: 'API_KEY' } },
  authenticationType: 'API_KEY'
});

async function main() {
  const result = await simulator.simulate({
    operationName: 'hello',
    query: 'query { hello }'
  });
  console.log(result);
  await simulator.stop();
}
main();