Skip to main content

Getting Started

Prerequisites​

To follow this workshop, you will need:

  • An AWS account
  • Basic understanding of GraphQL and the Schema Definitions Language (SDL)
  • Basic knowledge about AWS and its services (i.e. DynamoDB, Cognito)
  • Some background with TypeScript

High-level understanding the Serverless Framework might also be useful.

Ready? Let's get started.

Clone the Project​

First, we will clone the project and get familiar with it. Run the following command and open it in your favorite IDE.

git clone git@github.com:bboure/appsync-typescript-workshop.git

Workspace Structure​

The working directory should look like this.

├── codegen.ts
├── definitions
│   ├── appsync.ts
│   ├── cognito.ts
│   └── dynamodb.ts
├── schema
│   └── schema.graphql
├── serverless.ts
└── src
    ├── resolvers
    │   └── Query.getTask.ts
    ├── types
    │   ├── db.ts
    │   └── schema.ts
    └── utils.ts
  • codegen.ts contains GraphQL codegen configuration (More on that below).
  • definitions is a directory containing files with Serverless Framework definitions.
  • schema is a directory containing the schema for our API.
  • serverless.ts is the entry point of our Serverless Framework definitions.
  • src will contain the business logic for our API as well as some TypeScript types.

The GraphQL Schema​

Open schema/schema.graphql. It contains a basic schema for our API, including several types (e.g. Task and Project), some queries (e.g. getTask) and mutations (createTask).

If you want to learn more about types, fields and GraphQL schemas, go to the GraphQL docs.

TypeScript​

AWS AppSync allows us to write resolvers in JavaScript. This means that, in order to have better auto-complete capabilities as well as safeguarding us from making mistakes, we can also use TypeScript.

By default, AWS AppSync does not support TypeScript. Instead, it supports a limited flavour of JavaScript. Luckily, the serverless-appsync-plugin automatically transpiles and bundles TypeScript into AppSync-compatible Javascript code, out of the box.

Eslint​

In our project, we installed and configured eslint (.eslintrc.json). This gives us linting capabilities about good practices when writing code in TypeScript. However, AppSync does not support all of “standard” JavaScript/TypeScript features.

The AppSync team provides a useful eslint plugin that warns us about invalid usage: @aws-appsync/eslint-plugin

We are using the plugin in this project, but because we only want it to be active inside resolvers code, we use an additional eslint config file that we placed in the src/resolvers directory. This way, those special rules only apply to resolvers, and not the rest of our codebase (for example, Lambda functions).

{
  "extends": ["plugin:@aws-appsync/base"]
}

Codegen​

GraphQL Codegen is an open-source library that provides tools to generate code from GraphQL schemas. In this project, we will use it in order to generate the TypeScript types of our API. It uses the definition in codegen.ts.

Run the following command.

npm run codegen

Now have a look at src/types/schema.ts. You should see a set of TypeScript types that match our schema. We will use them later to build our API.