AWS Amplify

Console User Guide

AWS Amplify: Console User Guide

Copyright © 2019 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
 AWS Amplify Console User Guide

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not
Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or
discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may
or may not be affiliated with, connected to, or sponsored by Amazon.
 AWS Amplify Console User Guide

Table of Contents
What is the AWS Amplify Console? ...................................................................................................... 1
Get started ................................................................................................................................ 1
Amplify Console Features ............................................................................................................ 1
Modern Web Applications ........................................................................................................... 1
Getting Started .................................................................................................................................. 3
Step 1: Connect Repository ......................................................................................................... 3
Step 2: Confirm Build Settings for the Front End ........................................................................... 4
Step 3: Confirm Build Settings for the Backend ............................................................................. 5
Step 4: Add Environment Variables (Optional) ............................................................................... 6
Step 5: Save and Deploy ............................................................................................................. 6
Next Steps ................................................................................................................................ 7
Getting Started with Fullstack Deployments .......................................................................................... 8
Step 1: Deploy a fullstack sample ................................................................................................ 8
Step 2: Explore the Fullstack App ................................................................................................. 9
Step 3: Add a GraphQL backend ................................................................................................ 11
Next steps: Set up feature branch deployments ........................................................................... 12
Setting Up Custom Domains .............................................................................................................. 13
Adding a Custom Domain Managed in Amazon Route 53 ............................................................... 13
Adding a Custom Domain Managed by a Third-Party DNS Provider ................................................. 14
Adding Subdomains .................................................................................................................. 16
Troubleshooting Guide .............................................................................................................. 17
Technical Terminology ...................................................................................................... 17
How do I verify that my CNAME resolves? ........................................................................... 19
My domain hosted with a third party is stuck in Pending Verification state ............................... 20
My domain hosted with AWS Route53 is stuck in Pending Verification state ............................. 20
CNAMEAlreadyExistsException Error .................................................................................... 21
Connecting to Third-Party Custom Domains ........................................................................................ 22
Connecting to a GoDaddy Domain .............................................................................................. 22
Connecting to a Google Domain ................................................................................................ 25
Configuring Build Settings ................................................................................................................. 26
YML Specification Syntax .......................................................................................................... 26
Branch-Specific Build Settings .................................................................................................... 27
Navigating to a Subfolder ......................................................................................................... 28
Deploying the Backend with Your Front End ................................................................................ 28
Setting the Output Folder ......................................................................................................... 28
Installing Packages as Part of Your Build ..................................................................................... 28
Using a Private npm Registry ..................................................................................................... 29
Installing OS packages .............................................................................................................. 29
Key-value storage for every build ............................................................................................... 29
Disable Automatic builds ........................................................................................................... 29
Feature Branch Deployments ............................................................................................................. 31
Team workflows with Amplify CLI backend environments .............................................................. 31
Feature branch workflow ................................................................................................... 17
GitFlow workflow ............................................................................................................. 37
Per-developer sandbox ...................................................................................................... 37
Pattern-based feature branch deployments ................................................................................. 39
Manual Deploys ............................................................................................................................... 42
Drag and Drop ......................................................................................................................... 42
Amazon S3 or any URL ............................................................................................................. 42
One-click Deploy Button ................................................................................................................... 44
Add 'Deploy to Amplify Console' button to your repository or blog ................................................. 44
End-to-End Testing ........................................................................................................................... 45
Tutorial: Set up end-to-end tests with Cypress ............................................................................. 45
Add tests to your existing Amplify app ....................................................................................... 46

iii
 AWS Amplify Console User Guide

Disabling tests ......................................................................................................................... 46

Using Redirects ................................................................................................................................ 48
Types of Redirects .................................................................................................................... 48
Parts of a Redirect ................................................................................................................... 49
Order of Redirects .................................................................................................................... 49
Simple Redirects and Rewrites ................................................................................................... 50
Redirects for Single Page Web Apps (SPA) ................................................................................... 51
Reverse Proxy Rewrite ............................................................................................................... 51
Trailing slashes and Clean URLs ................................................................................................. 51
Placeholders ............................................................................................................................ 52
Query Strings and Path Parameters ............................................................................................ 52
Region-based Redirects ............................................................................................................. 52
Restricting Access ............................................................................................................................. 54
Environment Variables ...................................................................................................................... 55
Setting Environment Variables ................................................................................................... 55
Accessing Environment Variables ................................................................................................ 56
Amplify Console Environment Variables ...................................................................................... 56
Custom Headers ............................................................................................................................... 58
Example: Security Headers ........................................................................................................ 58
Incoming Webhooks ......................................................................................................................... 60
Access logs ...................................................................................................................................... 62
Analyzing access logs ................................................................................................................ 62
Custom Builds .................................................................................................................................. 63
Custom Build Images ................................................................................................................ 63
Configuring a Custom Build Image ..................................................................................... 63
Custom Build Image Requirements ..................................................................................... 64
Live Package Updates ............................................................................................................... 64
Configuring Live Updates .................................................................................................. 64
CloudFormation Support ................................................................................................................... 66
Creating a Service Role ..................................................................................................................... 67
Step 1: Login to the IAM Console ............................................................................................... 67
Step 2: Create Amplify role ....................................................................................................... 67
Step 3: Return to the Amplify Console ........................................................................................ 67
Managing Your App's Performance ..................................................................................................... 69

iv
 AWS Amplify Console User Guide
Get started

Welcome to the AWS Amplify

Console
The AWS Amplify Console provides a Git-based workflow for hosting fullstack serverless web apps with
continuous deployment. A fullstack serverless app consists of a backend built with cloud resources
such as GraphQL or REST APIs, file and data storage, and a frontend built with single page application
frameworks such as React, Angular, Vue, or Gatsby.

AWS Amplify Console supports common Single Page App (SPA) frameworks (e.g. React Angular, Vue.js,
Ionic, Ember), as well as static-site generators like Gatsby, Eleventy Hugo, VuePress, and Jekyll.

Get started
To get started with Amplify Console connect your repository (p. 3) (GitHub, BitBucket, GitLab,
and AWS CodeCommit) to set up continuous deployment. Alternatively, start with one of our fullstack
samples (p. 8). Amplify Console automatically detects the front end build settings along with any
backend functionality provisioned with the Amplify CLI (command-line toolchain for creating serverless
backends).

Amplify Console Features

With the Amplify Console, you can do the following:

• Manage production and staging environments for your frontend and backend by connecting new
branches. See feature branch deployments (p. 31).
• Connect your custom domain. If you manage your domain in Amazon Route 53, the Amplify Console
automatically connects the root (yourdomain.com), www subdomains (www.yourdomain.com), and
branch (https://dev.yourdomain.com) subdomains. See custom domains (p. 13).
• Preview changes during code reviews by setting up Pull-Request Previews.
• Improve your app quality with end to end tests. See End-to-End Testing (p. 45).
• Password protect your web app so you can work on new features without making them publicly
accessible. See restricting access (p. 54).
• Set up rewrites and redirects to maintain SEO rankings and route traffic based on your client app
requirements. See redirects (p. 48).

Also:

• Instant cache invalidations ensure your app is updated on every code commit instantly.
• Atomic deployments eliminate maintenance windows by ensuring that the web app is only updated
when the entire deployment has finished. This eliminates scenarios where files fail to upload properly.
• Get screen shots of your app rendered on different mobile devices to pinpoint layout issues.

Modern Web Applications

Modern web applications are constructed as single page web applications that package all application
components into static files. Traditional client-server web architectures led to poor experiences--

1
 AWS Amplify Console User Guide
Modern Web Applications

every button click or search required a round trip to the server, re-rendering the entire application.
Modern web apps offer a native app-like user experience by serving the app front end, or user interface,
efficiently to browsers as prebuilt HTML/JavaScript files that can then invoke backend functionality
without reloading the page.

Modern web applications functionality is often spread across multiple places--such as databases,
authentication services, front end code running in the browser, and backend business logic, or AWS
Lambda functions, running in the cloud. This makes application deployments complex and time-
consuming as developers need to carefully coordinate deployments across the front end and backend to
avoid partial or failed deployments. The AWS Amplify Console simplifies deployment of the front end
and backend in a single workflow.

2
 AWS Amplify Console User Guide
Step 1: Connect Repository

Getting Started with Existing Code

In this walkthrough, you learn how to continuously build, deploy, and host a modern web app. Modern
web apps include Single Page App (SPA) frameworks (for example, React, Angular, or Vue) and static-site
generators (SSGs) (for example, Hugo, Jekyll, or Gatsby).

To get started, log in to the Amplify Console and choose Get Started under Deploy.

Step 1: Connect Repository

Connect your GitHub, Bitbucket, GitLab, or AWS CodeCommit repositories. You also have the
option of manually uploading your build artifacts without connecting a Git repository (see Manual
Deploys (p. 42)). After you authorize the Amplify Console, Amplify fetches an access token from the
repository provider, but it doesn't store the token on the AWS servers. Amplify accesses your repository
using deploy keys installed in a specific repository only.

After you connect the repository service provider, choose a repository, and then choose a corresponding
branch to build and deploy.

3
 AWS Amplify Console User Guide
Step 2: Confirm Build Settings for the Front End

Step 2: Confirm Build Settings for the Front End

For the selected branch, Amplify inspects your repository to automatically detect the sequence of build
commands to be executed.

Important: Verify that the build commands and build output directory (that is, artifacts > baseDirectory)
is accurate. If you need to modify this information, choose Edit to open the YML editor. You can save
your build settings on our servers, or you can download the YML and add it to the root of your repo (for
monorepos, store the YML at the app's root directory).

4
 AWS Amplify Console User Guide
Step 3: Confirm Build Settings for the Backend

For more information, see YML structure (p. 26).

Step 3: Confirm Build Settings for the Backend

If you connected a repository provisioned by the Amplify CLI v1.0+ (run amplify -v to find CLI version),
the Amplify Console will deploy or automatically update backend resources (any resource provisioned
by the Amplify CLI) in a single workflow with the frontend build. You can choose to point an existing
backend environment to your branch, or create a completely new environment. For a step-by-step
tutorial, see Deploying a fullstack app (p. 8).

To deploy backend functionality using the Amplify CLI during your build, create or reuse an IAM service
role. IAM roles are a secure way to grant the Amplify Console permissions to act on resources in your
account.

Note: The Amplify CLI won't run without an IAM service role enabled.

5
 AWS Amplify Console User Guide
Step 4: Add Environment Variables (Optional)

Step 4: Add Environment Variables (Optional)

Almost every app needs to get configuration information at runtime. These configurations can be
database connection details, API keys, or different parameters. Environment variables provide a means to
expose these configurations at build time.

Step 5: Save and Deploy

Review all of your settings to ensure everything is set up correctly. Choose Save and deploy to deploy
your web app to a global content delivery network (CDN). Your front end build typically takes 1 to 2
minutes but can vary based on size of the app.

Access the build logs screen by selecting a progress indicator on the branch tile. A build has the following
stages:

1. Provision - Your build environment is set up using a Docker image on a host with 4 vCPU, 7GB
memory. Each build gets its own host instance, ensuring that all resources are securely isolated. The
contents of the Docker file are displayed to ensure that the default image supports your requirements.
2. Build - The build phase consists of three stages: setup (clones repository into container), deploy
backend (runs the Amplify CLI to deploy backend resources), and build front end (builds your front-
end artifacts).
3. Deploy - When the build is complete, all artifacts are deployed to a hosting environment managed
by Amplify. Every deployment is atomic - atomic deployments eliminate maintenance windows by
ensuring that the web app is only updated after the entire deployment has completed.
4. Verify - To verify that your app works correctly, Amplify renders screen shots of the index.html in
multiple device resolutions using Headless Chrome.

6
 AWS Amplify Console User Guide
Next Steps

Next Steps
• Add a custom domain to your app (p. 13)
• Manage multiple environments (p. 31)
• Preview pull requests before merging

7
 AWS Amplify Console User Guide
Step 1: Deploy a fullstack sample

Getting Started with Fullstack

Continuous Deployments
The Amplify Console enables developers building apps with the Amplify Framework to continuously
deploy updates to their backend and frontend on every code commit. With the Amplify Console you can
deploy serverless backends with GraphQL/REST APIs, authentication, analytics, and storage created by
the Amplify CLI on the same commit as your frontend code. Note: This feature only works with the
Amplify CLI v4.0+.

In this tutorial, we are going to create and deploy a React app which implements a basic authentication
flow for signing up/signing in users as well as protected client side routing using AWS Amplify.

Step 1: Deploy a fullstack sample

Log in to the Amplify Console and choose Get Started under Deploy. In the following screen, choose
From fullstack samples. Alternatively, start your own adventure by building a backend from scratch by
installing the Amplify CLI.

8
 AWS Amplify Console User Guide
Step 2: Explore the Fullstack App

Choose the Authentication Starter and Deploy app. You will be asked to connect your GitHub account.
Connecting your GitHub acccount allows the Amplify Console to create a fork of the repository in
your account, deploy the AWS backend services, and build and deploy the frontend. In order to deploy
backend resources to AWS, you will need to create a service role (p. 67).

Step 2: Explore the Fullstack App

Your app build will start by deploying the backend followed by the frontend. Click on the branch name
to see the running build. When the build completes you will be able to see screenshots of your app on
different devices.

9
 AWS Amplify Console User Guide
Step 2: Explore the Fullstack App

At the end of the build, you will have one frontend environment (the master branch deployed at 'https://
master.appid.amplifyapp.com') and one backend environment named devX. To add a user to your app,
you can either register a user through the deployed frontend, or choose the Authentication tab which
links to the Amazon Cognito UserPool. Create a user and try logging in to your app.

10
 AWS Amplify Console User Guide
Step 3: Add a GraphQL backend

Step 3: Add a GraphQL backend

1. Let's add a GraphQL API backend with a NoSQL database to your app. To start, clone the repository
that was forked in your account.

git clone [email protected]:<username>/create-react-app-auth-amplify.git

cd create-react-app-auth-amplify

2. From the Backend environments tab, choose Edit backend. As a pre-requisite, follow the instructions
to install and configure the Amplify CLI. The Amplify command line toolchain allows you to edit
the backend you just created to add more functionality such as GraphQL/REST APIs, analytics, and
storage. Once the Amplify CLI is configured, copy the amplify pull command to connect to this
backend from your local machine.

amplify pull --appId XXXXXXXX --envName devw

3. Add the GraphQL API using the default todo example. Learn more about modeling your backend with
the GraphQL transform.

amplify add api

? Please select from one of the below mentioned services GraphQL
? Provide API name: todo
? Choose the default authorization type for the API API key
? Enter a description for the API key:
? 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
? Do you want a guided schema creation? (Y/n) Y
? What best describes your project: Single object with fields (e.g., “Todo” with ID,
name, description)
? Do you want to edit the schema now? No
...
GraphQL schema compiled successfully.

4. To deploy these changes to the cloud run the following commands.

11
 AWS Amplify Console User Guide
Next steps: Set up feature branch deployments

amplify push
Current Environment: devw

| Category | Resource name | Operation | Provider plugin |

| -------- | --------------- | --------- | ----------------- |
| Api | todo | Create | awscloudformation |
| Auth | cognitocf0c6096 | No Change | awscloudformation |
? Are you sure you want to continue? (Y/n) Y
..
✔ Generated GraphQL operations successfully and saved at src/graphql
✔ All resources are updated in the cloud
GraphQL endpoint: https://gumwpbojgraj5b547y5d3shurq.appsync-api.us-west-2.amazonaws.com/
graphql
GraphQL API KEY: da2-vlthvw5qcffxzl2hibgowv3rdq

5. Visit the Amplify Console to view the added API category. Choosing the API category will allow you to
navigate to the AppSync Console (to write queries or mutations performing CRUD operations), or the
DynamoDB Console (to view your Todo table).

6. Use the Amplify GraphQL client to write frontend code that lists and updates the todos. To deploy the
updates to your frontend, simply commit your code and a new build will be triggered in the Amplify
Console.

Next steps: Set up feature branch deployments

Follow our recommended workflow to set up feature branch deployments with multiple backend
environments.

12
 AWS Amplify Console User Guide
Adding a Custom Domain Managed in Amazon Route 53

Setting Up Custom Domains

You can connect a custom domain purchased through domain registrars (for example, Amazon Route 53,
GoDaddy, and Google Domains) to your app. When you deploy your web app with the Amplify Console, it
is hosted at:

https://branch-name.d1m7bkiki6tdw1.amplifyapp.com

When you use a custom domain, users see that your app is hosted from a URL, such as the following:

https://www.awesomedomain.com

The Amplify Console issues an SSL certificate for all domains connected to your app so that all traffic is
secured through HTTPS/2. The SSL certificate generated by Amazon Certificate Manager is valid for 30
days and renews automatically as long as your app is hosted with Amplify.

Topics
• Adding a Custom Domain Managed in Amazon Route 53 (p. 13)
• Adding a Custom Domain Managed by a Third-Party DNS Provider (p. 14)
• Adding Subdomains (p. 16)
• Troubleshooting Guide (p. 17)

Adding a Custom Domain Managed in Amazon

Route 53
After you deploy your app, you can add a custom domain that you manage using Amazon Route 53.

1. On the left navigation pane, choose App Settings, Domain management, and then choose Add
domain.

2. In Enter your root domain, enter your root domain (https://awesomedomain.com). As you
start typing, root domains that you manage in Amazon Route 53 appear in the list (https://
awesomedomain.com). Select the domain you want to use and then choose Configure Domain.

13
 AWS Amplify Console User Guide
Adding a Custom Domain Managed
by a Third-Party DNS Provider

3. By default, the Amplify Console automatically adds two entries for https://
www.myroute53domain.com and https://myroute53domain.com with a redirect set up from the www
subdomain to the root domain (you can change this by choosing Rewrites and redirects from the left
menu). You can modify the default configuration if you want to add subdomains only, see: Connecting
subdomains (p. 16). Choose Save after configuring your domain.

Note: It can take up to 24 hours for the DNS to propagate and to issue the SSL certificate. For more
information about the status messages, see Associating a Domain.

Adding a Custom Domain Managed by a Third-

Party DNS Provider
After you deploy your app, you can add a custom domain that you manage using a third-party DNS
provider if you don't use Amazon Route 53.

1. On the left navigation pane, choose App Settings, Domain management, and then choose Add
domain.
2. In Enter your root domain, enter your root domain (https://awesomedomain.com) and then choose
Configure domain. If the domain is registered, a green alert notifies you to proceed as long you are
the owner of the domain. If the domain is available, purchase a domain at Amazon Route 53.

14
 AWS Amplify Console User Guide
Adding a Custom Domain Managed
by a Third-Party DNS Provider

3. By default, the Amplify Console adds two entries for https://www.awesomedomain.com and
https://awesomedomain.com with a redirect set up from the www subdomain to the root domain.
You can modify the default configuration if you want to add subdomains only, see: Connecting
subdomains (p. 16). Choose Save after configuring your domain.
4. Because the domain is managed externally you must manually configure your DNS provider (for
example, GoDaddy or Google domains). Choose View DNS records in the alert banner.

5. Update your DNS providers' CNAME and ALIAS records as follows. For GoDaddy and Google Domains,
see the step-by-step instructions in Connecting to Third-Party Custom Domains (p. 22).
a. To generate a SSL certificate for your domain, Amplify Console needs to verify ownership.
Configure a CNAME to point to the validation server. Once Amplify Console validates ownership of
your domain, all traffic will be served using HTTPS/2.
b. Configure CNAME record to point your subdomains (https://*.awesomedomain.com) to the
amplifyapp domain. NOTE: If you have production traffic it is recommended you update your
CNAME record after your domain status shows AVAILABLE.
c. Configure ANAME/ALIAS record to point the root domain (https://awesomedomain.com) to your
amplifyapp domain. ANAME records enable you to point the root of your domain to a hostname.
For DNS providers that do not have ANAME/ALIAS support, we strongly recommend migrating your
DNS to Amazon Route 53.
<problematic>**</problematic>
NOTE: If you have production traffic it is recommended you update your ANAME record after your
domain status shows AVAILABLE.*

15
 AWS Amplify Console User Guide
Adding Subdomains

Important: Verification of domain ownership and DNS propagation for third-party domains can take up
to 48 hours. For more information about status messages, see Associating a Domain.

Adding Subdomains
A subdomain is the part of your URL that appears before your domain name (for example,
www.amazon.com or aws.amazon.com).

1. Add a subdomain only: If you already have a production website, you might only want to connect
a subdomain (eg https://alpha.mydomain.com). You can do this by choosing Exclude root and
modifying the subdomain to alpha as shown below.

2. Add a multi-level subdomain: You might want to connect a multi-level subdomain (eg https://
beta.alpha.mydomain.com). You can do this by entering alpha.mydomain.com in the domain search
bar, choosing Exclude root, and modifying the subdomain to beta as shown below.

16
 AWS Amplify Console User Guide
Troubleshooting Guide

3. Manage subdomains After adding your domain, you might want to add more subdomains. Choose
Manage subdomains from the Domain management screen and edit your subdomains.

Troubleshooting Guide
This guide will help you troubleshoot issues regarding the setup of a custom domain in the AWS Amplify
Console.

Topics
• Technical Terminology (p. 17)
• How do I verify that my CNAME resolves? (p. 19)
• My domain hosted with a third party is stuck in Pending Verification state (p. 20)
• My domain hosted with AWS Route53 is stuck in Pending Verification state (p. 20)
• CNAMEAlreadyExistsException Error (p. 21)

Technical Terminology
1. CNAME - A CNAME (Canonical Record Name) is a type of DNS record which allows you to mask the
domain for a set of webpages and make them appear as though they are located elsewhere. CNAMES

17
 AWS Amplify Console User Guide
Technical Terminology

point a subdomain to a Fully Qualified Domain name (FQDN). For example, we can create a new
CNAME record to map the subdomain www.myawesomesite.com to the FQDN domain branch-
name.d1m7bkiki6tdw1.amplifyapp.com assigned to our App.
2. ANAME - An ANAME record is like a CNAME record, but at the root level. An ANAME will point the root
of your domain to a FQDN. That FQDN will actually point to an IP address.
3. Nameserver - A Nameserver is a server on the internet specialized in handling queries regarding the
location of a domain name's various services. If you have your domain setup in AWS Route53, you will
have a list of nameservers assigned to your domain.

Custom Domain Setup in AWS Amplify Console

When you create a new domain on the Amplify Console, there are a number of steps which need to
happen before you can view your app via your custom domain.

1. SSL Create - AWS Amplify Console is issuing an SSL certificate for setting up a secure custom domain.
2. SSL Configuration/Verification - Before issuing an SSL certificate, Amplify Console must verify that
you are the owner of the domain. For domains managed by Route53, we will automatic update the
DNS verification record. For domains managed outside of Route53, you will need to manually add the
displayed DNS verification record into your domain’s DNS provider.
3. Domain activation - The domain is successfully verified. For domains managed outside of Route53,
you will need to manually add the CNAME records provided in the console into your domain's DNS
provider.

Understanding DNS Verification

DNS stands for Domain Name System, and is commonly referred to being a phone book, translating
human-readable names (domains) to computer-friendly addresses (IP Addresses).

When you type https://google.com in the browser, a lookup is done in the DNS provider to find the IP
Address of server which hosts the website.

18
 AWS Amplify Console User Guide
How do I verify that my CNAME resolves?

DNS providers contain records of domains and their corresponding IP Addresses. Here are the most
commonly used DNS records.

1. A record - points the root domain or subdomain to an IP Address

2. CNAME record - Points a subdomain to a FQDN (Fully Qualified Domain Name)
3. NS record - Points to servers which will lookup your domain details

There are a number of free services on the internet you can use to verify your DNS records. For example,
whatsmydns.net.

The Amplify Console uses a CNAME record to verify that you own your custom domain. If you host your
domain with AWS Route53, verification is done on your behalf. However, if you host your domain with a
Third party, you'll have to manually go into your DNS settings and add a new CNAME record.

How do I verify that my CNAME resolves?

After your DNS update, you can use a tool like dig or a free website like whatsmydns.net to verify that
your CNAME records are resolving.

When you click search, you should that the results show that your CNAME is resolving correctly.

You can similarly check the other DNS records.

19
 AWS Amplify Console User Guide
My domain hosted with a third party
is stuck in Pending Verification state

My domain hosted with a third party is stuck in

Pending Verification state
The first thing you'll want to do is to verify if your CNAME records are resolving. See previous step for
instructions. If you CNAME records are not resolving, then you should confirm that the CNAME entry
exists in the your DNS Provider.

Note: If you added or updated your CNAME records a few hours after you
created your app, this will most likely cause your app to get stuck in
the pending verification state. It is important that you update your
CNAME records as soon as you create your custom domain.

Once your app is created in the Amplify Console, your CNAME records are checked every few minutes to
determine if it resolves. If it doesn't resolve after an hour, the check is made every few hours which can
lead to a delay in your domain being ready to use.

Lastly, if you have confirmed that the CNAME records exists, then there might be an issue with your DNS
provider. You can either contact the DNS provider to diagnose why the DNS verification CNAME is not
resolving or migrate your DNS to Route53.

My domain hosted with AWS Route53 is stuck in

Pending Verification state
If you transferred your domain to AWS Route53 then it's possible that your domain has different
nameservers then those issued by the Amplify Console when your app was created. Login to the Route53
console, choose Hosted Zones from the left navigation, and pick the domain you are connecting. Record
the nameserver values.

Next, choose Registered domains from the left navigation. Ensure the nameservers on the registered
domain screen match what you copied from the Hosted Zone.

20
 AWS Amplify Console User Guide
CNAMEAlreadyExistsException Error

If this did not resolve the issue, please email [email protected].

CNAMEAlreadyExistsException Error
This means that one of the hostnames you tried to connect (could be a subdomain, or the apex domain)
is already deployed to another AWS CloudFront distribution. Here's how you can diagnose the issue:

1. Check the AWS CloudFront Console to see if you have this domain deployed to any other distribution.
At a time, you can only have a single CNAME record attached to a one CloudFront distribution.
2. Is this domain connected to a different Amplify App that you own? If so, make sure you are not trying
to reuse one of the hostnames. If you are using www.domain.com on the other app, you cannot use
www.domain.com with this appYou can use other subdomains such as blog.domain.com.
3. If you had this domain successfully connected to another app and then recently (within the last hour)
deleted it, please wait and try again after some time. If you still see this exception after 6 hours,
please contact us at [email protected].

21
 AWS Amplify Console User Guide
Connecting to a GoDaddy Domain

Connecting to Third-Party Custom

Domains
Connecting to a GoDaddy Domain
1. Follow the instructions to add a domain (p. 13) for third-party providers.
2. Log in to your account at GoDaddy and choose DNS.

3. Add CNAME records to to point your subdomains to the Amplify domain, and another CNAME record
to point to Amazon Certificate Manager's validation server. A single validated ACM generates an SSL
certificate for your domain. Make sure you only enter the subdomain (for example, ) in **Host* as
shown below (don't enter yourdomainname.com).

GoDaddy doesn't support ANAME/ALIAS records. For DNS providers that don't have ANAME/ALIAS
support, we strongly recommend migrating your DNS to Amazon Route 53. If you want to keep your

22
 AWS Amplify Console User Guide
Connecting to a GoDaddy Domain

current provider and update the root domain, add Forwarding and set up a domain forward. In Forward
to, enter the information as shown following:

23
AWS Amplify Console User Guide
Connecting to a GoDaddy Domain

24
 AWS Amplify Console User Guide
Connecting to a Google Domain

Connecting to a Google Domain

1. Follow the instructions to add a domain (p. 13) for third-party providers.
2. Log in to your account at https://domains.google and choose DNS.

3. In Custom resource records, enter CNAME records that you want to point all subdomains (https://
*.awesomedomain.com) to the amplifyapp domain, and another CNAME record to point to Amazon
Certificate Manager's validation server. A single validated ACM generates an SSL certificate for your
domain.

Google domains don't support ANAME/ALIAS records. For DNS providers that don't have ANAME/
ALIAS support, we strongly recommend migrating your DNS to Amazon Route 53. If you want to keep
your current provider and update the root domain, add a Synthetic Record, and set up a Subdomain
Forward. In Subdomain, enter the @ symbol and then choose Forward path as shown following:

25
 AWS Amplify Console User Guide
YML Specification Syntax

Configuring Build Settings

The Amplify Console automatically detects the front end framework and associated build settings by
inspecting the package.json file in your repository. You have the following options:

• Save the build settings in the Amplify Console - The Amplify Console autodetects build settings and
saves it so that they can be accessed via the Amplify Console. These settings are applied to all of your
branches unless there is a YML file found in your repository.
• Save the build settings in your repository - Download the amplify.yml file and add it to the root of
your repository (or root of the app folder for monorepos).

You can edit these settings in the Amplify Console by choosing App Settings>Build settings. These build
settings are applied to all the branches in your app, except for the branches that have a YML file saved in
the repository.

YML Specification Syntax

The build specification YML contains a collection of build commands and related settings that the
Amplify Console uses to run your build. The YML is structured as follows:

version: 1.0
env:
variables:
key: value
backend:
phases:
preBuild:
commands:
- *enter command*
build:
commands:
- *enter command*
postBuild:
commands:
- *enter command*
frontend:
phases:
preBuild:
commands:
- cd react-app
- npm ci
build:
commands:
- npm run build
artifacts:
files:
- location
- location
discard-paths: yes
baseDirectory: location
cache:
paths:
- path
- path

26
 AWS Amplify Console User Guide
Branch-Specific Build Settings

customHeaders:
- pattern: 'file-pattern'
headers:
- key: 'custom-header-name'
value: 'custom-header-value'
- key: 'custom-header-name'
value: 'custom-header-value'
test:
phases:
preTest:
commands:
- *enter command*
test:
commands:
- *enter command*
postTest:
commands:
- *enter command*
artifacts:
files:
- location
- location
configFilePath: *location*
baseDirectory: *location*

• version - Represents the Amplify Console YML version number.

• env - Add environment variables to this section. You can also add environment variables using the
console.
• backend - Run Amplify CLI commands to provision a backend, update Lambda functions, or GraphQL
schemas as part of continuous deployment. Learn how to deploy a backend with your frontend (p. 8).
• frontend - Run frontend build commands.
• test - Run commands during a test phase. Learn how to add tests to your app (p. 45).
• The frontend, backend, and test have three phases that represent the commands run during each
sequence of the build.
• preBuild - The preBuild script runs before the actual build starts, but after we have installed
dependencies.
• build - Your build commands.
• postBuild - The post-build script runs after the build has finished and we have copied all the
necessary artifacts to the output directory.
• artifacts>base-directory - The directory in which your build artifacts exist.
• artifacts>files - Specify files from your artifact you want to deploy. **/* is to include all files.
• customHeaders - Custom header rules set on deployed files. See custom headers (p. 58).

Branch-Specific Build Settings

You can use bash shell scripting to set branch-specific build settings. For example, the following script
uses the system environment variable $AWS_BRANCH to execute one set of commands if the branch
name is master and a different set of commands if the branch name is dev.

frontend:
phases:
build:
commands:
- if [ "${AWS_BRANCH}" = "master" ]; then echo "master branch"; fi
- if [ "${AWS_BRANCH}" = "dev" ]; then echo "dev branch"; fi

27
 AWS Amplify Console User Guide
Navigating to a Subfolder

Navigating to a Subfolder
For monorepos, users want to be able to cd into a folder to run the build. After you run the cd command,
it applies to all stages of your build so you don't need to repeat the command in separate phases.

version: 1.0
env:
variables:
key: value
frontend:
phases:
preBuild:
commands:
- cd react-app
- npm ci
build:
commands:
- npm run build

Deploying the Backend with Your Front End

The amplifyPush is a helper script that helps you with backend deployments. The build settings below
automatically determine the correct backend environment to deploy for the current branch.

version: 1.0
env:
variables:
key: value
backend:
phases:
build:
commands:
- amplifyPush --simple

Setting the Output Folder

The following build settings set the output directory to the public folder.

frontend:
phases:
commands:
build:
- yarn run build
artifacts:
baseDirectory: public

Installing Packages as Part of Your Build

You can use npm or yarn to install packages during the build.

frontend:

28
 AWS Amplify Console User Guide
Using a Private npm Registry

phases:
build:
commands:
- npm install -g pkg-foo
- pkg-foo deploy
- yarn run build
artifacts:
baseDirectory: public

Using a Private npm Registry

You can add references to a private registry in your build settings or add it as an environment variable.

build:
phases:
preBuild:
commands:
- npm config set <key> <value>
- npm config set registry https://registry.npmjs.org
- npm config set always-auth true
- npm config set email [email protected]
- yarn install

Installing OS packages
You can install OS packages for missing dependencies.

build:
phases:
preBuild:
commands:
- yum install -y <package>

Key-value storage for every build

The envCache provides key-value storage at build time. Values stored in the envCache can only
be modified during a build and can be re-used at the next build. Using the envCache, we can store
information on the deployed environment and make it available to the build container in successive
builds. Unlike values stored in the envCache, changes to environment variables during a build are not
persisted to future builds.

Example usage:

envCache --set <key> <value>

envCache --get <key>

Disable Automatic builds

You can configure Amplify Console to disable automatic builds on every code commit. To set up, choose
App settings > General and then scroll to the section with all the connected branches. Select a branch,

29
 AWS Amplify Console User Guide
Disable Automatic builds

and then choose Action > Disable auto build. Further commits to that branch will no longer trigger a
new build.

30
 AWS Amplify Console User Guide
Team workflows with Amplify CLI backend environments

Feature branch deployments and

team workflows
The Amplify Console is designed to work with feature branch and GitFlow workflows. The Amplify
Console leverages Git branches to create new deployments every time a developer connects a new
branch in their repository. After connecting your first branch, you can create a new feature branch
deployment by adding a branch as follows:

1. On the branch list page, choose Connect branch.

2. Choose a branch from your repository.
3. Save and then deploy your app.

Your app now has two deployments available at https://master.appid.amplifyapp.com and https://
dev.appid.amplifyapp.com. This may vary from team-to-team, but typically the master branch tracks
release code and is your production branch. The develop branch is used as an integration branch to test
new features. This way beta testers can test unreleased features on the develop branch deployment,
without affecting any of the production end users on the master branch deployment.

Topics
• Team workflows with Amplify CLI backend environments (p. 31)
• Pattern-based feature branch deployments (p. 39)

Team workflows with Amplify CLI backend

environments
A feature branch deployment consists of a frontend and (optionally) a **backend environment*. The
frontend is built and deployed to a global CDN, while the backend is deployed by the Amplify CLI to
AWS.

31
 AWS Amplify Console User Guide
Feature branch workflow

You can use the Amplify Console to continuously deploy backend resources such as GraphQL APIs and
Lambda functions with your feature branch deployment. You can use the following models to deploy
your backend and frontend with the Amplify Console:

Topics
• Feature branch workflow (p. 17)
• GitFlow workflow (p. 37)
• Per-developer sandbox (p. 37)

Feature branch workflow

• Create prod, test, and dev backend environments with the Amplify CLI.
• Map prod and test to master and develop branches.
• Teammates can use the dev backend environment to test against feature branches.

1. Install the Amplify CLI to initialize a new Amplify project.

npm install -g @aws-amplify/cli

2. Initialize a prod backend environment for your project. If you don't have a project, create one using
bootstrap tools like create-react-app or Gatsby.

create-react-app next-unicorn
cd next-unicorn
amplify init
? Do you want to use an existing environment? (Y/n): n
? Enter a name for the environment: prod
...
amplify push

3. Add test and dev backend environments.

amplify env add

? Do you want to use an existing environment? (Y/n): n

32
 AWS Amplify Console User Guide
Feature branch workflow

? Enter a name for the environment: test

...
amplify push

amplify env add

? Do you want to use an existing environment? (Y/n): n
? Enter a name for the environment: dev
...
amplify push

4. Push code to a Git repository of your choice (in this example we'll assume you pushed to master).

git commit -am 'Added dev, test, and prod environments'

git push origin master

5. Visit the Amplify Console in the AWS Console to see your current backend environment. Navigate
a level up from the breadcrumb to view a list of all backend environments created in the Backend
environments tab.

33
 AWS Amplify Console User Guide
Feature branch workflow

6. Switch to the Frontend environments tab and connect your repository provider and master branch.

34
 AWS Amplify Console User Guide
Feature branch workflow

7. In the build settings screen, pick an existing backend environment to set up continuous deployment
with the master branch. Choose prod from the dropdown and grant the service role to Amplify
Console. Choose Save and deploy. After the build completes you will get a master branch deployment
available at https://master.appid.amplifyapp.com.

8. Connect develop branch in Amplify Console (assume develop and master branch are the same at this
point). Choose the test backend environment.

35
 AWS Amplify Console User Guide
Feature branch workflow

9. The Amplify Console is now setup. You can start working on new features in a feature branch. Add
backend functionality by using the dev backend environment from your local workstation.

git checkout -b newinternet

amplify env checkout dev
amplify add api
...
amplify push

1. After you finish working on the feature, commit your code, create a pull request to review internally.

git commit -am 'Decentralized internet v0.1'

git push origin newinternet

2. To preview what the changes will look like, go to the Console and connect your feature branch. Note:
If you have the AWS CLI installed on your system (Not the Amplify CLI), you can connect a branch
directly from your terminal. You can find your appid by going to App settings > General > AppARN:
arn:aws:amplify:<region>:<region>:apps/<appid>

aws amplify create-branch --app-id <appid> --branch-name <branchname>

aws amplify start-job --app-id <appid> --branch-name <branchname> --job-type RELEASE

3. Your feature will be accessible at https://newinternet.appid.amplifyapp.com to share with your

teammates. If everything looks good merge the PR to the develop branch.

git checkout develop

git merge newinternet
git push

4. This will kickoff a build that will update the backend as well as the frontend in the Amplify Console
with a branch deployment at https://dev.appid.amplifyapp.com. You can share this link with internal
stakeholders so they can review the new feature.

36
 AWS Amplify Console User Guide
GitFlow workflow

5. Delete your feature branch from Git, Amplify Console, and remove the backend environment from the
cloud (you can always spin up a new one based on by running 'amplify env checkout prod' and running
'amplify env add').

git push origin --delete newinternet

aws amplify delete-branch --app-id <appid> --branch-name <branchname>
amplify env remove dev

GitFlow workflow
GitFlow uses two branches to record the history of the project. The master branch tracks release code
only, and the develop branch is used as an integration branch for new features. GitFlow simplifies parallel
development by isolating new development from completed work. New development (such as features
and non-emergency bug fixes) is done in feature branches. When the developer is satisfied that the code
is ready for release, the feature branch is merged back into the integration develop branch. The only
commits to the master branch are merges from release branches and hotfix branches (to fix emergency
bugs).

The diagram below shows a recommended setup with GitFlow. You can follow the same process as
described in the feature branch workflow section above.

Per-developer sandbox
• Each developer in a team creates a sandbox environment in the cloud that is separate from their local
computer. This allows developers to work in isolation from each other without overwriting other team
members' changes.
• Each branch in the Amplify Console has its own backend. This ensures that the Amplify Console uses
the Git repository as a single source of truth from which to deploy changes, rather than relying on
developers on the team to manually push their backend or front end to production from their local
computers.

37
 AWS Amplify Console User Guide
Per-developer sandbox

1. Install the Amplify CLI to initialize a new Amplify project.

npm install -g @aws-amplify/cli

2. Initialize a kita backend environment for your project. If you don't have a project, create one using
bootstrap tools like create-react-app or Gatsby.

cd next-unicorn
amplify init
? Do you want to use an existing environment? (Y/n): n
? Enter a name for the environment: kita
...
amplify push

1. Push code to a Git repository of your choice (in this example we'll assume you pushed to master).

git commit -am 'Added kita sandbox'

git push origin master

2. Connect your repo > master to the Amplify Console.

38
 AWS Amplify Console User Guide
Pattern-based feature branch deployments

3. The Amplify Console will detect backend environments created by the Amplify CLI. Choose Create
new environment from the dropdown and grant the service role to Amplify Console. Choose Save
and deploy. After the build completes you will get a master branch deployment available at https://
master.appid.amplifyapp.com with a new backend environment that is linked to the branch.

4. Connect develop branch in Amplify Console (assume develop and master branch are the same at this
point) and choose Create new environment. After the build completes you will get a develop branch
deployment available at https://develop.appid.amplifyapp.com with a new backend environment that
is linked to the branch.

Pattern-based feature branch deployments

Pattern-based branch deployments allow you to automatically deploy branches that match a specific
pattern to the Amplify Console. Product teams using feature branch or GitFlow workflows for their
releases, can now define patterns such as 'release**' to automatically deploy Git branches that begin with
‘release’ to a shareable URL. This blog post describes using this feature with different team workflows.

1. Choose App settings > General > Edit.

2. Flip the branch autodetection switch to Enabled.

39
 AWS Amplify Console User Guide
Pattern-based feature branch deployments

1. Define patterns for automatically deploying branches.

• '*' will deploy all branches in your repository.
• 'release*' will automatically deploy all branches that being with the word 'release.
• 'release*/
<problematic>**</problematic>
' will deploy all branches that match a 'release /' pattern.
• Specify multiple patterns comma-separated - e.g. 'release*', 'feature*'.
2. Set up automatic password protection for all branches that are automatically created by setting
Branch autodetection - access control to Enabled.
3. For applications built with an Amplify backend, you can choose to create a new environment or point
all branches to an existing backend.

40
 AWS Amplify Console User Guide
Pattern-based feature branch deployments

41
 AWS Amplify Console User Guide
Drag and Drop

Manual Deploys
Manual deploys allows you to publish your web app to the Amplify Console without connecting a Git
provider. You can choose to drag and drop a folder from your desktop, or reference an Amazon S3 bucket
or external URL.

Drag and Drop

Drag and drop a folder from your desktop to host your site in seconds. Log in to the Amplify Console
and choose Deploy without a Git provider. Give your app a name, and a name for the environment (e.g.
development or production). Drag and drop files from your desktop to publish your web app.

Amazon S3 or any URL

Reference assets that are uploaded to an Amazon S3 bucket, or provide a public URL to files stored
elswhere.

For Amazon S3, choose the bucket and zip file to deploy your site. You can also set up AWS Lambda
triggers so your site is updated everytime new assets are uploaded. This blog post walks through setting
up a Lambda trigger to automatically deploy changes to Amplify on any updates to a bucket.

42
AWS Amplify Console User Guide
Amazon S3 or any URL

43
 AWS Amplify Console User Guide
Add 'Deploy to Amplify Console'
button to your repository or blog

Deploy to Amplify Console Button

The Deploy to Amplify Console button enables you to share GitHub projects publicly or within your
team. The button looks like:

Add 'Deploy to Amplify Console' button to your

repository or blog
Add this button to your GitHub README.md file, blog post, or any other markup page that renders
HTML. The button has two components:

1. An SVG image: https://oneclick.amplifyapp.com/button.svg

2. The Amplify Console URL with a link to your GitHub repository. Please copy your repo URL (e.g.
https://github.com/username/repository) only or provide a deep link into a specific folder
(e.g. https://github.com/username/repository/tree/master/folder). The Amplify
Console will deploy the default branch in your repository. Additional branches can be connected after
the app is connected.
3. Add the button to a markdown file (e.g. your GitHub README.md). Please replace https://
github.com/username/repository with your repository name.

[](https://
console.aws.amazon.com/amplify/home✔/deploy?repo=https://github.com/username/repository)

1. You can also add the button to any HTML document:

<a href="https://console.aws.amazon.com/amplify/home✔/deploy?repo=https://github.com/
username/repository">
<img src="https://oneclick.amplifyapp.com/button.svg" alt="Deploy to Amplify Console">
</a>

44
 AWS Amplify Console User Guide
Tutorial: Set up end-to-end tests with Cypress

Add End-to-End tests to your app

You now run end-to-end (E2E) tests in the test phase of your Amplify app to catch regressions before
pushing code to production. The test phase can be configured in the build specification YML and can be
used to run any testing framework of your choice during a build.

Tutorial: Set up end-to-end tests with Cypress

Cypress is a JavaScript-based framework that allows you to run E2E tests on a browser. This tutorial will
demonstrate how to set up E2E tests from scratch.

45
 AWS Amplify Console User Guide
Add tests to your existing Amplify app

Add tests to your existing Amplify app

You can use the test step to run any test commands at build time. For E2E tests, the Amplify Console
offers a deeper integration with Cypress that allows you to generate a UI report for your tests. To add
Cypress tests to an existing app, update your amplify.yml build settings with the following values.

test:
phases:
preTest:
commands:
- npm install
- npm install wait-on
- npm install [email protected] mochawesome mochawesome-merge mochawesome-report-
generator
- 'npm start & npx wait-on http://localhost:8080'
test:
commands:
- 'npx cypress run --reporter mochawesome --reporter-options "reportDir=cypress/
report/mochawesome-report,overwrite=false,html=false,json=true,timestamp=mmddyyyy_HHMMss"'
postTest:
commands:
- npx mochawesome-merge --reportDir cypress/report/mochawesome-report > cypress/
report/mochawesome.json
artifacts:
baseDirectory: cypress
configFilePath: '**/mochawesome.json'
files:
- '**/*.png'
- '**/*.mp4'

• preTest - Install all the dependencies required to run Cypress tests. Amplify Console uses
<problematic>`mochaawesome <https://github.com/adamgruber/mochawesome`__</problematic>
to generate a report to view your test results and wait-on to set up the localhost server during the
build.
• test - Run cypress commands to execute tests using mochawesome.
• postTest - The mochawesome report is generated from the output JSON.
• artifacts>baseDirectory - The directory from which tests are run.
• artifacts>files - The generated artifacts (screenshots and videos) available for download.

Disabling tests
Once the "test" config has been added to your amplify.yml build settings, the test step will be executed
for every build, on every branch. If you would like to globally disable tests from running, or you would
only like tests to run for specific branches, you can use the "USER_DISABLE_TESTS" environment variable
to do so without modifying your build settings.

To globally disable tests for all branches, add the USER_DISABLE_TESTS environment variable with a
value of true for all branches, as shown below:

46
 AWS Amplify Console User Guide
Disabling tests

To disable tests for a specific branch, add the USER_DISABLE_TESTS environment variable with a value
of false for all branches, and then add an override for each branch you would like to disable with a value
of true. In the following example, tests are disabled on the "master" branch, and enabled for every other
branch:

Disabling tests with this variable will cause the test step to be skipped altogether during a build. To re-
enable tests, set this value to false, or delete the environment variable.

47
 AWS Amplify Console User Guide
Types of Redirects

Using Redirects
Redirects enable a web server to reroute navigation from one URL to another. Common reasons for
using redirects include: to customize the appearance of URL, to avoid broken links, to move the hosting
location of an app or site without changing its address, and to change a requested URL to the form
needed by a web app.

Types of Redirects
There are several types of redirects that support specific scenarios.

Permanent redirect (301)

301 redirects are intended for lasting changes to the destination of a web address. Search engine ranking
history of the original address applies to the new destination address. Redirection occurs on the client-
side, so a browser navigation bar shows the destination address after redirection. Common reasons to
use 301 redirects include:

• To avoid a broken link when the address of a page changes.

• To avoid a broken link when a user makes a predictable typo in an address.

Temporary redirect (302)

302 redirects are intended for temporary changes to the destination of a web address. Search engine
ranking history of the original address doesn't apply to the new destination address. Redirection occurs
on the client-side, so a browser navigation bar shows the destination address after redirection. Common
reasons to use 302 redirects include:

• To provide a detour destination while repairs are made to an original address.

• To provide test pages for A/B comparison of user interface.

Rewrite (200)

200 redirects (rewrites) are intended to show content from the destination address as if it were served
from the original address. Search engine ranking history continues to apply to the original address.
Redirection occurs on the server-side, so a browser navigation bar shows the original address after
redirection. Common reasons to use 200 redirects include:

• To redirect an entire site to a new hosting location without changing the address of the site.
• To redirect all traffic to a single page web app (SPA) to its index.html page for handling by a client-side
router function.

Not Found (404)

404 redirects occur when a request points to an address that doesn't exist. The destination page of a 404
is displayed instead of the requested one. Common reasons a 404 redirect occurs include:

• To avoid a broken link message when a user enters a bad URL.

• To point requests to nonexistent pages of a web app to its index.html page for handling by a client-
side router function.

48
 AWS Amplify Console User Guide
Parts of a Redirect

Parts of a Redirect
Redirects consist of the following:

• An original address - The address the user requested.

• A destination address - The address that actually serves the content that the user sees.
• A redirect type - Types include a permanent redirect (301), a temporary redirect (302), a rewrite (200),
or not found (404).
• A two letter country code (optional) - a value you can include to segment the user experience of your
app by region

To create and edit redirects, choose Rewrites and redirects settings in the left navigation pane.

To bulk edit redirects in a JSON editor, choose Open text editor.

Order of Redirects
Redirects are executed from the top of the list down. Make sure that your ordering has the effect you
intend. For example, the following order of redirects causes all requests for a given path under /docs/ to
redirect to the same path under /documents/, except /docs/specific-filename.html which redirects to /
documents/different-filename.html:

/docs/specific-filename.html /documents/diferent-filename.html 301

/docs/<*> /documents/<*>

The following order of redirects ignores the redirection of specific-filename.html to different-

filename.html:

/docs/<*> /documents/<*>
/docs/specific-filename.html /documents/diferent-filename.html 301

49
 AWS Amplify Console User Guide
Simple Redirects and Rewrites

Simple Redirects and Rewrites

In this section we include example code for common redirect scenarios.

You can use the following example code to permanently redirect a specific page to a new address.

Original address Destination Address Redirect Type Country Code

/original.html /destination.html permanent redirect  

(301)

JSON: [{"source": "/original.html", "status": "301", "target": "/destination.html", "condition": null}]

You can use the following example code to redirect any path under a folder to the same path under a
different folder.

Original address Destination Address Redirect Type Country Code

docs/<*> /documents/<*> permanent redirect  

(301)

JSON [{"source": "/docs/<*>", "status": "301", "target": "/documents/<*>", "condition": null}]

You can use the following example code to redirect all traffic to index.html as a rewrite. In this scenario,
the rewrite makes it appear to the user that they have arrived at the original address.

Original address Destination Address Redirect Type Country Code

<*> /index.html rewrite (200)  

JSON [{"source": "/<*>", "status": "200", "target": "/index.html", "condition": null}]

You can use the following example code to use a rewrite to change the subdomain that appears to the
user.

Original address Destination Address Redirect Type Country Code

https:// https:// rewrite (200)  

mydomain.com www.mydomain.com

JSON [{"source": "https://mydomain.com", "status": "200", "target": "https://www.mydomain.com", "condition": null}]

You can use the following example code to redirect paths under a folder that can't be found to a custom
404 page.

Original address Destination Address Redirect Type Country Code

/<*> /404.html not found (404)  

50
 AWS Amplify Console User Guide
Redirects for Single Page Web Apps (SPA)

JSON [{"source": "/<*>", "status": "404", "target": "/404.html", "condition": null}]

Redirects for Single Page Web Apps (SPA)

Most SPA frameworks support HTML5 history.pushState() to change browser location without triggering
a server request. This works for users who begin their journey from the root (or /index.html), but fails
for users who navigate directly to any other page. Using regular expressions, the following example sets
up a 200 rewrite for all files to index.html except for the specific file extensions specified in the regular
expression.

Original address Destination Address Redirect Type Country Code

</^[^.]+$|\.(?! /index.html 200  

(css|gif|ico|
jpg|js|png|txt|
svg|woff|ttf|map|
json)$)([^.]+$)/>

JSON [{"source": "</^[^.]+$|.(?!(css|gif|ico|jpg|js|png|txt|svg|woff|ttf|map|json)$)([^.]+$)/>", "status": "200", "target": "index.html",

"condition": null}]

Reverse Proxy Rewrite

The following example uses a rewrite to proxy content from another location so that it appears to user
that the domain hasn't changed:

Original address Destination Address Redirect Type Country Code

/images https:// rewrite (200)  

images.otherdomain.com

JSON [{"source": "/images", "status": "200", "target": "https://images.otherdomain.com", "condition": null}]

Trailing slashes and Clean URLs

To create clean URL structures like about instead of about.html, static site generators such as
Hugo generate directories for pages with an index.html (/about/index.html). The Amplify Console
automatically creates clean URLs by adding a trailing slash when required. The table below highlights
different scenarios:

User inputs in browser URL in the address bar Document served

/about /about /about.html

/about (when about.html /about/ /about/index.html

returns 404)

/about/ /about/ /about/index.html

51
 AWS Amplify Console User Guide
Placeholders

Placeholders
You can use the following example code to redirect paths in a folder structure to a matching structure in
another folder.

Original address Destination Address Redirect Type Country Code

/docs/<year>/ /documents/<year>/ permanent redirect  

<month>/<date>/ <month>/<date>/ (301)
<itemid> <itemid>

JSON [{"source": "/docs/<year>/<month>/<date>/<itemid>", "status": "301", "target": "/documents/<year>/<month>/<date>/<itemid>",

"condition": null}]

Query Strings and Path Parameters

You can use the following example code to redirect a path to a folder with a name that matches the
value of a query string element in the original address:

Original address Destination Address Redirect Type Country Code

/docs?id=<my-blog- /documents/<my- permanent redirect  

id-value blog-post-id- (301)
value>

JSON [{"source": "/docs?id=<my-blog-id-value", "status": "301", "target": "/documents/<my-blog-post-id-value>", "condition": null}]

You can use the following example code to redirect all paths that can't be found at a given level of a
folder structure to index.html in a specified folder.

Original address Destination Address Redirect Type Country Code

/documents/ /documents/ 404  

<folder>/<child- index.html
folder>/<grand-
child-folder>

JSON [{"source": "/documents/<x>/<y>/<z>", "status": "404", "target": "/documents/index.html", "condition": null}]

Region-based Redirects
You can use the following example code to redirect requests based on region.

Original address Destination Address Redirect Type Country Code

/documents /documents/us/ 302 <US>

52
 AWS Amplify Console User Guide
Region-based Redirects

JSON [{"source": "/documents", "status": "302", "target": "/documents/us/", "condition": "<US>"}]

53
 AWS Amplify Console User Guide

Restricting access
Working on unreleased features? Password protect feature branches that are not ready to be accessed
publicly.

1. Choose App settings and then choose Access control.

2. In the list of your connected branches, choose Manage access in the top-right corner.

3. Do one of the following:

• You can set a global password that you want to apply to all connected branches. For example, if you
have master, dev, and feature connected, you can use a global password to set the same user name
and password for all branches.
• You can set a password at the branch level.

54
 AWS Amplify Console User Guide
Setting Environment Variables

Environment Variables
Environment variables are key-value pairs that are available at build time. These configurations can be
anything, including:

• Database connection details

• Third-party API keys
• Different customization parameters
• Secrets

As a best practice, you can use environment variables to expose these configurations. All environment
variables that you add are encrypted to prevent rogue access so you can use them to store secret
information.

Setting Environment Variables

1. In the Amplify console, choose App Settings and then choose Environment Variables.
2. In the key and value fields, enter all your app environment variables. By default, the Amplify console
applies the environment variables across all branches, so you don't have to re-enter variables when
you connect a new branch.
3. Choose Save.

If you need to customize a variable specifically for a branch, you can add a branch override. To do this,
choose Actions and then choose Add variable override. You now have a set of environment variables
specific to your branch.

55
 AWS Amplify Console User Guide
Accessing Environment Variables

Accessing Environment Variables

To access an environment variable during a build, edit your build settings to include the environment
variable in your build commands.

1. In the Amplify console, choose App Settings, choose Build settings, and then choose Edit.
2. Add the environment variable to your build command. You should now be able to access your
environment variable during your next build.

build:
commands:
- npm run build:$BUILD_ENV

Amplify Console Environment Variables

You can use environment variables that are accessible by default within the Amplify Console.

Variable name Description Example

AWS_APP_ID The app ID of the current build abcd123

AWS_BRANCH The branch name of the current master

build

AWS_BRANCH_ARN The branch ARN of the current arn:xxxxx/xxxx/xxxxx

build

AWS_CLONE_URL The clone URL used to fetch the [email protected]:<user-name>/

git repository contents <repo-name>.git

AWS_COMMIT_ID The commit ID of the current xxxxxxxxxxxxxxxxxx

build. "HEAD" for rebuilds

56
 AWS Amplify Console User Guide
Amplify Console Environment Variables

AWS_JOB_ID The job ID of the current build. 0000000001

This includes some padding of
'0' so it always has the same
length.

57
 AWS Amplify Console User Guide
Example: Security Headers

Custom Headers
Custom HTTP headers allow you to specify headers for every HTTP response. Response headers can be
used for debugging, security, and informational purposes. Define custom header rules for your app as
follows:

1. From the navigation bar on the left, choose App Settings > Build Settings, and then choose Edit to edit
your buildspec.
2. In the frontend section of the YML file, add the custom headers for your app as follows:

version: 0.1
frontend:
phases:
build:
post_build:
artifacts:
baseDirectory:
customHeaders:
- pattern: '*.json'
headers:
- key: 'custom-header-name-1'
value: 'custom-header-value-1'
- key: 'custom-header-name-2'
value: 'custom-header-value-2'
- pattern: '/path/*'
headers:
- key: 'custom-header-name-1'
value: 'custom-header-value-2'

• pattern - Headers applied to all URL file paths that match the pattern.
• headers - Define headers that match the file pattern. The key is the custom header name and the
value is the custom header value.
• To learn more about HTTP headers, please see Mozilla's documentation for a list of HTTP headers.

1. Choose Save. Your custom header settings will now be applied to your app.

Example: Security Headers

The following security headers enable enforcing HTTPS, preventing XSS attacks, and defending your
browser against clickjacking. Add it to your app's buildspec and choose Save to apply the custom header
settings.

customHeaders:
- pattern: '**/*'
headers:
- key: 'Strict-Transport-Security'
value: 'max-age=31536000; includeSubDomains'
- key: 'X-Frame-Options'
value: 'SAMEORIGIN'
- key: 'X-XSS-Protection'
value: '1; mode=block'
- key: 'X-Content-Type-Options'

58
 AWS Amplify Console User Guide
Example: Security Headers

value: 'nosniff'
- key: 'Content-Security-Policy'
value: 'default-src self'

59
 AWS Amplify Console User Guide

Incoming Webhooks
Set up an incoming webhook in the Amplify Console to trigger a build without comitting code to your Git
repository. Webhook triggers can be used with headless CMS tools (such as Contentful or GraphCMS) to
trigger builds on content changes, or to trigger daily builds using services such as Zapier.

1. Log in to the Amplify Console and choose your app.

2. Navigate to App Settings > Build Settings and scroll to the Incoming webhook container. Choose
Create webhook

3. Give your webhook a name and choose Save.

4. You can copy the webhook URL or run a curl command in your command line to trigger a new build.

60
AWS Amplify Console User Guide

61
 AWS Amplify Console User Guide
Analyzing access logs

Access logs
Access logs store information about all requests that are made to your Amplify hosted app. All sites
hosted on Amplify Console have logs retrievable for any two week window. To view access logs choose
App settings > Access logs from your app's left navigation bar. Choose Edit time range to choose the
two week interval you wish to access. The logs are availble to download in a CSV format.

Analyzing access logs

To analyze access logs you can store the CSV files in an Amazon S3 bucket. One way to analyze your
access logs is to use Amazon Athena. Athena is an interactive query service that can help you analyze
data for AWS services. You can follow the step-by-step instructions here to create a table. Once your
table has been created, you can query data as follows.

SELECT SUM(bytes) AS total_bytes

FROM logs
WHERE "date" BETWEEN DATE '2018-06-09' AND DATE '2018-06-11'
LIMIT 100;

62
 AWS Amplify Console User Guide
Custom Build Images

Custom Build Images and Live

Package Updates
Topics
• Custom Build Images (p. 63)
• Live Package Updates (p. 64)

Custom Build Images

Custom Build Images can be used to provide a customized build environment. If you have specific
dependencies that take a long time to install during a build using our default container, you can create
your own Docker image and reference it during a build. Images can be hosted on Docker Hub or a public
Amazon Elastic Container Registry. The format expected here is the same as the format Docker pull
command (e.g. node:latest). In case of a public ECR instance, you are required to provide the full URL (e.g.
aws_account_id.dkr.ecr.us-west-2.amazonaws.com/amazonlinux:latest).

Configuring a Custom Build Image

1. From your App Detail page, choose App Settings > Build Settings.
2. From the Build image settings container, choose Edit.

3. Specify your custom build image and choose Save.

63
 AWS Amplify Console User Guide
Custom Build Image Requirements

Custom Build Image Requirements

In order for a custom build image to work as an Amplify Console build image there are a few
requirements for the image:

1. cURL: When we launch your custom image, we download our build runner into your container, and
therefore we require cURL to be present. If this dependency is missing, the build will instantly fail
without any output as our build-runner was unable to produce any output.
2. Git: In order to clone your Git repository we require Git to be installed in the image. If this dependency
is missing, the ‘Cloning repository’ step will fail.
3. OpenSSH: In order to securely clone your repository we require OpenSSH to set up the SSH key
temporarily during the build, the OpenSSH package provides the commands that the build runner
requires to do this.
4. (NPM-based builds)Node.JS+NPM: Our build runner does not install Node, but instead relies on Node
and NPM being installed in the image. This is only required for builds that require NPM packages or
Node specific commands.

Live Package Updates

Live Package Updates allows you to specify versions of packages and dependencies to use in our default
build image. Our default build image comes with several packages and dependencies pre-installed
(e.g. Hugo, Amplify CLI, Yarn, etc). Live Package Updates allows you to override the version of these
dependencies and specify either a specific version, or always ensure the latest version is installed. If
Live Package Updates is enabled, before your build is executed, the build runner will first update (or
downgrade) the specified dependencies. This will increase the build time proportional to the time it takes
to update the dependencies, but the benefit is that you can ensure the same version of a dependency is
used to build your app.

Configuring Live Updates

1. From your App Detail page, choose App Settings > Build Settings.
2. From the Build image settings section, choose Edit.

64
 AWS Amplify Console User Guide
Configuring Live Updates

3. Select a package you’d like to change from the Add package version override list.

4. Input either a specific version of this dependency, or keep the default (latest). If latest is used, the
dependency will always be upgraded to the latest version available. Choose Save to apply the settings.

65
 AWS Amplify Console User Guide

AWS CloudFormation support

Access the Amplify Console CloudFormation documentation

Use AWS CloudFormation templates to provision Amplify Console resources, enabling repeatable and
reliable web app deployments. CloudFormation provides a common language for you to describe and
provision all the infrastructure resources in your cloud environment and simplifies the roll out across
multiple AWS accounts and/or regions with just a couple of clicks.

66
 AWS Amplify Console User Guide
Step 1: Login to the IAM Console

Adding a Service Role to the Amplify

Console When You Connect an App
The Amplify Console requires permissions to deploy backend resources with your front end. You use a
service role to accomplish this. A service role is the IAM role that Amplify Console assumes when calling
other services on your behalf. In this guide, you will create an Amplify service role that has full access to
the account which is required to deploy any Amplify CLI resources. Learn more.

Step 1: Login to the IAM Console

Login to the IAM Console and choose Roles from the left navigation bar, then choose Create role.

Step 2: Create Amplify role

In the role selection screen find Amplify and select the Amplify-Backend Deployment role. Accept all
the defaults and choose a name for your role (e.g. AmplifyConsoleServiceRole-AmplifyRole).

Step 3: Return to the Amplify Console

In the Amplify Console onboarding screen, choose refresh, and then pick the role you just created. It
should look like AmplifyConsoleServiceRole-AmplifyRole.

67
 AWS Amplify Console User Guide
Step 3: Return to the Amplify Console

If you already have an existing app, you can find the service role setting in App settings > General and
then choose Edit from the top right corner of the box. Pick the service role you just created from the
dropdown and choose Save.

The Amplify Console now has permissions to deploy backend resources.

68
 AWS Amplify Console User Guide

Instant Cache Invalidations

The Amplify Console supports instant cache invalidation of the CDN on every code commit. This enables
you to deploy updates to your single page or static app instantly — without giving up the performance
benefits of content delivery network (CDN) caching.

Learn more about how the Amplify Console handles cache invalidations.

69