Minimum requirements
June 4, 2026 ยท View on GitHub
Deploy AppSync API's in minutes using this Serverless plugin.
Contact me @linkedin
๐ Adoption
9.2M+ total downloads since Jan 2018
Interactive charts (weekly trends, year-by-year since 2018): npm.chart.dev โ ยท npm-stat (from Jan 2018) โ ยท npmjs.com โ
Minimum requirements
Installation
npm install serverless-appsync-plugin
Quick start
service: my-app
plugins:
- serverless-appsync-plugin
provider:
name: aws
appSync:
name: my-api
authentication:
type: API_KEY
resolvers:
Query.user:
dataSource: my-table
dataSources:
my-table:
type: AMAZON_DYNAMODB
config:
tableName: ${sls:stage}-data
Testing
The test suite is split into three independent layers. The first two run offline and need no AWS account; the third is opt-in and talks to a real AWS account.
Unit tests
Pure logic, schema validation and CloudFormation snapshots under
src/__tests__/. No AWS credentials required.
npm test
# Re-run on change
npm run test:watch
End-to-end (CloudFormation synthesis) tests
The tests in e2e/ apply the plugin to the example projects under
examples/, run serverless package, and assert on the generated
CloudFormation. They build the plugin first and do not deploy anything to
AWS, so they need no credentials and are safe to run on every PR. See
e2e/README.md for details.
# Run all synthesis tests (runs `npm run build` first)
npm run test:e2e
# Unit + e2e together
npm run test:all
# A single fixture
npx jest --config jest.e2e.config.ts basic-api-key
AWS integration tests
The suite in integration/ exercises the live AWS code paths against a real
AWS account, so it costs money and requires credentials. It is gated
behind APPSYNC_PLUGIN_INTEGRATION=1 โ without it every suite resolves to
describe.skip and the run exits green, which is why it never runs as part of
npm test, npm run test:e2e, npm run test:all, or the default CI.
# Cheapest useful run (evaluate + minimal deploy tiers)
APPSYNC_PLUGIN_INTEGRATION=1 \
APPSYNC_PLUGIN_INTEGRATION_REGION=us-west-2 \
AWS_PROFILE=my-sandbox \
npm run test:integration
Higher-cost tiers are opt-in on top of the master switch: set
APPSYNC_PLUGIN_INTEGRATION_CACHING=1 for the caching tier, and
APPSYNC_PLUGIN_INTEGRATION_DOMAIN + APPSYNC_PLUGIN_INTEGRATION_HOSTED_ZONE_ID
for the custom-domain tier. After a run, sweep any leftover stacks with
npm run test:integration:sweep. See
doc/integration-tests.md for the full tier
breakdown, environment variables, and cost profile.
Configuration
- General config
- DataSources
- Resolvers
- Pipeline Functions
- Authentication
- API keys
- Custom Domain
- Variable Substitutions
- Caching
- Web Application Firewall (WAF)
- Testing Resolvers
CLI
This plugin adds some useful CLI commands. See CLI commands documentation
| Command | Description |
|---|---|
sls appsync validate-schema | Validate the GraphQL schema |
sls appsync get-introspection | Export the introspection schema (JSON or SDL) |
sls appsync flush-cache | Flush the API cache |
sls appsync console | Open the AWS AppSync console |
sls appsync cloudwatch | Open CloudWatch logs |
sls appsync logs | Stream logs to stdout |
sls appsync evaluate | Evaluate a JS resolver or VTL template without deploying |
sls appsync env get | Get runtime environment variables of the deployed API |
sls appsync env set | Set a runtime environment variable on the deployed API |
sls appsync domain * | Manage custom domains |
Variables
This plugin exports some handy variables that you can use in your yml files to reference some values generated by CloudFormation:
${appsync:id}: The id of the AppSync API${appsync:url}: The URL of the AppSync API${appsync:arn}: The ARN of the AppSync API${appsync:apiKey.[NAME]}: An API key
Example:
provider:
environment:
APPSYNC_ID: ${appsync:id}
APPSYNC_ARN: ${appsync:arn}
APPSYNC_URL: ${appsync:url}
APPSYNC_API_KEY: ${appsync:apiKey.myKey}
appSync:
name: my-api
authentication:
type: API_KEY
apiKeys:
- name: myKey
Upgrading from v1
To upgrade form v1 of this plugin, follow this guide
Contributing
If you have any questions, issue, feature request, please feel free to open an issue.
You are also very welcome to open a PR and we will gladly review it.
Resources
Tools
- Mapping Tool: Quickly Build and Debug AppSync & API Gateway Mapping Templates
- GraphBolt: A professional desktop app solution for building, testing, and debugging AppSync APIs.
- AppSync Resolver Autocomplete: VSCode extension. Autocomplete support for VTL template files.
Video tutorials
Blog tutorial
Contributors โจ
Thanks goes to these wonderful people :clap:
This project follows the all-contributors specification. Contributions of any kind welcome!