About serverless-appsync-plugin

serverless plugin for appsync

s

Published by

sid88in

Visit View Profile

README.md

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

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:

_{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} 💻