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

• Node.js v20 or higher
• Serverless v3.0.0 or higher

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

• Building an AppSync + Serverless Framework Backend | FooBar

Blog tutorial

• Part 1: Running a scalable & reliable GraphQL endpoint with Serverless

• Part 2: AppSync Backend: AWS Managed GraphQL Service

• Part 3: AppSync Frontend: AWS Managed GraphQL Service

• Part 4: Serverless AppSync Plugin: Top 10 New Features

Contributors ✨

Thanks goes to these wonderful people 👏

Benoît Bouré 🚧 💻	Siddharth Gupta 💻	Nik Graf 💻	Charles Killer 💻	jpstrikesback 💻	ZY 💻	Francis Upton IV 💻
Ilya Shmygol 💻	Maddi Joyce 💻	sebflipper 💻	Erez Rokah 💻	Akshay Kadam (A2K) 💻	Anton 💻	Burkhard Reffeling 💻
Dean Koštomaj 💻	Vincent Lesierse 💻	lulzneko 💻	thomas michael wallace 💻	Adnene KHALFA 💻	Alex Rozn 💻	Eric Chan 💻
Joseph 💻	Miha Eržen 💻	Mike Fogel 💻	Philipp Muens 💻	Toxuin 💻	Scott Rippee 💻	Yi Ai 💻
markvp 💻	Alex 💻	Alex Jurkiewicz 💻	Anas Qaderi 💻	Andreas Heissenberger 💻	mickael 💻	Brian Torres-Gil 💻
Cameron Childress 💻	Chris Chiang 💻	Esref Durna 💻	Hari 💻	Ivan Barlog 💻	John Veldboom 💻	Luca Bigon 💻
Lucas 💻	Mark Pollmann 💻	Maurice Williams 💻	Mike Chen 💻	asnaseer-resilient 💻	Neal Clark 💻	Nicky Moelholm 💻
Patrick Arminio 💻	Paul Li 💻	James Lal 💻	Sam Gilman 💻	Stefan Ceriu 💻	tsmith 💻	veloware 💻
Vladimir Lebedev 💻	Ryan Jones 💻	Vicary A. 💻	Brian Santarelli 🤔	Emilio Font 💻	Andriy Nastyn 💻 📖	MarcusJones 📖
h-kishi 💻	Dillon Browne 💻	Piotr Grzesik 💻	Aleksa Cukovic 💻	Scott Davey 💻	Mateus Holzschuh 💻

This project follows the all-contributors specification. Contributions of any kind welcome!