Table of contents
In this blog post, we will create an awesome React TypeScript App hosted in an S3 static website bucket. For that, we will use AWS CDK and Projen.
But first, I will explain what AWS CDK and Projen are and why I strongly recommend using Projen for AWS CDK.
Then we dive into creating the React App, which will be afterward deployed in an S3 bucket with AWS CDK.
AWS CDK
AWS CDK (GitHub) stands for Cloud Development Kit and is an open-source framework for creating and managing AWS resources. The infrastructure is described as code using languages familiar to the developer, such as TypeScript or Python. In doing so, CDK synthesizes the code into AWS Cloudformation Templates and can optionally deploy them right away.
AWS CDK has been experiencing a steady increase in enthusiastic developers since 2019 and already has a strong and helpful community that is very active on Slack.
There is much more to say about AWS CDK, and I recommend you explore it.
Projen
Projen allows sophisticated management of project configuration files through code. An entire repository can be configured with just a few lines of typed JavaScript code.
Here is an example:
const { AwsCdkTypeScriptApp } = require('projen');
const project = new AwsCdkTypeScriptApp({
authorAddress: 'damadden88@googlemail.com',
authorName: 'martin.mueller',
cdkVersion: '1.99.0',
cdkVersionPinning: true,
defaultReleaseBranch: 'main',
name: 'cdk-s3-website',
});
project.synth();These few lines create all the GitHub project files your heart desires.
Among them the package.json, .gitignore, tsconfig.json and many, many more.
Projen emerged from the AWS CDK community and contains helpful tools for creating AWS CDK Apps.
Why use Projen instead of CDK directly?
Projen is a lightweight wrapper around CDK, so you are using CDK under the hood. Furthermore, it helps you with managing dependencies like those from AWS CDK. That’s a huge help as managing those dependencies in a package.json yourself is time-consuming and unpleasant. You will understand what I mean when we start with coding.
Projen is widely used in the CDK Community, and I strongly recommend trying it.
Here is an awesome-projen list from existing Projen projects.
I love Projen and use it for my private projects and client work. It lets me iterate and try out AWS CDK code very fast, and after using Projen for many months, it still feels like cheating <3. As an AWS cloud developer, I want to run stuff quickly and not set up other stuff like the repository.
It helps me to understand better and faster response from other creators if they are using Projen for their projects. So it becomes a kind of standard.
If you want to know more about Projen, look at my other Projen posts.
Coding Preparations
Before we start coding, we need to install the CDK. Find the concrete instructions here, but it is easy just as:
npm i -g aws-cdkFor Projen, I recommend setting up an alias as described here, as you will run the Projen command quite a lot. Simply write in your shell profile:
alias pj='npx projen'Cool, now you just need to run pj if you want to update the repository.
Let’s do it
Create and checkout a new repository in GitHub or any other git provider. I will take Github. Navigate into the project and open it with VS Code. I usually do:
cd cdk-s3-website
code .Init the CDK Project
First, let’s check out which project types it offers us:
pj new(or npx projen new if you didn’t do the alias)
It should show you a list of supported project types like those:
projen new awscdk-app-ts AWS CDK app in TypeScript.
projen new awscdk-construct AWS CDK construct library project.
projen new cdk8s-app-ts CDK8s app in TypeScript.
projen new cdk8s-construct CDK8s construct library project.
projen new java Java project.
projen new jsii Multi-language jsii library project.
projen new nextjs Next.js project without TypeScript.
projen new nextjs-ts Next.js project with TypeScript.
projen new node Node.js project.
projen new project Base project.
projen new python Python project.
projen new react React project without TypeScript.
projen new react-ts React project with TypeScript.
projen new typescript TypeScript project.
projen new typescript-app TypeScript app.
Cool or? I think it’s pretty cool to use Projen for those kinds of projects as it does all the setup for me, and I don’t need to figure out each specific way of installing them natively.
Anyway, we want to create an AWS CDK app, so let’s choose the first project type:
pj new awscdk-app-tsThat takes a bit, but oh boy, look at all those files it added for us like .gitignore, package.json or the tsconfig.json. They all originated from defaults and what is defined in the .projenrc.js file.
Yep, the .projenrc.js file will become very important as it defines the setup of your project. Take your time and explore all those created files a bit.
I love this approach because those properties in the .projenrc.js file are typed. So with an IDEA like VS Code, you just can hover over them or jump to the definition and you the documentation about the use of the property.
Let’s tweak the .projenrc.js and see what happens.
I have overridden the project properties and deleted the commented-out ones:
const project = new AwsCdkTypeScriptApp({
authorAddress: 'damadden88@googlemail.com',
authorName: 'martin.mueller',
cdkVersion: '1.99.0',
cdkVersionPinning: true,
defaultReleaseBranch: 'main',
name: 'cdk-s3-website',
});You see, I did choose a newer CDK version. At the time of the writing 1.99 was the highest CDK version. If there should be a newer one, take that!
Save the change and run:
pjIt will synth your requested changes from the .projenrc.js file like upgrading the CDK version in the package.json file. After that, it conveniently installs those packages.
In a later section, we will bring in other CDK dependencies like creating an S3 bucket with enabled website hosting. Those will be managed with Projen as well. But before, let’s create the React TypeScript App.
React TS App
So for setting up the React TypeScript App, we can use Projen as well. We are starting with bringing in the web library and defining the React TypeScript App as a child project from our CDK App:
const { AwsCdkTypeScriptApp, web } = require('projen');
const project = new AwsCdkTypeScriptApp({
authorAddress: 'damadden88@googlemail.com',
...
});
project.synth();
const frontendProject = new web.ReactTypeScriptProject({
defaultReleaseBranch: 'main',
outdir: 'frontend',
parent: project,
name: 'cdk-s3-website',
});The React App project will be generated in the subfolder called frontend.
For convenience reasons, let’s implement a Projen script for locally running the react app:
frontendProject.addTask('dev', {
description: 'Runs the application locally',
exec: 'react-scripts start',
});In the end, we need to tell Projen to synth the frontend project as well:
frontendProject.synth();The whole .projenrc.js file should look something like this:
const { AwsCdkTypeScriptApp, web } = require('projen');
const project = new AwsCdkTypeScriptApp({
authorAddress: 'damadden88@googlemail.com',
authorName: 'martin.mueller',
cdkVersion: '1.99.0',
cdkVersionPinning: true,
defaultReleaseBranch: 'main',
name: 'cdk-s3-website',
});
project.synth();
const frontendProject = new web.ReactTypeScriptProject({
defaultReleaseBranch: 'main',
outdir: 'frontend',
parent: project,
name: 'cdk-s3-website',
});
frontendProject.addTask('dev', {
description: 'Runs the application locally',
exec: 'react-scripts start',
});
frontendProject.synth();Super let synth everything with pj.
Now we go to frontend and run:
yarn devIf you run into this error:
There might be a problem with the project dependency tree.
It is likely not a bug in Create React App, but something you need to fix locally.
The react-scripts package provided by Create React App requires a dependency:
"jest": "26.6.0"
Don't try to install it manually: your package manager does it automatically.
...That is because we have two projects configured, the AWS CDK app and the react app, and both using a different version of the jest library. Do the following to ignore the error as it will do us no harm.
Create a file frontend/.env with a one-liner:
SKIP_PREFLIGHT_CHECK=trueOk, that was a bit nasty, but blame React for it as it produced the error.
OK, let’s run:
yarn devIf not open automatically, you should see a local running React app on https://localhost:3000
Super!
One more thing as we are already in the front and folder.
Please run:
yarn buildas we will use the React build to deploy it to an S3 static website bucket in the next section :).
S3 Static Website
Now, let’s do some real AWS CDK magic as this blog post is about AWS CDK, and we did not use it so far (shame on me).
First, we need to add some more CDK S3 dependencies. That is done in the .projenrc.js file with:
const project = new AwsCdkTypeScriptApp({
...
cdkDependencies: [
'@aws-cdk/aws-s3-deployment',
'@aws-cdk/aws-s3',
],
});Run
pjAnd check the package.json.
We brought in those two dependencies now, and it picked up the defined CDK version cdkVersion: '1.99.0'.
Let’s go to the src/main.ts and define the S3 static website:
import * as s3 from '@aws-cdk/aws-s3';
import * as s3deploy from '@aws-cdk/aws-s3-deployment';
import { App, CfnOutput, Construct, RemovalPolicy, Stack, StackProps } from '@aws-cdk/core';
export class MyStack extends Stack {
constructor(scope: Construct, id: string, props: StackProps = {}) {
super(scope, id, props);
const siteBucket = new s3.Bucket(this, 'SiteBucket', {
websiteIndexDocument: 'index.html',
websiteErrorDocument: 'error.html',
publicReadAccess: true,
cors: [
{
allowedMethods: [s3.HttpMethods.GET, s3.HttpMethods.HEAD],
allowedOrigins: ['*'],
allowedHeaders: ['*'],
exposedHeaders: ['ETag', 'x-amz-meta-custom-header', 'Authorization', 'Content-Type', 'Accept'],
},
],
removalPolicy: RemovalPolicy.DESTROY,
autoDeleteObjects: true,
});
// Deploy site contents to S3 bucket
new s3deploy.BucketDeployment(this, 'BucketDeployment', {
sources: [s3deploy.Source.asset('./frontend/build')],
destinationBucket: siteBucket,
});
new CfnOutput(this, 'bucketWebsiteUrl', {
value: siteBucket.bucketWebsiteUrl,
});
}
}
// for development, use account/region from cdk cli
const devEnv = {
account: 123456789, // you aws account id
region: 'us-east-1',
};
const app = new App();
new MyStack(app, 'my-stack-dev', { env: devEnv });
// new MyStack(app, 'my-stack-prod', { env: prodEnv });
app.synth();We defined an S3 static website bucket and told CDK to upload the build files from React in ./frontend/build to it.
As you might notice, I used explicit defined deploy account information instead of those CDK_DEFAULT_ ones.
So instead of:
const devEnv = {
account: process.env.CDK_DEFAULT_ACCOUNT,
region: process.env.CDK_DEFAULT_REGION,
};I used:
const devEnv = {
account: '123456789', // you aws account id
region: 'us-east-1',
};This has a couple of advantages, like that you have your configuration as code, and you don’t need to hide it in env variables during builds. As well, CDK will make check that your configured AWS credentials like in ~/.aws/credentials are matching.
That prevents accidental deployment to the wrong account, which is helpful.
OK, you might think that you showing critical aws information by revealing the account id. I do challenge you, and that is not true. With only seeing the account id, you can not hack into the account. I am happy if you prove me otherwise.
Super!
Let’s deploy it.
Go to the root folder and do:
pj
yarn deployCDK will tell you which resources needs to be applied or updated to create the S3 bucket. Confirm it with y.
When the deployment is finished you will see the S3 URL:
✅ my-stack-dev
Outputs:
my-stack-dev.bucketWebsiteUrl = http://my-stack-dev-sitebucket397a1860-6hzh1ardmfg0.s3-website-us-east-1.amazonaws.com
Open the URL.
Now you see your React TS App hosted in an S3 bucket.
How cool is that?!
What’s next?
Awesome, we set up a React TypeScript App in an S3 Static Website bucket. From here on, we could start to make the React App good-looking and create some nice components and routes. And let’s bring in some more AWS Services for use in our backend. Like AWS Cognito for user provisioning and authentication.
With AWS Amplify, it is very easy to integrate Cognito’s user authentication with our App as it comes with a nice Login UI and Cognito backend integration.
The S3 Static Website doesn’t use a Cloud Delivery Network (CDN). A CDN keeps the latency when accessing your website low as it uses a network of servers worldwide to cache your site. Setting up a CDN is easily done in AWS CDK.
You could set up an AWS API Gateway to use as a REST Server for our App, or even cooler, let’s do a GraphQL Server with AWS Appsync as I did here and here.
We hope you’ve found this article useful! If so, please, help us to spread it to the world!
Stay tuned for the next blog post 🙂
