Registry / aws / amplify-appsync-simulator

amplify-appsync-simulator

library2.4.1jsnpmunverified

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.

aws testing web-framework http-networking database

npm install amplify-appsync-simulator

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AMPLIFY-APPSYNC-SI

amplify-appsync-simulator

awsjavascriptv2.4.1

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.

AmplifyAppSyncSimulator

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

✗ const AmplifyAppSyncSimulator = require('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

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

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

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

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

Debug

Known issues

breakingVTL 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).

affects: >=2.0.0

deprecatedThe 'authenticationType' config option is deprecated; use 'authModes' instead.

fix

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

affects: >=2.3.0

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

affects: *

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

affects: *

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

fix

Use mock data sources or replace with local implementations.

affects: *

Errors

Common errors & fixes

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

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: No resolver found for type 'Query' field 'hello'

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.

SimulatorError: Unsupported authentication type

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: Cannot find module 'amplify-appsync-simulator'

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.

Upgrade

Version history

2.4.1latest on npm

Audit

Dependencies

amplify-clioptionalRequired to use simulator with Amplify projects; the simulator is a plugin.

Agent activity

59 hits · last 30 days

node

OpenAI (training)

Resources

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

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

homepagehttps://docs.amplify.aws ↗