Deploy AppSync API's in minutes using this Serverless plugin.

Contact me @linkedin

📈 Adoption

9.2M+ total downloads since Jan 2018

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 :clap:

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