Whether you are just starting to develop a simple react single page app or a large complex application, at some point you inevitably have to get it off your machine or local development environment and out into the real world.
Today we are going to tackle this challenge with an automated repeatable process that takes advantage of AWS’s solution for Infrastructure as Code (IaC), AWS Cloud Development Kit (CDK). We’ll also automate the entire process using CircleCI from code commit to fully deployed.
What we are building:
This tutorial is going to cover the process of standing up the following:
- A new Github Repo for your React App
- All the AWS infrastructure required to host your project
- An S3 Bucket for the compi led project source files
- A CloudFront Distribution (CDN) that will make your application more easily accessible
- A automated CircleCI pipeline connected to your GitHub Repo that automatically can deploy your app
Note: A example Repo can be found here: https://github.com/patrickcze/CDKDeployedReactApp
You’ll need the following to complete this tutorial:
- A Github Account
- An AWS Account
- A CircleCI Account
I’m also going to assume some familiarity with React and Typescript but almost anyone with some web development experience should be able to follow along.
Publishing our App to Github
Start by creating a new Github Repo to store our project. This step is completely optional. If you have an existing project and you can jump down to Setting up our App’s AWS Infrastructure with CDK.
- Go to https://github.com/new and fill in the details for your new Repo.
- Clone your Repo/Project to your machine or local development environment.
Creating our App
- Open a new terminal window and navigate to the new repo you just cloned.
npx create-react-app .in the folder to get a basic react app.
- Once the install is complete run
npm startjust to make sure all is working. You should see this:
Setting up our App’s AWS Infrastructure with CDK
Great now that we have a working React app and repo lets focus on setting up our CDK scripts to create the resources we need in AWS.
Configuring CDK in your Project
- Start by installing the CDK toolkit by following the instructions here: https://docs.aws.amazon.com/cdk/latest/guide/work-with.html#work-with-prerequisites
- Make sure you have run
aws configureon your machine to configure your connection to your AWS account.
- Add a new
infrastructurefolder to your project.
- In a new terminal window navigate to the
infrastructurefolder to your project and run
cdk init app --language typescript.
- CDK will now run and setup create all of the default files you’ll need.
- Now we will install all the CDK packages we need to write our deployment scripts.
npm install --save @aws-cdk/aws-iam @aws-cdk/core @aws-cdk/aws-cloudfront @aws-cdk/aws-s3-deployment
Creating a Stack for our Project
To define all of our required resources in AWS we need to add some details to the CDK stack that the init command above created for us.
infrastruture/lib folder you should see a
infrastructure-stack.ts file, open it in your favourite IDE. And copy and paste the code below into your file.
This script with define and the following resources:
- On line 11 we create a new S3 bucket to store our compiled project source files.
- On line 20 we create a new CloudFront distribution, to act as our CDN and cache files for users accessing our application. We also define the S3 bucket as our source.
- On line 57 we create a Bucket Deploy which basically makes it easy to define source files we want to copy over to our bucket and then connect to our CDN.
- On line 65 we output the domain name of our CloudFront distribution to the console so that we can easily determine where our app was deployed to.
Next we need to make sure that our
package.json file in the infrastructure folder has the correct versions of the different packages. One common issue when writing CDK IaC scripts is that if your CDK package version are out of sync with each other, your deployment can error and fail for unexpected reasons.
You should be able to copy the details below into your own file.
Next up let’s configure some short cuts to make our deploy easier.
Deploying our App To AWS form your machine
Now that we have our infrastructure scripts setup, there are really four things we need to do for our app to deploy to AWS.
- We need to build our React application. We would run
npm run buildin the root folder of the project. Once this completes you should have a
buildfolder in the project.
2. We need to build our infrastructure stack Typescript files so we can run them. Inside of the
infrastruture folder we would run
3. We need to bootstrap our infrastructure, this is basically the process of provisioning our assets into a CloudFormation Stack. Inside of the
infrastruture folder we would run
npm run cdk bootstrap.
4. Finally we need to deploy our application, this simply requires running
npm run cdk deploy inside of the
infrastruture folder to deploy your app. You’ll need to accept the changes in the command line by typing yes.
Once the script completes you should see the script output a link to the deployed CloudFront distribution where your app can be accessed.
We can make one more improvement by adding the following script to the
scripts section of our package.json:
"deploy": "npm run build && cdk bootstrap && cdk deploy -v --require-approval never"
This one line allows us to run
npm run deploy in the
infrastruture folder and have steps 2-4 above run at at once.
Now that we have deployed our app from our local machine let’s get this working automatically with CircleCI.
Deploying our App to AWS using CircleCI and Github
- Login to your CircleCI account.
1. If you don’t already have one created you can create a free account here. https://circleci.com/signup/
- Go to your projects page, if you have already connected with your Github Account you should see your project listed.
1. If you haven’t connect your GitHub find the details here: https://circleci.com/integrations/github/
3. Click on setup project.
4. Select Use Existing Config to the top right of the code editor.
5. Click Start Building.
Now you should see a screen telling us our first job is either running or failed because we don’t have a
.circleci/config.yml file in our project. Let’s work on adding that.
If you’re not familiar with Continuous Integration/Deployment I would recommend looking into some of the other great articles on medium on the subject. But essentially what CircleCI lets us do is write a script with instructions on how we want to build and deploy our application. We can then trigger this set of instructions to happen either manually, or automatically using an event, like a pull request being merged or a commit to the master branch.
In CircleCI this script needs to live in a
.circleci folder at the root of your project to be automatically picked up.
- Create a new folder named
.circleciin the root of your project.
- Inside of that folder add a new file called
- Copy the code below into that file.
The script above is setup to only run the build and deployment process when changes to the master branch occur. This allows you to develop your work on a separate branch and then merge it to master when you’re ready to deploy.
If you want this to run every time you make a commit on any branch you can change your workflows section in the
.circleci/config.yml file to this.
To make this deployment secure we need to create a new CircleCI context to store our AWS Key and Secret so that we don’t need to commit them into our Github Repo.
- Login to your CircleCI account.
- Click on Organization Settings in the left sidebar.
3. Select Contexts on the left sidebar.
4. Click create a context.
5. Give the context a name, we called ours
aws-account, if you change this to something else make sure to update it in the
.circleci/config.yml file you copied above (It’s on line 68).
6. Select the context you just created and add the 3 following environment variables.
AWS_ACCESS_KEY_ID: This the key for your User in AWS.
AWS_SECRET_ACCESS_KEY: This the secret for your User in AWS.
AWS_DEFAULT_REGION: This is the name of the default region you want your app to deploy to, I use
If you have all of that correctly entered you should be able to commit all of your changes to your project in Github. If you merge or commit this directly to the master branch of your project it will trigger a CircleCI pipeline to build your React project and then deploy it. Once its all done you can grab the link from the deployment script to the new CloudFront CDN.
That’s it 🎉, using the steps above you should be able to deploy any React App project to AWS and share it with the 🌎. This really is only the tip of the iceberg, you can do a lot more with CDK, everything from different deployments by environment to custom domains with Route53.
If you would like to see more articles like this reach out or follow me on Medium.
Who Is Xerris?
We build cloud-native solutions for companies undertaking digital transformation. As an AWS Advanced Partner, we work with our clients to craft innovative cloud-focused solutions to complex business problems.
If you have questions or comments about this article I’d love to hear from you.