Serverless-AppSync-Plugin 👌

Serverless plugin that allows you to deploy, update or delete your AWS AppSync API's with ease.

Tired of 🚀 deploying, ✏️ updating, and ❌ deleting your AppSync API's using the AWS AppSync dashboard? You can now develop all of your AppSync API's locally using Serverless + Serverless-AppSync-Plugin! With support for AWS DynamoDB, AWS Lambda, and AWS Elastic Search; you have everything you need to get started developing your AppSync API's locally.

Find AppSync examples in the Serverless-GraphQL Repo 👈

Introduction

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

Table of Contents (click to expand)

• Getting Started
• Installation
• Usage
• Contributing
• Credits

⚡️ Getting Started

Be sure to check out all that AWS AppSync has to offer. Here are a few resources to help you understand everything needed to get started!

• Mapping Templates - Not sure how to create Mapping Templates for DynamoDB, Lambda or Elastic Search? Here's a great place to start!
• Data Sources and Resolvers - Get more information on what data sources are supported and how to set them up!
• Security - Checkout this guide to find out more information on securing your API endpoints with AWS_IAM or Cognito User Pools!

💾 Installation

Install the plugin via Yarn (recommended)

yarn add serverless-appsync-plugin

or via NPM

npm install serverless-appsync-plugin

Configuring the plugin

Add serverless-appsync-plugin to the plugins section of serverless.yml

plugins:
   - serverless-appsync-plugin

Add the following example config to the custom section of serverless.yml

custom:
  accountId: abc # found here https://console.aws.amazon.com/billing/home?#/account
  appSync:
    name:  # defaults to api
    # apiId # only required for update-appsync/delete-appsync
    # apiKey # only required for update-appsync/delete-appsync
    authenticationType: AMAZON_COGNITO_USER_POOLS
    userPoolConfig:
      awsRegion: # required # region
      defaultAction: # ALLOW
      userPoolId: # required # user pool ID
      region: # defaults to provider region
    mappingTemplatesLocation: # defaults to mapping-templates
    mappingTemplates:
      - dataSource: # data source name
        type: # Query, Mutation, Subscription
        field: getUserInfo
        request: # request mapping template name
        response: # response mapping template name
    schema: # defaults schema.graphql
    serviceRole: "AppSyncServiceRole"
    dataSources:
      - type: AMAZON_DYNAMODB
        name: # data source name
        description: # DynamoDB Table Description
        config:
          tableName: # DynamoDB Table Name
          serviceRoleArn: "arn:aws:iam::${self:custom.accountId}:role/dynamo-${self:custom.appSync.serviceRole}"
      - type: AMAZON_ELASTICSEARCH
        name: # data source name
        description: 'ElasticSearch'
        config:
          endpoint: # required # "https://{DOMAIN}.{REGION}.es.amazonaws.com"
          serviceRoleArn: "arn:aws:iam::${self:custom.accountId}:role/elasticSearch-${self:custom.appSync.serviceRole}"
      - type: AWS_LAMBDA
        name: # data source name
        description: 'Lambda DataSource'
        config:
          lambdaFunctionArn: "arn:aws:lambda:us-east-1:${self:custom.accountId}:function:appsync-example-dev-graphql"
          serviceRoleArn: "arn:aws:iam::${self:custom.accountId}:role/Lambda-${self:custom.appSync.serviceRole}"

Be sure to replace all variables that have been commented out, or have an empty value.

▶️ Usage

serverless deploy-appsync

This command will deploy a new AppSync API endpoint using the name specified in the custom section of serverless.yml under appSync.

serverless update-appsync

This command will update an existing AppSync API endpoint using the apiId specified in the custom section of serverless.yml under appSync. (Data sources/resolvers will be automatically created if they don't already exist)

serverless delete-appsync

This command will delete an existing AppSync API endpoint using the apiId specified in the custom section of serverless.yml under appSync.

---

If the apiId you are trying to update or delete does not exist, an error will be thrown. Login to your AWS AppSync dashboard; retrieve the API ID that you are trying to update or delete, and set it as the apiId in serverless.yml

custom:
  appSync:
    apiId: xxxxxxxxxxxxxxxxxxxxxxxxxx

📝 Notes

• If you are planning on using AWS Elastic Search, you will need to create an Elastic Search domain/endpoint on AWS and set it as the endpoint option in serverless.yml before deploying.

🎁 Contributing

If you have any questions, please feel free to reach out to me directly on Twitter Sid Gupta.

❤️ Credits

Big Thanks to Nik Graf, Philipp Müns, Jon Patel and my favourite coolest kat ever for helping to build this plugin!

We are always looking for open source contributions. So, feel free to create issues/contribute to this repo.