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.
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
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 # 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
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
- 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 inserverless.yml
before deploying.
🎁 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:
- 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 anAPI_KEY
auth type, you will also need the new api key which is also included in the stack outputs. - Update existing consumers of your API to use the new endpoint. If you're using an api key, this will also need updated
- After verifying all existing consumers are updated, run
sls delete-appsync
to cleanup the old resources - Remove the
apiId
line fromcustom.appSync
inserverless.yml
- 🍹
❤️ 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.