This Serverless Framework Component is a specialized developer experience focused on making it easy to deploy and manage GraphQL applications on serverless infrastructure (specifically AWS AppSync and AWS Lambda) on your own AWS account. It comes loaded with powerful development features and represents possibly the easiest, cheapest and most scalable way to host GraphQL apps.

• Never Pay For Idle - No requests, no cost. Averages $0.0000002-$0.0000009 per request.
• Zero Configuration - All we need is your code, then just deploy (advanced config options are available).
• Fast Deployments - Deploy to the cloud in seconds.
• Realtime Logging - Rapidly develop on the cloud w/ real-time logs and errors in the CLI.
• Team Collaboration - Collaborate with your teammates with shared state and outputs.
• Custom Domain + SSL - Auto-configure a custom domain w/ a free AWS ACM SSL certificate.
• Lambda Default Resolver - Automatically deploys your code to a lambda function for rapid query resolution.
• Works with All Data Sources - Can be configured to work with directly with DynamodDB, and other data sources.
• Flexible Authorization Options - Supports all AppSync authorization options, API Key, IAM, Cognito or OpenID auth.

• Quick Start
  • Install
  • Initialize
  • Deploy
  • Query
• Configuration Reference
  • Extend Existing API
  • Lambda Configuration
  • Custom Domain
  • Custom IAM Policies
  • Authorization
  • Data Sources Resolvers
• CLI Reference
• Outputs Reference
• FAQs

To get started with this component, install the latest version of the Serverless Framework:

npm install -g serverless

After installation, make sure you connect your AWS account by setting a provider in the org setting page on the Serverless Dashboard.

The easiest way to start using the graphql component is by initializing the graphql-starter template. Just run this command:

serverless init graphql-starter
cd graphql-starter

This will also run npm install for you. You should now have a directory that looks something like this:

|- serverless.yml
|- schema.graphql
|- resolvers.js

The serverless.yml file is where you define your component config. It looks something like this:

component: graphql
name: graphql-api

inputs:
  src: ./

For more configuration options for the serverless.yml file, check out the Configuration section below.

The schema.graphql is where you define your GraphQL schema. It looks something like this:

type Post {
  id: ID!
}

type Query {
  getPost(id: ID!): Post
}

type Mutation {
  createPost(id: ID!): Post
}

schema {
  query: Query
  mutation: Mutation
}

The resolvers.js file is where you define your schema resolvers. It looks something like this:

const Query = {
  // resolver for field getPost in type Query
  getPost: async ({ id }) => {
    return { id }
  }
}

const Mutation = {
  // resolver for field createPost in type Mutation
  createPost: async ({ id }) => {
    return { id }
  }
}

module.exports = { Query, Mutation }

In this file, you simply export each of your schema types (ie. Query & Mutation) as an object of functions. Each function is a field resolver for that type.

All these files are required. Needless to say, any resolver you define in resolvers.js, must also be defined in your schema in the schema.graphql file, otherwise, you'll get an AppSync error. Same goes for the resolvers inputs & outputs. Remember, GraphQL is strongly typed by design.

Once you have the directory set up, you're now ready to deploy. Just run the following command from within the directory containing the serverless.yml file:

serverless deploy

Your first deployment might take a little while, but subsequent deployment would just take few seconds.

After deployment is done, you should see your the following outputs:

name:   graphql-api-pxzaf135
apiKey: da2-yf444kxlhjerxl376jxyafb2rq
apiId:  survbmoad5ewtnm3e3cd7qys4q
url:    https://cnbfx5zutbe4fkrtsldsrunbuu.appsync-api.us-east-1.amazonaws.com/graphql

Your GraphQL API is now deployed! Next time you deploy, if you'd like to know what's happening under the hood and see realtime logs, you can pass the --debug flag:

serverless deploy --debug

You can query and test your newly created GraphQL API directly with the AWS AppSync console, or any HTTP client.

Here's a snippet using fetch or node-fetch with the example above:

// you can get the url and apiKey values from the deployment outputs
const url = 'https://cnbfx5zutbe4fkrtsldsrunbuu.appsync-api.us-east-1.amazonaws.com/graphql'
const apiKey = 'da2-yf444kxlhjerxl376jxyafb2rq'

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': apiKey // the "x-api-key" header is required by AppSync
  },
  body: JSON.stringify({
    query: `query getPost { getPost(id: "123") { id }}`
  })
})
  .then((res) => res.json())
  .then((post) => console.log(post))

The response should be an echo of the post id, something like this:

{
  "data": {
    "getPost": {
      "id": "123"
    }
  }
}

The GraphQL component is a zero configuration component, meaning that it'll work out of the box with no configuration and sane defaults. With that said, there are still a lot of optional configuration that you can specify.

Here's a very minimal configuration to get you started. Most of these properties are optional, but if you use them, remember to substitute with your own value if required (ie. the org property)

component: graphql               # (required) name of the component. In that case, it's graphql.
name: graphql-api                # (required) name of your graphql component instance.
org: serverlessinc               # (optional) serverless dashboard org. default is the first org you created during signup.
app: myApp                       # (optional) serverless dashboard app. default is the same as the name property.
stage: dev                       # (optional) serverless dashboard stage. default is dev.

inputs:
  src: ./                        # (optional) path to the source folder. default is a simple blogging app.
  region: us-east-2              # (optional) aws region to deploy to. default is us-east-1.

Even the src input is optional. If you didn't specify any src directory containing your code, an example app will be deployed for you.

Keep reading to learn more about all the configuration options available to you.

If the appId input variable is provided this component will extend an existing AppSync API:

inputs:
  src: ./
  apiId: xxx                     # (optional) if provided will extend an existing api.

The apiId can be reference from the source component using the apiId output variable from the component instance that created the graphql API: ${output:[STAGE]:[APP]:[NAME].apiId}

If you specify resolvers in a resolvers.js file as shown in the quick start above, the component will deploy a lambda function automatically for you to host your resolvers and connect everything together. You can configure this default lambda function with the following inputs:

inputs:
  src: ./
  description: My GraphQL App    # (optional) lambda description. default is en empty string.
  memory: 512                    # (optional) lambda memory size. default is 3008.
  timeout: 10                    # (optional) lambda timeout. default is 300.
  env:                           # (optional) env vars. default is an empty object
    TABLE: 'my-table'
  layers:                        # (optional) list of lambda layer arns to attach to your lambda function.
    - arn:aws:first:layer
    - arn:aws:second:layer
  vpcConfig:                     # (optional) specify a vpc
    securityGroupIds:
      - sg-xxx
    subnetIds:
      - subnet-xxx
      - subnet-xxx

If you've purchased your domain from AWS Route53, you can configure the domain with a single input:

inputs:
  src: ./
  domain: example.com

Subdomains work too:

inputs:
  src: ./
  domain: api.example.com

This will create a a free SSL certificate for you with AWS ACM, deploy a CDN with AWS CloudFront, and setup all the DNS records required.

If you've purchased your domain elsewhere, you'll have to manually create a Route53 hosted zone for your domain, and point to the AWS nameservers on your registrar before you add the domain input.

The component creates the minimum required IAM policy based on your configuration. But you could always add your own policy statements using the policy input:

inputs:
  src: ./src
  policy:
    - Action: '*'
      Effect: Allow
      Resource: '*'

This policy applies to both the built-in Lambda function and the AppSync API. Keep in mind that this component automatically adds the required IAM policies to invoke your data source depending on your configuration.

This component uses apiKey authorization by default. However all other AppSync authorization options are available via the auth input.

IAM authorization:

inputs:
  src: ./
  auth: iam

Cognito authorization:

inputs:
  src: ./
  auth:
    userPoolId: qwertyuiop
    defaultAction: ALLOW
    region: us-east-1
    appIdClientRegex: qwertyuiop

OpenID authorization:

inputs:
  src: ./
  auth:
    issuer: qwertyuiop
    authTTL: 0
    clientId: wertyuiop
    iatTTL: 0

If you'd like to setup your resolvers to use your own existing data sources, you could specify your resolvers as a serverless.yml input instead of inside a resolvers.js file.

In that case, you'll need to also specify your own request and response VTL templates. You could do that directly in serverless.yml, or by pointing to a vtl file inside of your src directory.

Here's an example using an existing lambda as a data source:

inputs:
  src: ./
  resolvers:
    Query:                          # this must be a valid type in your schema
      getPost:                      # this must be a valid resolver in your schmea
        lambda: my-lambda           # this will set up the my-lambda Lambda as a data source for this resolver
        request: >                  # the request VTL template for this resolver.
          { "version": "2017-02-28", "operation": "Invoke", "payload": $util.toJson($context)  }
        response: response.vtl      # you could also point to a VTL file relative to your src directory.

These request and response properties are required regardless of which data source you are working with, and they're different depending on your schema and your application requirements. Check out the official AWS docs for more information on the required syntax for each data source.

inputs:
  src: ./
  resolvers:
    Query:                          
      getPost:                      
        lambda: my-lambda
        request: '{ "version": "2017-02-28", "operation": "Invoke", "payload": $util.toJson($context)  }'
        response: '$util.toJson($context.result)'

inputs:
  src: ./
  resolvers:
    Query:                          
      getPost:                      
        table: my-table
        request: >
          {
              "version" : "2017-02-28",
              "operation" : "PutItem",
              "key" : {
                  "id" : $util.dynamodb.toDynamoDBJson($context.arguments.id)
              }
          }
        response: '$util.toJson($context.result)'

inputs:
  src: ./
  resolvers:
    Query: 
      getPost:
        endpoint: https://search-my-sample-data-abbaabba.us-east-1.es.amazonaws.com
        request: >
          {
              "version":"2017-02-28",
              "operation":"GET",
              "path":"/id/post/_search",
              "params":{
                  "headers":{},
                  "queryString":{},
                  "body":{
                      "from":0,
                      "size":50
                  }
              }
          }
        response: >
          [
              #foreach($entry in $context.result.hits.hits)
              #if( $velocityCount > 1 ) , #end
              $utils.toJson($entry.get("_source"))
              #end
          ]

inputs:
  src: ./
  resolvers:
    Query:    
      getPost: 
        database: my-database
        dbClusterIdentifier: arn:aws:rds:us-east-1:123456789123:cluster:my-serverless-aurora-postgres-1
        awsSecretStoreArn: arn:aws:secretsmanager:us-east-1:123456789123:secret:rds-db-credentials/cluster-ABCDEFGHI/admin-aBc1e2
        relationalDatabaseSourceType: RDS_HTTP_ENDPOINT
        schema: public
        request: >
          {
              "version": "2018-05-29",
                  "statements": [
                      $util.toJson("select * from Posts WHERE id='$ctx.args.id'")
              ]
          }
        response: '$utils.toJson($utils.rds.toJsonObject($ctx.result)[0][0])'

To deploy, simply run deploy from within the directory containing the serverless.yml file:

serverless deploy

If you'd like to know what's happening under the hood and see realtime logs, you can pass the --debug flag:

serverless deploy --debug

Instead of having to run serverless deploy everytime you make changes you wanna test, you can enable dev mode, which allows the CLI to watch for changes in your source directory as you develop, and deploy instantly on save.

To enable dev mode, simply run the following command from within the directory containing the serverless.yml file:

serverless dev

Dev mode also enables live streaming logs from your GraphQL app so that you can see the results of your code changes right away on the CLI as they happen.

Anytime you need to know more about your running GraphQL instance, you can run the following command to view the most critical info:

serverless info

This is especially helpful when you want to know the outputs of your instances so that you can reference them in another instance. It also shows you the status of your instance, when it was last deployed, how many times it was deployed, and the error message & stack if the latest deployment failed.

To dig even deeper, you can pass the --debug flag to view the state object of your component instance:

serverless info --debug

If you wanna tear down your entire GraphQL infrastructure that was created during deployment, just run the following command in the directory containing the serverless.yml file:

serverless remove

The GraphQL component will then use all the data it needs from the built-in state storage system to delete only the relavent cloud resources that it created.

Just like deployment, you could also specify a --debug flag for realtime logs from the GraphQL component running in the cloud:

serverless remove --debug

name:   graphql-api-pxzaf135
apiKey: da2-yf444kxlhjerxl376jxyafb2rq
apiId:  survbmoad5ewtnm3e3cd7qys4q
url:    https://cnbfx5zutbe4fkrtsldsrunbuu.appsync-api.us-east-1.amazonaws.com/graphql

You can run npm init & npm install as you normally would in the directory containing the resolvers.js file. This is the root of your app. This entire directory is uploaded to your Lambda function, and you can structure it however you want. Just make sure resolvers.js and schema.graphql are in the root of the directory.