GraphQL is becoming a popular way to use APIs in modern web and mobile apps.

However, learning new things is always time-consuming and without getting your hands dirty, it’s very difficult to understand the nuances of a new technology.

So, we have put together a powerful and concise tutorial that will guide you through setting up a GraphQL backend and integration into your React app in the shortest time possible. This tutorial is light on opinions, so that once you get a hang of the fundamentals, you can go on and tailor your workflow.

Key topics and takeaways:

• Authentication
• GraphQL API with AWS AppSync
• Hosting
• Working with multiple environments
• Removing services
  

What will we be building?

We will build a basic real-time Restaurant CRUD app using authenticated GraphQL APIs. Click here to try the deployed version of the app to see what we’ll be building.

Will this tutorial teach React or GraphQL concepts as well?

No. The focus is to learn how to use AWS Amplify to build cloud-enabled, real-time web applications. If you are new to React or GraphQL, we recommend going through the official documentation and then coming back here.

What do I need to take this tutorial?

• Node >= v10.9.0
• NPM >= v6.9.0 packaged with Node.
  

Getting started - Creating the application

To get started, we first need to create a React project using the create-react-app boilerplate:

CODE: https://gist.github.com/velotiotech/350047bf60b98af065e44a1f4536a70f.js

Let’s now install the AWS Amplify and AWS Amplify React bindings and try running the application:

CODE: https://gist.github.com/velotiotech/a782fe4140cbb9ab9b4b4db45ef86b4c.js

If you have initialized the app with Typescript and see errors while using

aws-amplify-react, add aws-amplify-react.d.ts to src with:

CODE: https://gist.github.com/velotiotech/ba0708301bcbe3d82d19199bc13fac13.js

Installing the AWS Amplify CLI and adding it to the project

To install the CLI:

CODE: https://gist.github.com/velotiotech/6e07580a9fe1e1ccf12d19e5186114f4.js

Now we need to configure the CLI with our credentials:

CODE: https://gist.github.com/velotiotech/0f4a56fe9d39c4f89d18c4aeff4a4c18.js

If you’d like to see a video walkthrough of this process, click here

Here we'll walk you through the amplify configure setup. After you sign in to the AWS console, follow these steps:

• Specify the AWS region: ap-south-1 (Mumbai) <Select the region based on your location. Click here for reference>
• Specify the username of the new IAM user: amplify-app <name of="" your="" app=""></name>
  

In the AWS Console, click Next: Permissions, Next: Tags, Next: Review, and Create User to create the new IAM user. Then, return to the command line and press Enter.

• Enter the credentials of the newly created user:
  accessKeyId: <your_access_key_id> </your_access_key_id>
  ‍secretAccessKey: <your_secret_access_key></your_secret_access_key>

• Profile Name: default
  

To view the newly created IAM user, go to the dashboard. Also, make sure that your region matches your selection.

To add amplify to your project:

CODE: https://gist.github.com/velotiotech/b98d8e323759c4d0e7d3fa04bbcd4c4a.js

Answer the following questions:

• Enter a name for the project: amplify-app <name of="" your="" app=""></name>‍
• Enter a name for the environment: dev <name of="" your="" environment=""></name>‍
• Choose your default editor: Visual Studio Code <your default editor=""></your>‍
• Choose the type of app that you’re building: javaScript‍
• What JavaScript framework are you using: React‍
• Source Directory Path: src‍
• Distribution Directory Path: build‍
• Build Command: npm run build (for macOS/Linux), npm.cmd run-script build (for Windows)‍
• Start Command: npm start (for macOS/Linux), npm.cmd run-script start (for Windows)‍
• Do you want to use an AWS profile: Yes‍
• Please choose the profile you want to use: default
  

Now, the AWS Amplify CLI has initialized a new project and you will see a new folder: amplify. This folder has files that hold your project configuration.

CODE: https://gist.github.com/velotiotech/9bcea124626106bf65be6eb7f406bb63.js

Adding Authentication

To add authentication:

CODE: https://gist.github.com/velotiotech/1833a2e3286f648369b99e64b9fdc148.js

When prompted, choose:

• Do you want to use default authentication and security configuration: Default configuration‍
• How do you want users to be able to sign in when using your Cognito User Pool: Username‍
• What attributes are required for signing up: Email
  

Now, let’s run the push command to create the cloud resources in our AWS account:

CODE: https://gist.github.com/velotiotech/bccb5213b6eeef35d07caae1f16813bb.js

To quickly check your newly created Cognito User Pool, you can run

CODE: https://gist.github.com/velotiotech/1ab065695ad58c1cd43c8542984610c1.js

To access the AWS Cognito Console at any time, go to the dashboard. Also, ensure that your region is set correctly.

Now, our resources are created and we can start using them.

The first thing is to connect our React application to our new AWS Amplify project. To do this, reference the auto-generated aws-exports.js file that is now in our src folder.

To configure the app, open App.tsx and add the following code below the last import:

CODE: https://gist.github.com/velotiotech/efcd4f75f34d8ac23bb2c1378b55a48e.js

Now, we can start using our AWS services.
To add the Authentication flow to the UI, export the app component by wrapping it with the authenticator HOC:

CODE: https://gist.github.com/velotiotech/ca3d34ad37c23aa181229b2f8ba11f53.js

Now, let’s run the app to check if an Authentication flow has been added before our App component is rendered.

This flow gives users the ability to sign up and sign in. To view any users that were created, go back to the Cognito dashboard. Alternatively, you can also use:

CODE: https://gist.github.com/velotiotech/2daeea79a27c003c38b3bf9c130ad41f.js

The withAuthenticator HOC is a really easy way to get up and running with authentication, but in a real-world application, we probably want more control over how our form looks and functions. We can use the aws-amplify/Auth class to do this. This class has more than 30 methods including signUp, signIn, confirmSignUp, confirmSignIn, and forgotPassword. These functions return a promise, so they need to be handled asynchronously.

Adding and Integrating the GraphQL API

To add GraphQL API, use the following command:

CODE: https://gist.github.com/velotiotech/a7b174b87d426f94e5c2ab78e3cfada2.js

Answer the following questions:

• Please select from one of the below mentioned services: GraphQL‍
• Provide API name: RestaurantAPI‍
• Choose an authorization type for the API: API key‍
• Do you have an annotated GraphQL schema: No‍
• Do you want a guided schema creation: Yes‍
• What best describes your project: Single object with fields (e.g., “Todo” with ID, name, description)‍
• Do you want to edit the schema now: Yes
  

When prompted, update the schema to the following:

CODE: https://gist.github.com/velotiotech/7b0f3c2f5368958aba73fb479e7c86fa.js

Next, let’s run the push command to create the cloud resources in our AWS account:

CODE: https://gist.github.com/velotiotech/1473e5b86951dc6fbe661839611dfb1d.js

• Are you sure you want to continue: Yes‍
• Do you want to generate code for your newly created GraphQL API: Yes‍
• Choose the code generation language target: typescript‍
• Enter the file name pattern of graphql queries, mutations and subscriptions: src/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: src/API.ts
  

Notice your GraphQL endpoint and API KEY. This step has created a new AWS AppSync API and generated the GraphQL queries, mutations, and subscriptions on your local. To check, see src/graphql or visit the AppSync dashboard. Alternatively, you can use:

CODE: https://gist.github.com/velotiotech/de9a3a9e289724e734d92ac3bfdfa9d2.js

Please select from one of the below mentioned services: GraphQL

Now, in the AppSync console, on the left side click on Queries. Execute the following mutation to create a restaurant in the API:

CODE: https://gist.github.com/velotiotech/eb95d957be36599f4d586ddc84cf319d.js

Now, let’s query for the restaurant:

CODE: https://gist.github.com/velotiotech/f243d195686411991ea267f7e921ef86.js

We can even search / filter data when querying:

CODE: https://gist.github.com/velotiotech/0bc4abbf3d6885c92d7b99111aad657d.js

Now that the GraphQL API is created, we can begin interacting with it from our client application. Here is how we’ll add queries, mutations, and subscriptions:

CODE: https://gist.github.com/velotiotech/8e436a746dbbd49aa01f2ae14ffd1a93.js

Finally, we have our app ready. You can now sign-up,sign-in, add new restaurants, see real-time updates of newly added restaurants.

Hosting

The hosting category enables you to deploy and host your app on AWS.

CODE: https://gist.github.com/velotiotech/ce72149014b16bb84452b9974b2c3c5e.js

• Select the environment setup: DEV (S3 only with HTTP)‍
• hosting bucket name: <YOUR_BUCKET_NAME>‍
• index doc for the website: index.html‍
• error doc for the website: index.html
  

Now, everything is set up & we can publish it:

CODE: https://gist.github.com/velotiotech/d4045cf59736623e2ef0f367747fc30f.js

Working with multiple environments

You can create multiple environments for your application to create & test out new features without affecting the main environment which you are working on.

When you use an existing environment to create a new environment, you get a copy of the entire backend application stack (CloudFormation) for the current environment. When you make changes in the new environment, you are then able to test these new changes in the new environment & merge only the changes that have been made since the new environment was created.

Let's take a look at how to create a new environment. In this new environment, we'll add another field for the restaurant owner to the GraphQL Schema.

First, we'll initialize a new environment using amplify init:

CODE: https://gist.github.com/velotiotech/e6f5e3ebcc7f4856b47aac2dbdb5607c.js

• Do you want to use an existing environment: N‍
• Enter a name for the environment: apiupdate‍
• Do you want to use an AWS profile: Y
  

Once the new environment is initialized, we should be able to see some information about our environment setup by running:

CODE: https://gist.github.com/velotiotech/9ab009d54d2c92ec453991ca66d6cfd8.js

Now, add the owner field to the GraphQL Schema in

CODE: https://gist.github.com/velotiotech/1cd929f04e5a039fe80f164e27640b19.js

CODE: https://gist.github.com/velotiotech/c49474971125ab91532293ca22e6e3f1.js

Run the push command to create a new stack:

CODE: https://gist.github.com/velotiotech/b4371b77cc99563b2b9fb9584d4c94c2.js

After testing it out, it can be merged into our original dev environment:

CODE: https://gist.github.com/velotiotech/e3e52bec2bd12719b40723f5c5dc86ea.js

• Do you want to update code for your updated GraphQL API: Y‍
• Do you want to generate GraphQL statements: Y
  

Removing Services

If at any time, you would like to delete a service from your project & your account, you can do this by running the amplify remove command:

CODE: https://gist.github.com/velotiotech/c407e1b3adbcf8ab72b89044adebfe2d.js

If you are unsure of what services you have enabled at any time, amplify status will give you the list of resources that are currently enabled in your app.

Sample code

The sample code for this blog post with an end to end working app is available here.

Summary

Once you've worked through all the sections above, your app should now have all the capabilities of a modern app, and building GraphQL + React apps should now be easier and faster with Amplify.