DEV Community: Dave Hudson

How to use Amplify AppSync GraphQL types in a React TypeScript App

Dave Hudson — Tue, 01 Dec 2020 10:41:13 +0000

I recently had the task of performing a code review on a TypeScript project utilising NextJS and Amplify AppSync. The developer had opted for TypeScript because it would "prevent runtime errors for both backend and frontend". This is solid reasoning which I fully support, problem was this wasn't quite what was happening in reality.

The AppSync GraphQL was strongly typed through the schema.graphql file but the TypeScript frontend wasn't linked to those types in any way. The React code simply used the TypeScript :any type meaning the code was effectively opting out of type checking. So how do you use the TypeScript types of an AppSync GraphQL API on the frontend of a React app?

The Amplify CLI is pretty helpful and gets you most of the way there as it generates a types file when codegen is run. However, it turns out the generated types need some further manipulation as they contain null values and __typename properties. Additionally when actually making a GraphQL API call we get back a JSON response wrapped in a data: object which our type doesn't expect.

What follows is a detailed walkthrough of the steps I took to achieve a typed frontend, taking the generated types from Amplify and manipulating them into a format that can be used effectively on the frontend.

If you want to bypass the walkthrough and jump straight to the code it's on Github.

Init NextJS TypeScript App

First off I started out with a fresh NextJS project, nothing special, just an out of the box app configured with TypeScript following the NextJS docs.

npx create-next-app
touch tsconfig.json
npm install --save-dev typescript @types/react @types/node
npm run dev

In short we now have a NextJS app in TypeScript, we just need to start renaming .js files to .tsx

Init Amplify

If you haven't used Amplify before there are some prerequisites you may need to install and configure. See https://docs.amplify.aws/start/getting-started/installation/q/integration/react. These instructions follow on assuming you have already done these steps.

Initialise a new Amplify backend with:

amplify init

I changed a few options specifically for NextJS:

? Enter a name for the project nexttsappsync
? Enter a name for the environment dev
? Choose your default editor: Visual Studio Code
? Choose the type of app that you are building javascript
Please tell us about your project
? What javascript framework are you using react
? Source Directory Path:  ./
? Distribution Directory Path: out
? Build Command:  npm run-script build
? Start Command: npm run-script start

GraphQL Folder

Next add an API to Amplify:

amplify add api

Choose GraphQL as it's strongly typed which is ideal for our TypeScript frontend. Use the Todo generated single object with fields schema:

? Please select from one of the below mentioned services: GraphQL
? Provide API name: todoapi
? Choose the default authorization type for the API API key
? Enter a description for the API key: todoAPIKey
? After how many days from now the API key should expire (1-365): 365
? Do you want to configure advanced settings for the GraphQL API No, I am done.
? Do you have an annotated GraphQL schema? No
? Choose a schema template: Single object with fields (e.g., “Todo” with ID, name, description)

The generated schema.graphql has a Todo model as follows:

type Todo @model {
  id: ID!
  name: String!
  description: String
}

Next configure amplify codegen and generate the TypeScript types based off our GraphQL Schema.

amplify configure codegen

In the generation target language ensure you choose typescript. For the filepath I set graphql/**/*.ts because NextJS doesn't use a src folder and I wanted everything generated inside a graphql folder but you can generate to whatever filepath you like.

Enter the file name and path for the generated code I used graphql/API.ts

? Enter a file name pattern of graphql queries, mutations and subscriptions graphql/**/*.ts
? Do you want to generate/update all possible GraphQL operations - queries, mutations and subscriptions Yes
? Enter maximum statement depth [increase from default if your schema is deeply nested] 2
? Enter the file name for the generated code graphql/API.ts
? Do you want to generate code for your newly created GraphQL API Yes

GraphiQL

We now have a GraphQL API, create some Todo items for the frontend to play with by running amplify mock. Mocking will create the underlying DynamoDB tables and spin up GraphiQL on a local url. You should see something like:

AppSync Mock endpoint is running at http://192.168.86.161:20002

Open that link and you'll see GraphiQL. Create some data using a mutation as follows:

mutation MyMutation {
  createTodo(input: {name: "Put out the bins", description: "You know what to do again"}) {
    id
  }
}

Create a few more with your own todo name and description then use the following query to see your data:

query MyQuery {
  listTodos {
    items {
      id
      description
      createdAt
      name
      updatedAt
    }
  }
}

In my case that yields:

{
  "data": {
    "listTodos": {
      "items": [
        {
          "id": "39e9cb83-d936-4b05-999d-61f412d57ecb",
          "description": "You know what to do again",
          "createdAt": "2020-11-25T10:21:39.407Z",
          "name": "Put out the bins",
          "updatedAt": "2020-11-25T10:21:39.407Z"
        },
        {
          "id": "dd2d975b-be52-4a23-8dfd-03e6a4a256ae",
          "description": "The best chore!",
          "createdAt": "2020-11-25T10:22:20.674Z",
          "name": "Hoover up lounge",
          "updatedAt": "2020-11-25T10:22:20.674Z"
        },
        {
          "id": "8bce419d-39d5-425b-ab45-00f731e0454e",
          "description": "You know what to do",
          "createdAt": "2020-11-25T10:21:31.577Z",
          "name": "Put out the recycling",
          "updatedAt": "2020-11-25T10:21:31.577Z"
        }
      ]
    }
  }
}

Note the structure of the returned JSON. There is a data object, which has a listTodos object, which contains an items array. Each array item has properties that are defined by our strongly typed schema.graphql file. You'll also notice some utility properties have been added automatically by Amplify, specifically createdAt and updatedAt

React

Moving to the frontend lets get Amplify set up with our React App. First we need to install Amplify and the Amplify GraphQL library.

npm i aws-amplify @aws-amplify/api-graphql

Rename pages/index.js to pages/index.tsx then add:

import Amplify from "aws-amplify";
import awsExports from "../aws-exports";
Amplify.configure(awsExports);

Run npm run dev and it should show the out of the box NextJS app running on http://localhost:3000. The only difference being we've connected Amplify to it.

GraphQL Integration

Take a look in the graphql folder, note the queries.ts, mutations.ts, subscriptions.ts files and the API.ts file from the codegen command. Lets make our imports easier by creating the file /graphql/index.tsx and adding the following:

export * from './API';
export * from './mutations';
export * from './queries';
export * from './subscriptions';

We can now import our types and queries from the same place. Back in the pages/index.tsx file import the following:

import * as React from 'react';
import GraphQLAPI, { GRAPHQL_AUTH_MODE } from '@aws-amplify/api-graphql';
import { listTodos } from '../graphql'

Then add some code to fetch our todos using the generated listTodos query and specifying the API_KEY as the authorization mode for our GraphQL:

  React.useEffect(() => {
    const fetchTodos = async () => {
      try {
        const response = await GraphQLAPI.graphql({
          query: listTodos,
          authMode: GRAPHQL_AUTH_MODE.API_KEY
        })
        console.log(response);
      } catch (error) {
        console.log(error);
      }
    };

    fetchTodos();
  }, []);

If all went well you should see the exact same JSON response we saw in GraphiQL logged in the console. To get that displayed on the page we'll make use of React.useState() changing the code to:

  const [todos, setTodos] = React.useState(undefined);

  React.useEffect(() => {
    const fetchTodos = async () => {
      try {
        const response = await GraphQLAPI.graphql({
          query: listTodos,
          authMode: GRAPHQL_AUTH_MODE.API_KEY
        })
        console.log(response);
        setTodos(response.data);
      } catch (error) {
        console.log(error);
      }
    };

    fetchTodos();
  }, []);

We've now got the list of todos in state, we just need to map over the array in JSX. Remove the four anchor tag sections and replace with the following code which will map over the todo array and display all our todos on the page.

  <div className={styles.grid}>
    {todos?.listTodos?.items.map((todo) => {
      return (
        <a href="#" className={styles.card}>
          <h3>{todo.name}</h3>
          <p>{todo.description}</p>
        </a>
      )
    })}
  </div>

You should see the todo items you added in GraphiQL on the web page. This is good but it's all still JavaScript, we still need to add some TypeScript to make use of the GraphQL types.

We can modify the GraphQLAPI code to use the generated ListTodosQuery type from API.ts. First import it:

import { listTodos, ListTodosQuery } from '../graphql'

Then tell GraphQL to use this type:

  const response = (await GraphQLAPI.graphql({
    query: listTodos,
    authMode: GRAPHQL_AUTH_MODE.API_KEY
  })) as { data: ListTodosQuery }

Note how we need to account for the fact the response returned is a data object. If you look in the API.ts file you'll see that the type doesn't contain a data object so we need to let TypeScript know that we expect it.

export type ListTodosQuery = {
  listTodos:  {
    __typename: "ModelTodoConnection",
    items:  Array< {
      __typename: "Todo",
      id: string,
      name: string,
      description: string | null,
      createdAt: string,
      updatedAt: string,
    } | null > | null,
    nextToken: string | null,
  } | null,
};

If you try typing a period . after response in the console.log you'll see we now have full intellisense! TypeScript is telling you it expects the response to have a data object. If you select that then type another period TypeScript tells you it expects a listTodos object.

TypeScript now knows exactly what format our GraphQL API responses should be. However, down in the JSX code we've some more work to do. At the moment our API response is TypeScript aware but the JSX isn't, when mapping over the todos TypeScript can't infer what the types should be.

We can fix that by telling React.useState what types to expect:

const [todos, setTodos] = React.useState<ListTodosQuery | undefined>(undefined);

Here we've told TypeScript the same as the API to expect ListTodosQuery as the type but also that it could be undefined if we don't yet have any data.

Now if you go to the JSX and start typing you'll see all the same lovely intellisense!

e.g. {todo.name}

This is great but if you take a closer look at the intellisense in VSCode you'll see some __typename entries. Looking back at the ListTodosQuery you note how that is indeed part of the type, but it's not data that we desire when working in React, in fact it's going to cause you problems further down the line. We can clean it up though.

TypeScript Omit & Exclude

Fortunately we can automate this clean up in a nice way that won't break as we amend our graphql.schema file by using TypeScripts Utility types Omit & Exclude.

Create a new file graphql/APITypes.ts and add the export to your graphql/index.ts file.

Next create a new file graphql/DeepOmit.ts and paste in the following:

type Primitive =
  | string
  | Function
  | number
  | boolean
  | symbol
  | undefined
  | null;

type DeepOmitArray<T extends any[], K> = {
  [P in keyof T]: DeepOmit<T[P], K>;
};

export type DeepOmit<T, K> = T extends Primitive
  ? T
  : {
      [P in Exclude<keyof T, K>]: T[P] extends infer TP
        ? TP extends Primitive
          ? TP // leave primitives and functions alone
          : TP extends any[]
          ? DeepOmitArray<TP, K> // Array special handling
          : DeepOmit<TP, K>
        : never;
    };

Stricly speaking DeepOmit isn't necessary in this example, you could just use Omit, however, when your schema becomes more complicated you may find DeepOmit will serve you better.

Back in APITypes.ts we'll import DeepOmit and our Amplify generated types:

import { DeepOmit } from './DeepOmit';
import {
  ListTodosQuery,
} from './API';

We can now create base types from the generated Amplify types filtering out the null entries and __typename properties. The following code does just that for the generated GetTodoQuery creating a new type named TodoType.

export type TodoType = DeepOmit<
  Exclude<GetTodoQuery['getTodo'], null>,
  '__typename'
>;

This will generate a type as follows:

type TodoType = {
    id: string;
    name: string;
    description: string;
    completed: boolean;
    createdAt: string;
    updatedAt: string;
}

To make use of the type in React, import it:

import {listTodos, ListTodosQuery, TodoType} from '../graphql'

and update the JSX telling TypeScript that each todo item is of the TodoType:

  <div className={styles.grid}>
    {todos?.listTodos?.items.map((todo: TodoType) => {
      return (
        <div className={styles.card}>
          <h3>{todo.name}</h3>
          <p>Find in-depth information about Next.js features and API.</p>
        </div>
      )
    })}
  </div>

Intellisense now works without the erroeneous null and __typename properties.

Changing Schema

So what happens when we extend our schema.graphql file? Let's find out.

In schema.graphl add a completed flag, so the schema becomes:

type Todo @model {
  id: ID!
  name: String!
  description: String
  completed: Boolean!
}

If you are still running amplify mock then you'll notice something neat, the code generation updates automatically as soon as you save the file. If you look in API.ts you see the new completed boolean in the type definitions.

What about APITypes.ts? Well that file hasn't been updated but it doesn't need to. It just pulls in the updated types from API.ts and removes null and __typename.

Let's try this out, back in our React code lets add the status of the completed flag in our UI.

   <div className={styles.card} key={todo.id}>
      <h3>{todo.name}</h3>
      <p>{todo.description}</p>
      <p>{`Status: ${todo.completed}`}</p>
   </div>

When adding the status and typing the period you should have noticed how TypeScript suggested completed as an option!

If you look in the browser though you'll see status is null because we haven't set any value yet for the completed status and null is an appropriate alternative value. Let's fix that in GraphiQL

mutation MyMutation {
  updateTodo(input: {id: "8bce419d-39d5-425b-ab45-00f731e0454e", completed: true}) {
    id
  }
}

Sorted!

Summary

Our app now has a nice contract between the backend and the frontend using the GraphQL.schema file as the glue and delivers on the promise of preventing runtime errors for both backend and frontend.

Inspiration

This walkthrough is based on the groundwork of these excellent articles:

Multiple frontends with Amplify Console

Dave Hudson — Sat, 30 May 2020 11:55:36 +0000

If you have an Amplify Console app with a cloud backend and need to connect a second app to it, this is the tutorial for you.

AWS Amplify is a fantastic solution for building secure, scalable full stack applications. The concept is that as you build out your frontend app, you also scaffold out your backend in the cloud using the Amplify CLI, storing the resulting config in a single Git repository. Amplify Console then provides a Git-based workflow for deploying and hosting your fullstack serverless app.

The Amplify documentation covers this scenario in detail. What if you want to connect more than one app to your backend though? The schema for all of your cloud backend is in the first repo. How do you connect to say an iOS app, Android app or as in my case another React app to the cloud backend?

The Amplify team have provided the basic commands to enable you to achieve this but the documentation and use cases are lagging, leaving you to search out the specifics yourself.

Connecting a second app

I'll assume you've already created your full-stack app in Amplify Console with a frontend web app and a cloud backend app. Now you want to get cracking on that second app and get it talking to your single backend.

If you haven't you best start with the Getting Started Amplify Docs https://docs.amplify.aws/start/q/integration/js

Scaffold out your app

In my case I'm creating a Gatsby app so I ran the command gatsby new gatsby-site.

Pull down the backend

Next you need to pull down the backend from Amplify. In Amplify Console select your app, select the Backend environements tab and click the Edit backend link. This will reveal the command you need to run in order to pull down the backend. In my case amplify pull --appId dt9kkffvqgojy --envName dev.

Run this command and follow the prompts as normal but for the final question "Do you plan on modifying this backend?" answer no. This ensures the amplify folder is not copied to your second app. Whilst the docs say things will work if you have the amplify folder in your second app, it can lead to conflicts when pushing code.

? Do you want to use an AWS profile? Yes
? Please choose the profile you want to use Default
Amplify AppID found: dt9kkffvqgojy. Amplify App name is: test-app
Backend environment dev found in Amplify Console app: test-app
? Choose your default editor: Visual Studio Code
? Choose the type of app that you're building javascript
Please tell us about your project
? What javascript framework are you using react
? Source Directory Path:  src
? Distribution Directory Path: build
? Build Command:  npm run-script build
? Start Command: npm run-script start

? Do you plan on modifying this backend? No

Download backend schema

Most likely you'll also have a schema for your backend that you need to work with in your second app e.g if you've created an API. You'll need to also download that.

Jump back into the Amplify Console and click on your backend environment name, in my case it is Dev and click on the API tab. I have a GraphQL API so I clicked the View in AppSync button which opens the AppSync console. Click the Schema navigation link and then the Export schema button. Select the schema.json option and save it in the root of your second app.

You will now be able to run amplify codegen add to configure your second project with your API to generate the GraphQL mutations, queries and subscriptions so your second app can talk to your amplify backend.

For more information on codgen see the docs https://docs.amplify.aws/cli/graphql-transformer/codegen

At this point you have everything you need to develop locally on your second app. If you need to work with a different environment, simply run the amplify pullcommand, update schema.json and run the amplify codegen command again.

Configuring C.I builds

Working in development locally is only part of the solution. As you move closer towards deployment you'll notice some issues. Specifically:

You can't use your AWS Profile in continuous integration like you do on your local machine
The interactive prompts from the amplify pull command need to be automatically answered somehow

The solution to these problems is that you need to run the commands in headless mode https://docs.amplify.aws/cli/usage/headless.

Update @amplify/cli in C.I

Amplify pull is a relatively new command, so older versions of the Amplify CLI have no clue what to do when you run the command. So step 1 before you do anything else and to help you avoid losing many an hour to this quirk as I did, update the Amplify CLI in C.I.

For some reason the default version of the Amplify CLI running in C.I of the Amplify Console is 1.12.0, the latest version being 4.21.0. To fix this go into the Build settings section of the Amplify console for your project (available in the sidebar menu). Scroll to the bottom and edit the Build image settings, then choose to Add package version override. Select Amplify CLI and set the version to canary.

This will update @amplify/cli during the Cloning repository stage of your build to the latest version.

2020-05-28T12:51:32.924Z [INFO]: # Ensuring NPM package '@aws-amplify/cli' is version: 'canary'
2020-05-28T12:51:40.174Z [INFO]: # Patching NPM package '@aws-amplify/cli' from 1.12.0 to canary...
2020-05-28T12:52:45.411Z [INFO]: # Done patching NPM package '@aws-amplify/cli'

Headless Amplify pull

Now that Amplify Console can understand the amplify pull command we can run it in headless mode by passing the --yes flag at the end. This means we don't get any of the question prompts and instead need to provide all of the parameters to the command.

At the bottom of the documentation on headless CLI usage there is a section on amplify pull that provides an example bash script. We'll use that as the basis for our C.I build.

In the root of your project create a bash file named amplify-pull.sh (can be named whatever you want). Then set execute permissions by running chmod u+x amplify-pull.sh.

YAML configuration

Next we need to make a few amends to the build config in Amplify Console to call our bash script.

In the build settings edit the amplify.yml file (you can also download it and put it in the root of your project if you prefer). In the frontend phase of the build we need to tell Amplify Console to run our bash script in the preBuild stage, e.g

version: 0.1
frontend:
  phases:
    preBuild:
      commands:
        - ./amplify-pull.sh "${ACCESS_KEY_ID}" "${SECRET_ACCESS_KEY}" "${AWS_BRANCH}"
        - npm ci

In the code above we specify that we want to run the command ./amplify-pull.sh which will pass everything over to our bash script. The bash script requires a number of environment variables which you'll note we also pass in via the YAML file. They are:

ACCESS_KEY_ID
SECRET_ACCESS_KEY
AWS_BRANCH (not strictly required but handy)

You'll need to set up these environment variable values within the Amplify Console. You'll find the values in your .aws/credentials file on your local machine. These are the credentials you may have set up when running amplify configure.

See docs on setting environment variables in Amplify Console https://docs.aws.amazon.com/amplify/latest/userguide/environment-variables.html

The bash file

Finally back to the empty bash file we created. The exact config of your bash file will depend on your specific needs. In my case I'm building a Gatsby site so the DistributionDir is set to public as that is where Gatsby likes to place the files when building for production. On the whole though the bash files should be fairly similar.

It's important to know that environment variables are read in a bash script based on the order they are passed in. So:

ACCESS_KEY_ID was passed in first so is available as $1
SECRET_ACCESS_KEY as $2
AWS_BRANCH as $3

The first part of the code checks $3 to check the current Git branch. This enables deploying different backends depending on which branch you are on with the value simply passed on as the $AWSENV variable to the Amplify object. Also note that projectName and appId are the values of the Amplify app in the other project that is fully connected to Amplify.

The rest of the code is essentially the same as the example in the documentation but note that accessKeyId and secretAccessKey take their values from the environment variables we passed in.

One additional step added is the amplify codegen command, not stricly necessary as we did that locally but it does ensure the correct code is deployed.

#!/bin/bash
set -e
IFS='|'

# Use AWS_BRANCH var to check which backend to pull
if [ "$3" = "master" ]; then
    AWSENV="prod" 
else
    AWSENV="qa"
fi

REACTCONFIG="{\
\"SourceDir\":\"src\",\
\"DistributionDir\":\"public\",\
\"BuildCommand\":\"npm run-script build\",\
\"StartCommand\":\"npm run-script start\"\
}"

AWSCLOUDFORMATIONCONFIG="{\
\"configLevel\":\"project\",\
\"useProfile\":false,\
\"profileName\":\"default\",\
\"accessKeyId\":\"$1\",\
\"secretAccessKey\":\"$2\",\
\"region\":\"eu-west-2\"\
}"

AMPLIFY="{\
\"projectName\":\"admin-app\",\
\"appId\":\"dt9kkffvqgojy\",\
\"envName\":\"$AWSENV\",\
\"defaultEditor\":\"code\"\
}"

FRONTEND="{\
\"frontend\":\"javascript\",\
\"framework\":\"react\",\
\"config\":$REACTCONFIG\
}"

PROVIDERS="{\
\"awscloudformation\":$AWSCLOUDFORMATIONCONFIG\
}"

amplify pull --amplify $AMPLIFY --frontend $FRONTEND --providers $PROVIDERS --yes
amplify codegen

That's it! You should now be able to develop and publish your second app via continuous integration connected to the amplify cloud backend from your main app codebase.

In truth it isn't that hard to set up, it is just that none of this is fully documented as yet and pitfalls like the outdated Amplify CLI in Amplify Console may prevent you knowing this is even possible at all.