Getting Started

AWS Amplify is Amazon's take on backendless services such as Google Firebase and others. The main aim is to provide (frontend) developers a service which allows them to focus on programming (web or mobile) apps and spend (almost) no time to configure the backend services like web servers or databases.

AWS Amplify was released back in 2018 as Amplify Console and steadily grew into a mature service catalog so let's get started.

Code repository

The code in this step-by-step guide is available as open-source on Github:
https://github.com/expressflow/aws-amplify-react

Feel free to dig right into the code - every part of this blog post is separated in a different branch.

This is part 1 of a series of posts:

Part 1: Getting started - this part
Part 2: Authentication (Coming soon)
Part 3: GraphQL Backend (Coming soon)

Setup

To get started with AWS Amplify you need:

Node.js v10.0 or later
npm v5.0 or later
create-react-app
a coup of coffee

Frontend Setup

To kickoff the app development just create a new react app as you would normally do:

create-react-app . --template typescript

This creates a new react app with TypeScript in the current directory.

Nothing fancy here and pretty clean from a "vendor-lock-in" perspective. +1 for AWS Amplify for that.

Add AWS Amplify CLI

To be able to create a AWS Amplify project you need to have an AWS Account.

If you haven't, you can create one right here.

To get started with AWS Amplify CLI you need to install it globally on your system:

npm install -g @aws-amplify/cli

After successfully installing the aws-amplify-cli you need to configure it:

amplify configure

This opens a browser and asks you to log in to your AWS Management console. After finishing this step a setup wizard in the console starts:

Follow these steps to set up access to your AWS account:

Sign in to your AWS administrator account:
https://console.aws.amazon.com/
Press Enter to continue

Specify the AWS Region
? region:  
  us-east-1 
  us-east-2 
  us-west-2 
❯ eu-west-1 
  eu-west-2 
  eu-central-1 
  ap-northeast-1

After choosing your region a new AWS user is created - just follow along with the default settings and you are good to go.

Specify the username of the new IAM user:
? user name:  amplify-RANDOM-CODE
Complete the user creation using the AWS console
https://console.aws.amazon.com/iam/home?region=eu-west-1#/users$new?step=final&accessKey&userNames=amplify&permissionType=policies&policies=arn:aws:iam::aws:policy%2FAdministratorAccess
Press Enter to continue

Enter the access key of the newly created user:
? accessKeyId:  ********************
? secretAccessKey:  ****************************************
This would update/create the AWS Profile in your local machine
? Profile Name:  default

Successfully set up the new user.

Awesome! You are set up. Let's initialize the new backend.

Backend Setup

Right in your React app enter the following to initialize the Amplify backend

amplify init

This starts the initialization of the amplify backend. To setup a React app in Amplify simply choose the following settings

Note: It is recommended to run this command from the root of your app directory
? Enter a name for the project awsamplifyreact
? Enter a name for the environment dev
? 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
Using default provider  awscloudformation

For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html

? Do you want to use an AWS profile? Yes
? Please choose the profile you want to use default

Cool! After successfully running this command you might notice a new folder amplify in your React app. You can find all settings there.

Let's briefly recap what we did here:

Create React app with TypeScript
Connected our AWS Account to the AWS Amplify CLI
Initialized the AWS Amplify Project in our React app

Pretty straight forward. Let's finally add some basic functionality.

amplify add api

This starts the API wizard which you can answer with the following settings

? Please select from one of the below mentioned services: GraphQL
? Provide API name: products
? Choose the default authorization type for the API API key
? Enter a description for the API key: demo
? After how many days from now the API key should expire (1-365): 7
? 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: One-to-many relationship (e.g., “Blogs” with “Posts” and “Comments”)

The following types do not have '@auth' enabled. Consider using @auth with @model
         - Blog
         - Post
         - Comment
Learn more about @auth here: https://docs.amplify.aws/cli/graphql-transformer/directives#auth

Ok what did we do here?

We created a GraphQL API named products which uses an API key for authentication.
Then autogenerated schema consists of a one-to-many relationship storing Blogs, Posts and Comments - more on this in a moment.

When you take a look at your local code, there will be some new files freshly generated for you from the amplify cli

ls amplify/backend/api/products

build
parameters.json
resolvers
schema.graphql
stacks
transform.conf.json

Open the schema.graphql file in your amplify/backend/api/products folder

type Blog @model {
  id: ID!
  name: String!
  posts: [Post] @connection(keyName: "byBlog", fields: ["id"])
}

type Post @model @key(name: "byBlog", fields: ["blogID"]) {
  id: ID!
  title: String!
  blogID: ID!
  blog: Blog @connection(fields: ["blogID"])
  comments: [Comment] @connection(keyName: "byPost", fields: ["id"])
}

type Comment @model @key(name: "byPost", fields: ["postID", "content"]) {
  id: ID!
  postID: ID!
  post: Post @connection(fields: ["postID"])
  content: String!
}

Hint: If you schema looks different you probably selected a different setting in
"Choose a schema template"
in the previous wizard. Check twice to be sure.

This sample examines the principles of GraphQL relationships, keys, models and more. To get more samples of GraphQL refer to our GraphQL by example (Coming soon).

Change the default schema to

type Type @model {
  id: ID!
  name: String!
  products: [Product] @connection(keyName: "byType", fields: ["id"])
}

type Product @model @key(name: "byType", fields: ["typeID"]) {
  id: ID!
  name: String!
  typeID: ID!
  type: Type @connection(fields: ["typeID"])
  articles: [Article] @connection(keyName: "byProduct", fields: ["id"])
}

type Article @model @key(name: "byProduct", fields: ["productID", "description"]) {
  id: ID!
  productID: ID!
  product: Product @connection(fields: ["productID"])
  description: String!
}

Now check the changes by typing

amplify status

This should display your local changes which are ready to be pushed to the AWS cloud

Scanning for plugins...
Plugin scan successful

Current Environment: dev

| Category | Resource name | Operation | Provider plugin   |
| -------- | ------------- | --------- | ----------------- |
| Api      | products      | Create    | awscloudformation |

Just do so by entering

amplify push

Once again this triggers a console wizard which asks you to generate some code for you. Answer the questions with the following settings

? 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
⠙ Updating resources in the cloud. This may take a few minutes...

Congratulations! You successfully released a first React app in the AWS cloud with AWS Amplify!

AWS Amplify React example