AWS Amplify is a set of purpose-built tools and features that lets frontend web and mobile developers quickly and easily build full-stack applications on AWS, with the flexibility to leverage the breadth of AWS services as your use cases evolve. AWS Amplify Hosting is a fully managed CI/CD and hosting service for fast, secure, and reliable static and server-side rendered apps that scale with your business. It supports modern web frameworks such as React, Angular, Vue, Next.js, Gatsby, Hugo, Jekyll, and more.
Amazon Cognito lets you add user sign-up, sign-in, and access control to your web and mobile apps quickly and easily. Amazon Cognito scales to millions of users and supports sign-in with social identity providers, such as Apple, Facebook, Google, and Amazon, and enterprise identity providers via SAML 2.0 and OpenID Connect.
Prerequisites
- AWS Account with Administrator access
- AWS Amplify CLI
- NodeJS 14.x or later
- Visual Studio Code
- Git for Windows/Linux
- GitHub account
What you will learn
- Install and configure AWS Amplify CLI
- Host your React frontend using AWS Amplify with GitHub
- Create a service role for AWS Amplify build process
- Configure Amplify on React application locally
- Enable authentication for React application using Cognito user pool
Install and configure AWS Amplify CLI
1) Before you start configuring the application with AWS amplify you need to deploy the AWS Amplify CLI on local development machine. Verify the NodeJS version before installing the AWS amplify CLI.
node --version
2) Make sure the latest versions of NodeJS is installed in your machine. Ensure it is 14.x or later version of NodeJS runtime.
3) Install the AWS Amplify CLI globally by running the following command.
npm install -g @aws-amplify/cli
4) Amplify CLI uses the IAM user account to create and manage AWS resources for you. You need to create an IAM user with administrative access. Immediately after you install the Amplify CLI, you need to run the following command to configure the IAM user credentials for CLI.
amplify configure
5) This command will take you through a series of steps to create an IAM administrator user. If you have user created already you can speicify the username and skip the user creation step. Specify the Access Key ID and Secret Access Key of user when prompted.
Host your React frontend using AWS Amplify with GitHub
1) Open the command terminal and run the following command to clone the sample employee-portal React application.
git clone https://github.com/sonusathyadas/aws-amplify-reactjs.git
2) Switch to the project folder and restore all npm packages.
cd aws-amplify-reactjs\employee-portal
npm install
3) Initialize the git repository in the employee-portal project.
git init
4) Add all files to staging and commit the changes.
git add .
git commit -m "initial commit"
5) Now, you need to create a GitHub repository in your GitHub account and push the code to the repository. Create a repository with the name employee-portal-ui and the push the code to it.
git branch -M main
git remote add origin <GIT_REPOSITORY_URL>
git push -u origin main
[!NOTE] Replace the <GIT_REPOSITORY_URL> with your employee-portal-ui repository URL.
6) Open the AWS Management Console in a new browser window. Search for Amplify and navigate to Amplify service console.
7) In the Amplify service console, Scroll down to the Get Started section and click on the Get Started button under Amplify Hosting.
8) For the code repository select GitHub and click Continue. You need to login to your GitHub account and allow AWS to access the repositories.
9) After the login is successful, select the employee-portal-ui repository from the dropdown list and select main branch from Branch list. Click Next to continue.
10) In the Configure build settings page, you can update the application name if you wish or leave it as default. Verify the build configuration YAML and click Next.
11) Review the configuration settings and click on Save and Deploy. This will start the deployment process of React frontend web application. You can see the progress of the build process.
12) After the deployment is successfully completed click on the thumbnail on the left side or click on the URL to launch the application.
13) Your application is now successfully configured for CI/CD. Any code changes made on the code will be redeployed automatically when you push the code to the GitHub repository.
14) Open the project in Visual Studio Code and open src\components\Home.jsx file. Update the page heading from <h2>Home</2> to <h2>Employee List</h2> inside the render method.
render() {
return (
<EmployeeContext.Provider value={{ employees: this.state.filteredResults, loadedAt: new Date(), doSearch: this.handleSearch }}>
<Container>
<Row>
<Col><h2>Employee List</h2></Col>
</Row>
<Row>
<Col><SearchBar /></Col>
</Row>
<Row>
<Col>
<UserList />
</Col>
</Row>
</Container>
</EmployeeContext.Provider>
);
}
15) Save the changes and push the code changes to GitHub repository.
git add .
git commit -m "heading updated"
git push -u origin main
16) You can see the commit triggering the build process in Amplify console.
17) After the deployment is successful, reload the application to see the changes.
Create a service role for AWS Amplify build process
You need to enable Amplify on your React project which helps you to add Cognito authentication. To build the backend services, you need to create and configure a Service role for your Amplify project.
1) Open the AWS management console and search for IAM. Navigate to the IAM service console.
2) Click on the Roles link on the left pane to view the existing list of roles. Click on the Create role button to start creating a new Role.
3) Select AWS Service and choose Amplify from the list of AWS Services. In the Select your use case section choose Amplify - Backend Deployment and click Next:Permissions.
4) In the policy section you can see the AdministratorAccess-Amplify policy selected by default. Click on the Next:Tags.
5) You can optionally provide the tags for your role. Click on the Next:Review button.
6) Specify the service role name as AmplifyConsoleServiceRole-AmplifyRole and click Create role.
7) Open you employee-portal-ui Amplify project in AWS management console. Under the App settings click on the General section.
8) Click on the Edit button to update the app details. For the Service role select the AmplifyConsoleServiceRole-AmplifyRole service role and click on Save button.
Configure Amplify on React application locally
1) Open the Amplify project in AWS Amplify service console. click on Backend environments and click on Get started. Wait for the back end to be deployed.
2) After the backend is provisioned successfully, click on the Launch Studio button to open the Amplify studio.
3) Go back to the Amplify Console Backend environments tab and open the Local setup instructions. Copy the command to your clipboard and open the terminal on your computer. Set the terminal path to the react application folder and run the command.
amplify pull --appId d3cplee02ijndg --envName staging
4) You need to authenticate to AWS account. After the authentication is successful, follow the instructions to configure the amplify in project.
- Choose your default editor: Visual Studio Code
- Choose the type of app that you are building: javascript
- What javascript framework are you using: react
- Source Directory Path: src
- Distribution Directory Path: build
- Build Command: npm run-script build
- Start Command: npm run-script start
- Do you plan on modifying this backend? Y
Enable authentication for React application using Cognito user pool
1) Open the React project in Visual Studio Code. Open the terminal and install the following npm packages to the project.
npm install aws-amplify @aws-amplify/ui-react
[!IMPORTANT] This will be installing the latest version of @aws-amplify/ui-react package. You need to update the amplify CLI in the Amplify management console to use the latest version for successfully building the project.
2) To enable the authentication service on the project run the following command. It will prompt for the authentication mode and sign in method.
amplify add auth
? Do you want to use the default authentication and security configuration? : Default configuration ? How do you want users to be able to sign in? : Username ? Do you want to configure advanced settings? : No, I am done.
3) Now that the authentication service has been configured locally. Before you push the changes to AWS you can update the name of user pool and identity pool.It is optional to do this. To update the names of user pool and identitypool open the amplify\backend\auth\<random-name>\cli-inputs.json file and update the values for identityPoolName and userPoolName attributes.
{
"version": "1",
"cognitoConfig": {
"identityPoolName": "employee_identitypool",
"allowUnauthenticatedIdentities": false,
"resourceNameTruncated": "employ8203a640",
"userPoolName": "employee_userpool",
"autoVerifiedAttributes": [
"email"
],
......
4) Now we can deploy it by running the Amplify push command.
amplify push --y
5) Open the App.js file in your react application and add the following code below all import statements
import { Amplify } from 'aws-amplify';
import { Authenticator } from '@aws-amplify/ui-react';
import '@aws-amplify/ui-react/styles.css';
import awsExports from './aws-exports';
Amplify.configure(awsExports);
6) Update the App component code with the following. This will add a signout link and shows currently logged in user name in the navigation bar.
function App() {
return (
<Authenticator loginMechanisms={['username']}>
{({ signOut, user }) => (
<Router>
<Navbar bg="dark" variant="dark">
<Container>
<Navbar.Brand href="#home">{process.env.REACT_APP_APP_NAME}</Navbar.Brand>
<Nav className="me-auto">
<Nav.Link as={Link} to="/" >Home</Nav.Link>
<Nav.Link as={Link} to="/about">About</Nav.Link>
<Nav.Link as={Link} to="/contact">Contact</Nav.Link>
<Nav.Link onClick={signOut}>Sign out</Nav.Link>
<Nav.Link href ="#" > Welcome {user.username}</Nav.Link>
</Nav>
</Container>
</Navbar>
<div>
<Routes>
<Route exact path="/" element={<Home />}></Route>
<Route exact path="about" element={<About />}></Route>
<Route exact path="contact" element={<Contact />}></Route>
<Route exact path="employees/loc/:loc/code/:code" element={<EmployeeDetail />}></Route>
<Route exact path="employees/new" element={<EmployeeForm />} ></Route>
<Route path="*" element={<Navigate to="/" />} />
</Routes>
</div>
</Router>
)}
</Authenticator>
);
}
7) Now, you can test the application locally by running the following command.
npm start
8) Application will launch with a login page, click on the Create account and create a new user account. You need to use a valid email id while registering new user. A verification code will be sent to a specified email.
9) After you create the user successfully, you will be logged in automatically and redirected to application home page.
10) Next, we need to configure the Amplify build process to add the backend as part of the continuous deployment workflow. From your terminal window run the following command to open amplify console.
amplify console
Which site do you want to open? · Console
11) This will open the AWS console. Select the Amplify project and open App Settings > Build Settings page. Click on the Edit button to edit the Amplify.yml file. Add the following lines of code above the frontend.
backend:
phases:
build:
commands:
- '# Execute Amplify CLI with the helper script'
- amplifyPush --simple
The complete YAML file looks like:
version: 1
backend:
phases:
build:
commands:
- '# Execute Amplify CLI with the helper script'
- amplifyPush --simple
frontend:
phases:
preBuild:
commands:
- npm ci
build:
commands:
- npm run build
artifacts:
baseDirectory: build
files:
- '**/*'
cache:
paths:
- node_modules/**/*
12) Also, you need to update the Amplify CLI version to the latest in the build settings. This will override the default version of Amplify CLI in console with the latest version. In the Build Settings page scroll down to bottom and click on the Edit button for Build image settings.
13) Click on the Add package version override and choose Amplify CLI. Make sure the latest is given as the value for the version.
14) Next, update your front end branch to point to the backend environment you just created. Under the branch name, choose Edit.
15) In the Edit target backend dialog, point your frontend main branch to the backend you just created. Choose Save.
16) Go back to the terminal in your local machine and run the following commands to push the changes to the GitHub repository.
git add .
git commit -m “added auth”
git push origin main
17) This will start the build and deploy process automatically. Wait for the build process to complete. Click on the frontend thumbnail or click on the Url to launch the application.
18) Login with the Cognito user account which you have registered earlier.
Join the conversation! Your thoughts help the community grow.