AWS Amplify - Console User Guide · 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,

AWS AmplifyConsole User Guide

AWS Amplify: Console User GuideCopyright © 2020 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 notAmazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages ordiscredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who mayor may not be affiliated with, connected to, or sponsored by Amazon.


Table of ContentsWhat is the AWS Amplify Console? .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Get started .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Amplify Console Features .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Modern Web Applications .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Getting Started .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Step 1: Connect Repository .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Step 2: Confirm Build Settings for the Front End .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Step 3: Confirm Build Settings for the Backend .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Step 4: Add Environment Variables (Optional) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Step 5: Save and Deploy .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Next Steps .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Getting Started with Fullstack Deployments .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Step 1: Deploy a fullstack sample .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Step 2: Explore the Fullstack App .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Step 3: Add a GraphQL backend .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Next steps: Set up feature branch deployments .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Setting Up Custom Domains .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Adding a Custom Domain Managed in Amazon Route 53 .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Adding a Custom Domain Managed by a Third-Party DNS Provider ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Adding Subdomains .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Troubleshooting Guide .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

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

Connecting to Third-Party Custom Domains .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Connecting to a GoDaddy Domain .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Connecting to a Google Domain .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Configuring Build Settings .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26YML Specification Syntax .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Branch-Specific Build Settings .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Navigating to a Subfolder ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Deploying the Backend with Your Front End .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Setting the Output Folder ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Installing Packages as Part of Your Build .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Using a Private npm Registry .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Installing OS packages .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Key-value storage for every build .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Skip Build for a Commit .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Disable Automatic builds .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Feature Branch Deployments .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Team workflows with Amplify CLI backend environments .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Feature branch workflow ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17GitFlow workflow ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Per-developer sandbox .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Pattern-based feature branch deployments .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Manual Deploys .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Drag and Drop .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Amazon S3 or any URL .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

One-click Deploy Button .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Add ‘Deploy to Amplify Console’ button to your repository or blog .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Previews .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Enable web previews .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

iii


End-to-End Testing .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Tutorial: Set up end-to-end tests with Cypress .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Add tests to your existing Amplify app .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Disabling tests ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Using Redirects ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Types of Redirects ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Parts of a Redirect ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Order of Redirects ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Simple Redirects and Rewrites ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Redirects for Single Page Web Apps (SPA) .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Reverse Proxy Rewrite .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Trailing slashes and Clean URLs .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Placeholders ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Query Strings and Path Parameters ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Region-based Redirects ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Restricting Access .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Environment Variables .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Setting Environment Variables .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Accessing Environment Variables .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Amplify Console Environment Variables .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Custom Headers .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Example: Security Headers .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Incoming Webhooks .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Access logs .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Analyzing access logs .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Custom Builds .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Custom Build Images .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Configuring a Custom Build Image .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Custom Build Image Requirements .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Live Package Updates .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Configuring Live Updates .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

CloudFormation Support ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Creating a Service Role .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Step 1: Login to the IAM Console .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Step 2: Create Amplify role .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Step 3: Return to the Amplify Console .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Managing Your App's Performance .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

iv

AWS Amplify Console User GuideGet started

Welcome to the AWS AmplifyConsole

The AWS Amplify Console provides a Git-based workflow for hosting fullstack serverless web apps withcontinuous deployment. A fullstack serverless app consists of a backend built with cloud resourcessuch as GraphQL or REST APIs, file and data storage, and a frontend built with single page applicationframeworks 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 startedTo 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 fullstacksamples (p. 8). Amplify Console automatically detects the front end build settings along with anybackend functionality provisioned with the Amplify CLI (command-line toolchain for creating serverlessbackends).

Amplify Console FeaturesWith the Amplify Console, you can do the following:

• Manage production and staging environments for your frontend and backend by connecting newbranches. See feature branch deployments (p. 31).

• Connect your custom domain. If you manage your domain in Amazon Route 53, the Amplify Consoleautomatically connects the root (yourdomain.com), www subdomains (www.yourdomain.com), andbranch (https://dev.yourdomain.com) subdomains. See custom domains (p. 13).

• Preview changes during code reviews by setting up Pull-Request Previews (p. 45).• Improve your app quality with end to end tests. See End-to-End Testing (p. 47).• Password protect your web app so you can work on new features without making them publicly

accessible. See restricting access (p. 56).• Set up rewrites and redirects to maintain SEO rankings and route traffic based on your client app

requirements. See redirects (p. 50).

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 ApplicationsModern web applications are constructed as single page web applications that package all applicationcomponents into static files. Traditional client-server web architectures led to poor experiences–

1

https://dev.yourdomain.com

AWS Amplify Console User GuideModern 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 functionalitywithout 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 AWSLambda 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 toavoid partial or failed deployments. The AWS Amplify Console simplifies deployment of the front endand backend in a single workflow.

2

AWS Amplify Console User GuideStep 1: Connect Repository

Getting Started with Existing Code

In this walkthrough, you learn how to continuously build, deploy, and host a modern web app. Modernweb apps include Single Page App (SPA) frameworks (for example, React, Angular, or Vue) and static-sitegenerators (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 RepositoryConnect your GitHub, Bitbucket, GitLab, or AWS CodeCommit repositories. You also have theoption of manually uploading your build artifacts without connecting a Git repository (see ManualDeploys (p. 42)). After you authorize the Amplify Console, Amplify fetches an access token from therepository provider, but it doesn’t store the token on the AWS servers. Amplify accesses your repositoryusing deploy keys installed in a specific repository only.

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

3

https://console.aws.amazon.com/amplify/home

AWS Amplify Console User GuideStep 2: Confirm Build Settings for the Front End

Step 2: Confirm Build Settings for the Front EndFor the selected branch, Amplify inspects your repository to automatically detect the sequence of buildcommands 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 saveyour build settings on our servers, or you can download the YML and add it to the root of your repo (formonorepos, store the YML at the app’s root directory).

4

AWS Amplify Console User GuideStep 3: Confirm Build Settings for the Backend

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

Step 3: Confirm Build Settings for the BackendIf 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 provisionedby the Amplify CLI) in a single workflow with the frontend build. You can choose to point an existingbackend environment to your branch, or create a completely new environment. For a step-by-steptutorial, see Deploying a fullstack app (p. 8).

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

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

5

AWS Amplify Console User GuideStep 4: Add Environment Variables (Optional)

Step 4: Add Environment Variables (Optional)Almost every app needs to get configuration information at runtime. These configurations can bedatabase connection details, API keys, or different parameters. Environment variables provide a means toexpose these configurations at build time.

Step 5: Save and DeployReview all of your settings to ensure everything is set up correctly. Choose Save and deploy to deployyour web app to a global content delivery network (CDN). Your front end build typically takes 1 to 2minutes 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 followingstages:

1. Provision - Your build environment is set up using a Docker image on a host with 4 vCPU, 7GBmemory. Each build gets its own host instance, ensuring that all resources are securely isolated. Thecontents 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), deploybackend (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 managedby Amplify. Every deployment is atomic - atomic deployments eliminate maintenance windows byensuring 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 inmultiple device resolutions using Headless Chrome.

6

AWS Amplify Console User GuideNext Steps

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

7

AWS Amplify Console User GuideStep 1: Deploy a fullstack sample

Getting Started with FullstackContinuous Deployments

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

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

Step 1: Deploy a fullstack sampleLog in to the Amplify Console and choose Get Started under Deploy. In the following screen, chooseFrom fullstack samples. Alternatively, start your own adventure by building a backend from scratch byinstalling the Amplify CLI.

8


AWS Amplify Console User GuideStep 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 inyour account, deploy the AWS backend services, and build and deploy the frontend. In order to deploybackend resources to AWS, you will need to create a service role (p. 69).

Step 2: Explore the Fullstack AppYour app build will start by deploying the backend followed by the frontend. Click on the branch nameto see the running build. When the build completes you will be able to see screenshots of your app ondifferent devices.

9

AWS Amplify Console User GuideStep 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 whichlinks to the Amazon Cognito UserPool. Create a user and try logging in to your app.

10

AWS Amplify Console User GuideStep 3: Add a GraphQL backend

Step 3: Add a GraphQL backend1. 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.gitcd create-react-app-auth-amplify

2. From the Backend environments tab, choose Edit backend. As a pre-requisite, follow the instructionsto install and configure the Amplify CLI. The Amplify command line toolchain allows you to editthe backend you just created to add more functionality such as GraphQL/REST APIs, analytics, andstorage. Once the Amplify CLI is configured, copy the amplify pull command to connect to thisbackend 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 withthe 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

https://aws-amplify.github.io/docs/cli-toolchain/graphql

AWS Amplify Console User GuideNext steps: Set up feature branch deployments

amplify pushCurrent 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 cloudGraphQL endpoint: https://gumwpbojgraj5b547y5d3shurq.appsync-api.us-west-2.amazonaws.com/graphqlGraphQL API KEY: da2-vlthvw5qcffxzl2hibgowv3rdq

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

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

Next steps: Set up feature branch deploymentsFollow our recommended workflow to set up feature branch deployments with multiple backendenvironments.

12

https://aws-amplify.github.io/docs/js/api#amplify-graphql-client

https://docs.aws.amazon.com/amplify/latest/userguide/multi-environments.html#team-workflows-with-amplify-cli-backend-environments

https://docs.aws.amazon.com/amplify/latest/userguide/multi-environments.html#team-workflows-with-amplify-cli-backend-environments

AWS Amplify Console User GuideAdding a Custom Domain Managed in Amazon Route 53

Setting Up Custom DomainsYou 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, itis 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 issecured through HTTPS/2. The SSL certificate generated by Amazon Certificate Manager is valid for 13months 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 AmazonRoute 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 Adddomain.

2. In Enter your root domain, enter your root domain (https://awesomedomain.com). As youstart 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 GuideAdding 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 wwwsubdomain to the root domain (you can change this by choosing Rewrites and redirects from the leftmenu). You can modify the default configuration if you want to add subdomains only, see: Connectingsubdomains (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 moreinformation 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 DNSprovider if you don’t use Amazon Route 53.

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

2. In Enter your root domain, enter your root domain (https://awesomedomain.com) and then chooseConfigure domain. If the domain is registered, a green alert notifies you to proceed as long you arethe owner of the domain. If the domain is available, purchase a domain at Amazon Route 53.

14

https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-register.html

AWS Amplify Console User GuideAdding a Custom Domain Managed

by a Third-Party DNS Provider

3. By default, the Amplify Console adds two entries for https://www.awesomedomain.com andhttps://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: Connectingsubdomains (p. 16). Choose Save after configuring your domain.

4. Because the domain is managed externally you must manually configure your DNS provider (forexample, 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 ofyour domain, all traffic will be served using HTTPS/2.

b. Configure CNAME record to point your subdomains (https://*.awesomedomain.com) to theamplifyapp domain. NOTE: If you have production traffic it is recommended you update yourCNAME record after your domain status shows AVAILABLE.

c. Configure ANAME/ALIAS record to point the root domain (https://awesomedomain.com) to youramplifyapp 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 yourDNS to Amazon Route 53.<problematic>**</problematic>NOTE: If you have production traffic it is recommended you update your ANAME record after yourdomain status shows AVAILABLE.*

15

https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/dns-configuring.html


AWS Amplify Console User GuideAdding Subdomains

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

Adding SubdomainsA 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 connecta subdomain (eg https://alpha.mydomain.com). You can do this by choosing Exclude root andmodifying 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 searchbar, choosing Exclude root, and modifying the subdomain to beta as shown below.

16

AWS Amplify Console User GuideTroubleshooting Guide

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

Troubleshooting GuideThis guide will help you troubleshoot issues regarding the setup of a custom domain in the AWS AmplifyConsole.

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 Terminology1. 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 GuideTechnical Terminology

point a subdomain to a Fully Qualified Domain name (FQDN). For example, we can create a newCNAME 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 rootof 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 thelocation of a domain name’s various services. If you have your domain setup in AWS Route53, you willhave 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 tohappen 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 thatyou are the owner of the domain. For domains managed by Route53, we will automatic update theDNS verification record. For domains managed outside of Route53, you will need to manually add thedisplayed 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 DNSprovider.

Understanding DNS Verification

DNS stands for Domain Name System, and is commonly referred to being a phone book, translatinghuman-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 IPAddress of server which hosts the website.

18

AWS Amplify Console User GuideHow do I verify that my CNAME resolves?

DNS providers contain records of domains and their corresponding IP Addresses. Here are the mostcommonly 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 yourdomain with AWS Route53, verification is done on your behalf. However, if you host your domain with aThird 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 thatyour 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

https://www.whatsmydns.net/

https://en.wikipedia.org/wiki/Dig_(command)

https://www.whatsmydns.net/

AWS Amplify Console User GuideMy domain hosted with a third partyis stuck in Pending Verification state

My domain hosted with a third party is stuck inPending Verification stateThe first thing you’ll want to do is to verify if your CNAME records are resolving. See previous step forinstructions. If you CNAME records are not resolving, then you should confirm that the CNAME entryexists in the your DNS Provider.

Note: If you added or updated your CNAME records a few hours after youcreated your app, this will most likely cause your app to get stuck inthe pending verification state. It is important that you update yourCNAME 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 todetermine if it resolves. If it doesn’t resolve after an hour, the check is made every few hours which canlead 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 DNSprovider. You can either contact the DNS provider to diagnose why the DNS verification CNAME is notresolving or migrate your DNS to Route53.

My domain hosted with AWS Route53 is stuck inPending Verification stateIf you transferred your domain to AWS Route53 then it’s possible that your domain has differentnameservers then those issued by the Amplify Console when your app was created. Login to the Route53console, choose Hosted Zones from the left navigation, and pick the domain you are connecting. Recordthe nameserver values.

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

20

https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/MigratingDNS.html

https://console.aws.amazon.com/route53/home

https://console.aws.amazon.com/route53/home

AWS Amplify Console User GuideCNAMEAlreadyExistsException Error

If this did not resolve the issue, please check our GitHub Issues and open a new issue if it doesn’t alreadyexist.

CNAMEAlreadyExistsException ErrorThis 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 tryingto reuse one of the hostnames. If you are using www.domain.com on the other app, you cannot usewww.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 check our GitHub Issues and open a new issue if it doesn’t already exist.

21

https://github.com/aws-amplify/amplify-console/issues

https://console.aws.amazon.com/cloudfront/home?#

https://github.com/aws-amplify/amplify-console/issues

AWS Amplify Console User GuideConnecting to a GoDaddy Domain

Connecting to Third-Party CustomDomains

Connecting to a GoDaddy Domain1. 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 recordto point to Amazon Certificate Manager’s validation server. A single validated ACM generates an SSLcertificate for your domain. Make sure you only enter the subdomain in Host as shown below (don’tenter yourdomainname.com).

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

22



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

23


24

AWS Amplify Console User GuideConnecting to a Google Domain

Connecting to a Google Domain1. 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 AmazonCertificate Manager’s validation server. A single validated ACM generates an SSL certificate for yourdomain.

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 keepyour current provider and update the root domain, add a Synthetic Record, and set up a SubdomainForward. In Subdomain, enter the @ symbol and then choose Forward path as shown following:

25

https://domains.google


AWS Amplify Console User GuideYML Specification Syntax

Configuring Build SettingsThe Amplify Console automatically detects the front end framework and associated build settings byinspecting 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 andsaves it so that they can be accessed via the Amplify Console. These settings are applied to all of yourbranches 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 ofyour 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 buildsettings are applied to all the branches in your app, except for the branches that have a YML file saved inthe repository.

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

version: 1.0env: variables: key: valuebackend: 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 GuideBranch-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 theconsole.

• backend - Run Amplify CLI commands to provision a backend, update Lambda functions, or GraphQLschemas 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. 47).

• The frontend, backend, and test have three phases that represent the commands run during eachsequence of the build.

• preBuild - The preBuild script runs before the actual build starts, but after we have installeddependencies.

• build - Your build commands.

• postBuild - The post-build script runs after the build has finished and we have copied all thenecessary 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.

• cache - The buildspec’s cache field is used to cache build-time depedencies such as the node_modulesfolder, and is automatically suggested based on the package manager and framework that thecustomer’s app is built in. During the first build, any paths here are cached, and on subsequent buildswe re-inflate the cache and use those cached dependencies where possible to speed up build time.

• customHeaders - Custom header rules set on deployed files. See custom headers (p. 60).

Branch-Specific Build SettingsYou can use bash shell scripting to set branch-specific build settings. For example, the following scriptuses the system environment variable $AWS_BRANCH to execute one set of commands if the branchname is master and a different set of commands if the branch name is dev.

frontend:

27

AWS Amplify Console User GuideNavigating to a Subfolder

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

Navigating to a SubfolderFor 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.0env: variables: key: valuefrontend: phases: preBuild: commands: - cd react-app - npm ci build: commands: - npm run build

Deploying the Backend with Your Front EndThe amplifyPush is a helper script that helps you with backend deployments. The build settings belowautomatically determine the correct backend environment to deploy for the current branch.

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

Setting the Output FolderThe following build settings set the output directory to the public folder.

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

28

AWS Amplify Console User GuideInstalling Packages as Part of Your Build

Installing Packages as Part of Your BuildYou can use npm or yarn to install packages during the build.

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

Using a Private npm RegistryYou 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 packagesYou can install OS packages for missing dependencies.

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

Key-value storage for every buildThe envCache provides key-value storage at build time. Values stored in the envCache can onlybe modified during a build and can be re-used at the next build. Using the envCache, we can storeinformation on the deployed environment and make it available to the build container in successivebuilds. Unlike values stored in the envCache, changes to environment variables during a build are notpersisted to future builds.

Example usage:

envCache --set <key> <value>envCache --get <key>

29

AWS Amplify Console User GuideSkip Build for a Commit

Skip Build for a CommitTo skip an automatic build on a particular commit, include the text [skip-cd] at the end of the commitmessage.

Disable Automatic buildsYou can configure Amplify Console to disable automatic builds on every code commit. To set up, chooseApp settings > General and then scroll to the section with all the connected branches. Select a branch,and then choose Action > Disable auto build. Further commits to that branch will no longer trigger anew build.

30

AWS Amplify Console User GuideTeam workflows with Amplify CLI backend environments

Feature branch deployments andteam workflows

The Amplify Console is designed to work with feature branch and GitFlow workflows. The AmplifyConsole leverages Git branches to create new deployments every time a developer connects a newbranch in their repository. After connecting your first branch, you can create a new feature branchdeployment 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 tracksrelease code and is your production branch. The develop branch is used as an integration branch to testnew 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 backendenvironments

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

31

https://docs.aws.amazon.com/amplify/latest/userguide/deploy-backend.html

AWS Amplify Console User GuideFeature branch workflow

You can use the Amplify Console to continuously deploy backend resources such as GraphQL APIs andLambda functions with your feature branch deployment. You can use the following models to deployyour 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 usingbootstrap tools like create-react-app or Gatsby.

create-react-app next-unicorncd next-unicornamplify 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


? 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. Navigatea level up from the breadcrumb to view a list of all backend environments created in the Backendenvironments tab.

33


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

34


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

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

35


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

git checkout -b newinternetamplify env checkout devamplify 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 branchdirectly 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 yourteammates. If everything looks good merge the PR to the develop branch.

git checkout developgit merge newinternetgit push

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

36

AWS Amplify Console User GuideGitFlow workflow

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

git push origin --delete newinternetaws amplify delete-branch --app-id <appid> --branch-name <branchname>amplify env remove dev

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

The diagram below shows a recommended setup with GitFlow. You can follow the same process asdescribed 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 teammembers’ changes.

• Each branch in the Amplify Console has its own backend. This ensures that the Amplify Console usesthe Git repository as a single source of truth from which to deploy changes, rather than relying ondevelopers on the team to manually push their backend or front end to production from their localcomputers.

37

AWS Amplify Console User GuidePer-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 usingbootstrap tools like create-react-app or Gatsby.

cd next-unicornamplify 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 GuidePattern-based feature branch deployments

3. The Amplify Console will detect backend environments created by the Amplify CLI. Choose Createnew environment from the dropdown and grant the service role to Amplify Console. Choose Saveand 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 thispoint) and choose Create new environment. After the build completes you will get a develop branchdeployment available at https://develop.appid.amplifyapp.com with a new backend environment thatis linked to the branch.

Pattern-based feature branch deploymentsPattern-based branch deployments allow you to automatically deploy branches that match a specificpattern to the Amplify Console. Product teams using feature branch or GitFlow workflows for theirreleases, 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

https://dev.to/kkemple/branch-based-deployment-strategies-with-aws-amplify-console-1n3c


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 settingBranch autodetection - access control to Enabled.

3. For applications built with an Amplify backend, you can choose to create a new environment or pointall branches to an existing backend.

40


41

AWS Amplify Console User GuideDrag and Drop

Manual Deploys

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

Drag and DropDrag and drop a folder from your desktop to host your site in seconds. Log in to the Amplify Consoleand 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 URLReference assets that are uploaded to an Amazon S3 bucket, or provide a public URL to files storedelswhere.

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

42


http://aws.amazon.com/blogs/mobile/deploy-files-s3-dropbox-amplify-console/

AWS Amplify Console User GuideAmazon S3 or any URL

Note: When you are uploading the zip folder make sure you zip the contents of your build outputand not the top level folder. For example if your build output generates a folder named “build” or“public” first navigate into that folder, select all of the contents and zip it from there. If you do notdo this then you will see an “Access Denied” error because the sites root directory will not be initializedproperly.

43

AWS Amplify Console User GuideAdd ‘Deploy to Amplify Console’button to your repository or blog

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

Add ‘Deploy to Amplify Console’ button to yourrepository or blog

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

1. An SVG image: https://oneclick.amplifyapp.com/button.svg2. 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 AmplifyConsole will deploy the default branch in your repository. Additional branches can be connected afterthe 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.

[![amplifybutton](https://oneclick.amplifyapp.com/button.svg)](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 GuideEnable web previews

Web Previews

Web Previews offer development and QA teams a way to preview changes from pull requests beforemerging code to a production or integration branch. Pull requests let you tell others about changesyou’ve pushed to a branch in a repository. Once a pull request is opened, you can discuss and review thepotential changes with collaborators and add follow-up commits before your changes are merged intothe base branch.

A web preview deploys every pull request made to your GitHub repository to a unique preview URL;completely different from the one your main site uses. For apps with backend environments provisionedvia the Amplify CLI, every pull request (private Git repositories only) spins up an ephemeral backendthat is deleted when the PR is closed.

Enable web previews1. Choose App settings > Previews and Enable previews. For GitHub repositories only, you are required

to install a GitHub app in your account to enable this feature. You can give the Amplify Consolepermission to all repositories or only the current one. Note: For security purposes, Previews will onlywork with private repositories for fullstack apps using the Amplify CLI.

2. Once enabled, return to the Amplify Console to enable previews for specific branches. Pick a branchfrom the list and choose Manage. For fullstack applications, you will be able to choose to create a anew backend for every pull request, or point all pull requests to an existing backend environment.Choosing the first option will allow you to test changes without impacting production.

1. The next time you submit a pull request for the branch, the Amplify Console will build and deployyour PR to a preview URL For GitHub repositories only, you can view a preview of your URL directlyfrom the pull request.

45

AWS Amplify Console User GuideEnable web previews

1. Once the pull request is closed, the preview URL is deleted, and any ephemeral backend environmentlinked to the pull request is deleted.

46

AWS Amplify Console User GuideTutorial: 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 beforepushing code to production. The test phase can be configured in the build specification YML and can beused to run any testing framework of your choice during a build.

Tutorial: Set up end-to-end tests with CypressCypress is a JavaScript-based framework that allows you to run E2E tests on a browser. This tutorial willdemonstrate how to set up E2E tests from scratch.

47

http://aws.amazon.com/blogs/mobile/run-end-to-end-cypress-tests-for-your-fullstack-ci-cd-deployment-with-amplify-console/

AWS Amplify Console User GuideAdd tests to your existing Amplify app

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

test: phases: preTest: commands: - npm ci - 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 cypress/report/mochawesome-report/mochawesome*.json > 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 thebuild.

• 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 testsOnce the “test” config has been added to your amplify.yml build settings, the test step will be executedfor every build, on every branch. If you would like to globally disable tests from running, or you wouldonly like tests to run for specific branches, you can use the “USER_DISABLE_TESTS” environment variableto do so without modifying your build settings.

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

48

https://github.com/jeffbski/wait-on

AWS Amplify Console User GuideDisabling tests

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

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.

49

AWS Amplify Console User GuideTypes of Redirects

Using RedirectsRedirects enable a web server to reroute navigation from one URL to another. Common reasons forusing redirects include: to customize the appearance of URL, to avoid broken links, to move the hostinglocation of an app or site without changing its address, and to change a requested URL to the formneeded by a web app.

Types of RedirectsThere 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 rankinghistory 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 touse 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 engineranking history of the original address doesn’t apply to the new destination address. Redirection occurson the client-side, so a browser navigation bar shows the destination address after redirection. Commonreasons 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 servedfrom 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 afterredirection. 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 404is 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.

50

AWS Amplify Console User GuideParts of a Redirect

Parts of a RedirectRedirects 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 RedirectsRedirects are executed from the top of the list down. Make sure that your ordering has the effect youintend. For example, the following order of redirects causes all requests for a given path under /docs/ toredirect to the same path under /documents/, except /docs/specific-filename.html which redirects to /documents/different-filename.html:

/docs/specific-filename.html /documents/different-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/different-filename.html 301

51

AWS Amplify Console User GuideSimple Redirects and Rewrites

Simple Redirects and RewritesIn 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 adifferent folder.


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.


<*> /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 theuser.


https://mydomain.com

https://www.mydomain.com

rewrite (200)

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 custom404 page.


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

52

AWS Amplify Console User GuideRedirects 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 triggeringa server request. This works for users who begin their journey from the root (or /index.html), but failsfor users who navigate directly to any other page. Using regular expressions, the following example setsup a 200 rewrite for all files to index.html except for the specific file extensions specified in the regularexpression.


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

/index.html 200

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

“condition”: null}]

Reverse Proxy RewriteThe following example uses a rewrite to proxy content from another location so that it appears to userthat the domain hasn’t changed:


/images https://images.otherdomain.com

rewrite (200)

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

Trailing slashes and Clean URLsTo create clean URL structures like about instead of about.html, static site generators such asHugo generate directories for pages with an index.html (/about/index.html). The Amplify Consoleautomatically creates clean URLs by adding a trailing slash when required. The table below highlightsdifferent scenarios:

User inputs in browser URL in the address bar Document served

/about /about /about.html

/about (when about.htmlreturns 404)

/about/ /about/index.html

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

53

AWS Amplify Console User GuidePlaceholders

PlaceholdersYou can use the following example code to redirect paths in a folder structure to a matching structure inanother folder.


/docs/<year>/<month>/<date>/<itemid>

/documents/<year>/<month>/<date>/<itemid>

permanent redirect(301)

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

“condition”: null}]

Query Strings and Path ParametersYou can use the following example code to redirect a path to a folder with a name that matches thevalue of a query string element in the original address:


/docs?id=<my-blog-id-value

/documents/<my-blog-post-id-value>

permanent redirect(301)

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 afolder structure to index.html in a specified folder.


/documents/<folder>/<child-folder>/<grand-child-folder>

/documents/index.html

404

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

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


/documents /documents/us/ 302 <US>

54

AWS Amplify Console User GuideRegion-based Redirects

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

55


Restricting accessWorking on unreleased features? Password protect feature branches that are not ready to be accessedpublicly.

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 nameand password for all branches.

• You can set a password at the branch level.

56

AWS Amplify Console User GuideSetting Environment Variables

Environment Variables

Environment variables are key-value pairs that are available at build time. These configurations can beanything, 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 environmentvariables that you add are encrypted to prevent rogue access so you can use them to store secretinformation.

Setting Environment Variables1. 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 consoleapplies the environment variables across all branches, so you don’t have to re-enter variables whenyou 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 variablesspecific to your branch.

57

AWS Amplify Console User GuideAccessing Environment Variables

Accessing Environment VariablesTo access an environment variable during a build, edit your build settings to include the environmentvariable 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 yourenvironment variable during your next build.

build: commands: - npm run build:$BUILD_ENV

Amplify Console Environment VariablesYou 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 currentbuild

master

AWS_BRANCH_ARN The branch ARN of the currentbuild

arn:xxxxx/xxxx/xxxxx

AWS_CLONE_URL The clone URL used to fetch thegit repository contents

[email protected]:<user-name>/<repo-name>.git

AWS_COMMIT_ID The commit ID of the currentbuild. “HEAD” for rebuilds

xxxxxxxxxxxxxxxxxx

58

mailto:[email protected]

AWS Amplify Console User GuideAmplify Console Environment Variables

Variable name Description Example

AWS_JOB_ID The job ID of the current build.This includes some padding of‘0’ so it always has the samelength.

0000000001

_LIVE_UPDATES The tool will be upgraded to thelatest version.

[{“name”:”AmplifyCLI”,”pkg”:”@aws-amplify/cli”,”type”:”npm”,”version”:”latest”}]

59

AWS Amplify Console User GuideExample: Security Headers

Custom HeadersCustom HTTP headers allow you to specify headers for every HTTP response. Response headers can beused for debugging, security, and informational purposes. Define custom header rules for your app asfollows:

1. From the navigation bar on the left, choose App Settings > Build Settings, and then choose Edit to edityour buildspec.

2. In the frontend section of the YML file, add the custom headers for your app as follows:

version: 0.1frontend: 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 HeadersThe following security headers enable enforcing HTTPS, preventing XSS attacks, and defending yourbrowser against clickjacking. Add it to your app’s buildspec and choose Save to apply the custom headersettings.

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'

60

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers

AWS Amplify Console User GuideExample: Security Headers

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

61


Incoming Webhooks

Set up an incoming webhook in the Amplify Console to trigger a build without comitting code to your Gitrepository. Webhook triggers can be used with headless CMS tools (such as Contentful or GraphCMS) totrigger 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. ChooseCreate 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.

62



63

AWS Amplify Console User GuideAnalyzing access logs

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

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

SELECT SUM(bytes) AS total_bytesFROM logsWHERE "date" BETWEEN DATE '2018-06-09' AND DATE '2018-06-11'LIMIT 100;

64

https://docs.aws.amazon.com/athena/latest/ug/cloudfront-logs.html#create-cloudfront-table

AWS Amplify Console User GuideCustom Build Images

Custom Build Images and LivePackage Updates

Topics

• Custom Build Images (p. 65)

• Live Package Updates (p. 66)

Custom Build ImagesCustom Build Images can be used to provide a customized build environment. If you have specificdependencies that take a long time to install during a build using our default container, you can createyour own Docker image and reference it during a build. Images can be hosted on Docker Hub or a publicAmazon Elastic Container Registry. The format expected here is the same as the format Docker pullcommand (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 Image1. 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.

65

https://hub.docker.com/

https://aws.amazon.com/ecr/

AWS Amplify Console User GuideCustom Build Image Requirements

Custom Build Image RequirementsIn order for a custom build image to work as an Amplify Console build image there are a fewrequirements for the image:

1. cURL: When we launch your custom image, we download our build runner into your container, andtherefore we require cURL to be present. If this dependency is missing, the build will instantly failwithout 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 dependencyis missing, the ‘Cloning repository’ step will fail.

3. OpenSSH: In order to securely clone your repository we require OpenSSH to set up the SSH keytemporarily during the build, the OpenSSH package provides the commands that the build runnerrequires to do this.

4. (NPM-based builds)Node.JS+NPM: Our build runner does not install Node, but instead relies on Nodeand NPM being installed in the image. This is only required for builds that require NPM packages orNode specific commands.

Live Package UpdatesLive Package Updates allows you to specify versions of packages and dependencies to use in our defaultbuild 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 thesedependencies and specify either a specific version, or always ensure the latest version is installed. IfLive Package Updates is enabled, before your build is executed, the build runner will first update (ordowngrade) the specified dependencies. This will increase the build time proportional to the time it takesto update the dependencies, but the benefit is that you can ensure the same version of a dependency isused to build your app.

Configuring Live Updates1. From your App Detail page, choose App Settings > Build Settings.

2. From the Build image settings section, choose Edit.

66

AWS Amplify Console User GuideConfiguring 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, thedependency will always be upgraded to the latest version available. Choose Save to apply the settings.

67


AWS CloudFormation supportAccess the Amplify Console CloudFormation documentation

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

68

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/AWS_Amplify.html

AWS Amplify Console User GuideStep 1: Login to the IAM Console

Adding a Service Role to the AmplifyConsole When You Connect an App

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

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

Step 2: Create Amplify roleIn the role selection screen find Amplify and select the Amplify-Backend Deployment role. Accept allthe defaults and choose a name for your role (e.g. AmplifyConsoleServiceRole-AmplifyRole).

Step 3: Return to the Amplify ConsoleIn the Amplify Console onboarding screen, choose refresh, and then pick the role you just created. Itshould look like AmplifyConsoleServiceRole-AmplifyRole.

69

https://aws-amplify.github.io/docs/cli/concept

https://console.aws.amazon.com/iam/home?#/roles

AWS Amplify Console User GuideStep 3: Return to the Amplify Console

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

The Amplify Console now has permissions to deploy backend resources.

70


Instant Cache InvalidationsThe Amplify Console supports instant cache invalidation of the CDN on every code commit. This enablesyou to deploy updates to your single page or static app instantly — without giving up the performancebenefits of content delivery network (CDN) caching.

Learn more about how the Amplify Console handles cache invalidations.

71

http://aws.amazon.com/blogs/mobile/aws-amplify-console-supports-instant-cache-invalidation-and-delta-deployments/

Documents

AWS Amplify - Console User Guide · 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,