Serverless Appsync Plugin

homepage icon https://github.com/sid88in/serverless-appsync-plugin
Follow @sid88in

Tracked

NPM Downloads Last Month
3258
Issues
33
Stars
228
Forks
49
Watchers
228
Watch Star Fork Issue Download License NPM Build Status Coverage Status Contributors

Repo README Contents:

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

appsync architecture

Table of Contents (click to expand) * [Getting Started](#-getting-started) * [Installation](#-installation) * [Usage](#️-usage) * [Contributing](#-contributing) * [Credits](#️-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!

💾 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
    # apiKey # only required for update-appsync/delete-appsync
    authenticationType: API_KEY or AWS_IAM or AMAZON_COGNITO_USER_POOLS or OPENID_CONNECT
    # if AMAZON_COGNITO_USER_POOLS
    userPoolConfig:
      awsRegion: # required # region
      defaultAction: # ALLOW
      userPoolId: # required # user pool ID
      region: # defaults to provider region
    # if OPENID_CONNECT
    openIdConnectConfig:
      issuer: 
      clientId: 
      iatTTL: 
      authTTL: 
    logConfig:
      loggingRoleArn: { Fn::GetAtt: [AppSyncLoggingServiceRole, Arn] } # Where AppSyncLoggingServiceRole is a role with CloudWatch Logs write access
      level: ERROR # Logging Level: NONE | ERROR | ALL
    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" # AppSyncServiceRole is a role defined by amazon and available in all accounts
    dataSources:
      - type: AMAZON_DYNAMODB
        name: # data source name
        description: # DynamoDB Table Description
        config:
          tableName: { Ref: MyTable } # Where MyTable is a dynamodb table defined in Resources
          serviceRoleArn: { Fn::GetAtt: [AppSyncDynamoDBServiceRole, Arn] } # Where AppSyncDynamoDBServiceRole is an IAM role defined in Resources
          region: # Overwrite default region for this data source
      - type: AMAZON_ELASTICSEARCH
        name: # data source name
        description: 'ElasticSearch'
        config:
          endpoint: # required # "https://{DOMAIN}.{REGION}.es.amazonaws.com"
          serviceRoleArn: { Fn::GetAtt: [AppSyncESServiceRole, Arn] } # Where AppSyncESServiceRole is an IAM role defined in Resources
      - type: AWS_LAMBDA
        name: # data source name
        description: 'Lambda DataSource'
        config:
          lambdaFunctionArn: { Fn::GetAtt: [GraphqlLambdaFunction, Arn] } # Where GraphqlLambdaFunction is the lambda function cloudformation resource created by serverless for the serverless function named graphql
          serviceRoleArn: { Fn::GetAtt: [AppSyncLambdaServiceRole, Arn] } # Where AppSyncLambdaServiceRole is an IAM role defined in Resources
      - type: HTTP
        name: # data source name
        description: 'Http endpoint'
        config:
          endpoint: # required # "https://{DOMAIN}/{PATH}"
    substitutions: # allows to pass variables from here to velocity templates
      # ${exampleVar1} will be replaced with given value in all mapping templates
      exampleVar1: "${self:service.name}"
      exampleVar2: {'Fn::ImportValue': 'Some-external-stuff'}

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

▶️ Usage

serverless deploy

This command will deploy all AppSync resources in the same CloudFormation template used by the other serverless resources.

📝 Notes

🎁 Contributing

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

👷 Migration from versions prior to 1.0

If you have previously used versions of this plugin prior to 1.0, you will need to perform some additional manual steps in order to continue use of this plugin (it will be worth it). This change removes the sls *-appsync commands in favor of adding AppSync resources directly to the serverless cloudformation stack. What this means for your existing APIs is that they can no longer be updated. The good news is that you will no longer need to use separate commands to deploy vs update and update your serverless config with the created apiId.

The rough steps for migration are as follows:

  1. Run sls deploy to create the new AppSync api and make note of the endpoint returned as part of the stack outputs. If you were using an API_KEY auth type, you will also need the new api key which is also included in the stack outputs.
  2. Update existing consumers of your API to use the new endpoint. If you’re using an api key, this will also need updated
  3. After verifying all existing consumers are updated, run sls delete-appsync to cleanup the old resources
  4. Remove the apiId line from custom.appSync in serverless.yml
  5. 🍹

❤️ 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.