AppSync Butler

AppSync Butler is an AppSync (GraphQL) API development framework, compatible with AWS Cloud Development Kit and Serverless Stack Toolkit. Visit the homepage for more information.

This package does the heavy-lifting to parse and load on-disk resolvers and functions.

Quick start

Begin your journey in your existing CDK/SST project ✨

1. Install the required dependencies

1# Do not install @aws-cdk/aws-appsync-alpha when using SST.
2npm install @aws-cdk/aws-appsync-alpha @appsync-butler/core

2. Setup the directory structure

1mkdir -p vtl/{resolvers,functions} \
2    vtl/resolvers/{Query,Mutation} \
3    graphql
4echo '# TODO: Write GraphQL schema' >> graphql/index.graphql

3. Create a simple date resolver

1cat <<EOF >> graphql/index.graphql
2schema {
3  query: Query
4}
5
6type Query {
7  getDateTime: String!
8}
9EOF
10
11mkdir vtl/resolvers/Query/getDateTime
12
13cat <<EOF > vtl/resolvers/Query/getDateTime/request.vtl
14##@butler.dataSource('none')
15{
16    "version": "2018-05-29"
17}
18EOF
19
20echo '$util.toJson($util.time.nowFormatted("yyyy-MM-dd HH:mm:ssZ"))' \
21    >  vtl/resolvers/Query/getDateTime/response.vtl

4. Instantialize the loader and call Loader#load

1import { Stack, StackProps } from 'aws-cdk-lib';
2import { Construct } from 'constructs';
3import { Table, AttributeType } from 'aws-cdk-lib/aws-dynamodb';
4import { GraphqlApi, Schema } from '@aws-cdk/aws-appsync-alpha';
5import { Loader } from '@appsync-butler/core';
6
7export class AppStack extends Stack {
8    constructor(scope: Construct, id: string, props?: StackProps) {
9        super(scope, id, props);
10        const table = new Table(this, 'table', {
11            partitionKey: { name: "pk", type: AttributeType.STRING }
12        });
13        const api = new GraphqlApi(this, 'api', {
14            name: "test",
15            schema: Schema.fromAsset("graphql/index.graphql")
16        });
17        const tableDs = api.addDynamoDbDataSource('tableDs', table);
18        const loader = new Loader(this, {
19            api,
20            defaultUnitResolverDataSource: tableDs,
21            defaultFunctionDataSource: tableDs
22        });
23        loader.load();
24    }
25}

Congratulations! You have wrote your first AppSync Butler application 🎉 Deploy the stack to interact with your newly created GraphQL API. Alternatively, you can use npx appsync-butler to run steps 1 and 2.

Documentation

Explore the documentation of AppSync Butler here.