🎉 I'm releasing 12 products in 12 months! If you love product, checkout my new blog workingoutloud.dev

Back to home

Deploying Static Websites To AWS S3 + CloudFront + Route53 Using The TypeScript AWS CDK

In today's post, we're going to walk through a step-by-step deployment of a static website to an S3 bucket that has CloudFront setup as the global CDN.

The post is written using the AWS TypeScript CDK.

This example is used as a deployment for a static export of a NextJS 10 website. Find the blog post on how to do that here. That being said, this post is aimed at pushing any HTML to S3 to use a static website. I simply use the NextJS content to demo the final product and changes in steps required to get it done.

Getting Started

We need to set up a new npm project and install the prerequisites. We'll also create a stacks directory to house our S3 stack and update it to take some custom.

# Create a root directory mkdir infra cd infra # init npm project with default values npm init -y # Install required libraries npm i @aws-cdk/aws-cloudfront @aws-cdk/aws-route53 @aws-cdk/aws-s3 @aws-cdk/aws-s3-deployment @aws-cdk/aws-certificatemanager @aws-cdk/core @aws-cdk/aws-route53-targets # Dev installation reqs npm i --save-dev typescript @types/node # Make a stacks directory to house stacks mkdir -p stacks stacks/s3-static-site-with-cloudfront # Create main infra entry file touch index.ts # Create stack file touch stacks/s3-static-site-with-cloudfront/index.ts touch tsconfig.json cdk.json cdk.context.json

Updating cdk.json

Add the following the the cdk.json file:

{ "app": "node index" }

Setting up context

Add the following the the cdk.json file:

{ "account": "<your-account-number>", "region": "us-east-1" }

A guide to getting your account ID can be found on the AWS website, but if you are familiar with the AWS CLI then you can use the following.

aws sts get-caller-identity

Ensure that you set the account to be a string with the number returned.

For more information on context, see the AWS docs.

Updating the TypeScript Configuration File

In tsconfig.json, add the following:

{ "compilerOptions": { "target": "ES2018", "module": "commonjs", "lib": ["es2016", "es2017.object", "es2017.string"], "strict": true, "noImplicitAny": true, "strictNullChecks": true, "noImplicitThis": true, "alwaysStrict": true, "noUnusedLocals": true, "noUnusedParameters": true, "noImplicitReturns": true, "noFallthroughCasesInSwitch": false, "inlineSourceMap": true, "inlineSources": true, "experimentalDecorators": true, "strictPropertyInitialization": false, // only required if using Node fns (which I do later on) "types": ["node"] } }

This is a basic TypeScript configuration for the CDK to compile the TypeScript configuration to JavaScript.

Handling the static site stack

Open up stacks/s3-static-site-with-cloudfront/index.ts and add the following:

import cloudfront = require("@aws-cdk/aws-cloudfront"); import route53 = require("@aws-cdk/aws-route53"); import s3 = require("@aws-cdk/aws-s3"); import s3deploy = require("@aws-cdk/aws-s3-deployment"); import acm = require("@aws-cdk/aws-certificatemanager"); import cdk = require("@aws-cdk/core"); import targets = require("@aws-cdk/aws-route53-targets/lib"); import { Stack, App, StackProps } from "@aws-cdk/core"; import path = require("path"); export interface StaticSiteProps extends StackProps { domainName: string; siteSubDomain: string; } /** * Static site infrastructure, which deploys site content to an S3 bucket. * * The site redirects from HTTP to HTTPS, using a CloudFront distribution, * Route53 alias record, and ACM certificate. */ export class StaticSiteStack extends Stack { constructor(parent: App, name: string, props: StaticSiteProps) { super(parent, name, props); const zone = route53.HostedZone.fromLookup(this, "Zone", { domainName: props.domainName, }); const siteDomain = props.siteSubDomain + "." + props.domainName; new cdk.CfnOutput(this, "Site", { value: "https://" + siteDomain }); // Content bucket const siteBucket = new s3.Bucket(this, "SiteBucket", { bucketName: siteDomain, websiteIndexDocument: "index.html", websiteErrorDocument: "error.html", publicReadAccess: true, // The default removal policy is RETAIN, which means that cdk destroy will not attempt to delete // the new bucket, and it will remain in your account until manually deleted. By setting the policy to // DESTROY, cdk destroy will attempt to delete the bucket, but will error if the bucket is not empty. removalPolicy: cdk.RemovalPolicy.DESTROY, // NOT recommended for production code }); new cdk.CfnOutput(this, "Bucket", { value: siteBucket.bucketName }); // TLS certificate const certificateArn = new acm.DnsValidatedCertificate( this, "SiteCertificate", { domainName: siteDomain, hostedZone: zone, region: "us-east-1", // Cloudfront only checks this region for certificates. } ).certificateArn; new cdk.CfnOutput(this, "Certificate", { value: certificateArn }); // CloudFront distribution that provides HTTPS const distribution = new cloudfront.CloudFrontWebDistribution( this, "SiteDistribution", { aliasConfiguration: { acmCertRef: certificateArn, names: [siteDomain], sslMethod: cloudfront.SSLMethod.SNI, securityPolicy: cloudfront.SecurityPolicyProtocol.TLS_V1_1_2016, }, originConfigs: [ { customOriginSource: { domainName: siteBucket.bucketWebsiteDomainName, originProtocolPolicy: cloudfront.OriginProtocolPolicy.HTTP_ONLY, }, behaviors: [{ isDefaultBehavior: true }], }, ], } ); new cdk.CfnOutput(this, "DistributionId", { value: distribution.distributionId, }); // Route53 alias record for the CloudFront distribution new route53.ARecord(this, "SiteAliasRecord", { recordName: siteDomain, target: route53.RecordTarget.fromAlias( new targets.CloudFrontTarget(distribution) ), zone, }); // Deploy site contents to S3 bucket new s3deploy.BucketDeployment(this, "DeployWithInvalidation", { sources: [s3deploy.Source.asset("./site-contents")], destinationBucket: siteBucket, distribution, distributionPaths: ["/*"], }); } }

The above was adjusted from the AWS CDK Example to convert things to run as a stack as opposed to a construct.

To explain what is happening here:

  1. We have an interface StaticSiteProps which allows up to pass an object of arguments domainName and siteSubDomain which will allow us to demo an example. If I were to push domainName as dennisokeeffe.com and siteSubDomain as s3-cdk-deployment-example then you would expect the website to be available at s3-cdk-deployment-example.dennisokeeffe.com. This is assigned as the variable siteDomain within the class.
  2. An ARN certificate certificateArn is create to enable us to use https.
  3. A new CloudFront distribution is created and assigned to distribution. The certificateArn is used to configure the ACM Certificate Reference, and the siteDomain is used here as the name.
  4. A new Alias Record is created for our siteDomain value and has the target set to be the new CloudFront Distribution.
  5. Finally, we deploy assets from a source ./site-contents which expects you to have your code source in that folder relative to the stacks folder. In our case, this will not be what we want and that value will be changed. The deployment also invalidates the objects on the CDN. This may or may not be what you want depending on how your cache-busting mechanisms work. If you have hashed assets and no-cache or max-age=0 for your index.html file (which you should) then you can switch this off. Invalidation costs money.

In my case, I am going to adjust the code above to import path and change the s3deploy.Source.asset('./site-contents') value to become s3deploy.Source.asset(path.resolve(__dirname, '../../../next-10-static-export/out')) (which points to my output directory with the static HTML build assets). This relates to my corresponding blog post on exporting NextJS 10 static websites directly. Note that you will need to add import path = require('path') to the top and install @types/node.

Using the StaticSite Stack

Back at the root directory in index.ts, let's import the stack and put it to use.

import cdk = require("@aws-cdk/core"); import { StaticSiteStack } from "./stacks/s3-static-site-with-cloudfront"; const app = new cdk.App(); const staticSite = new StaticSiteStack(app, "NextJS10StaticSite", { env: { account: app.node.tryGetContext("account"), region: app.node.tryGetContext("region"), }, domainName: "dennisokeeffe.com", siteSubDomain: "nextjs-10-static-example", }); // example of adding a tag - please refer to AWS best practices for ideal usage cdk.Tags.of(staticSite).add("Project", "NextJS 10 Example Deployment"); app.synth();

In the above, we simply import the stack, create a new app with the cdk API, then pass that app to the new instance of the StaticSite.

If you recall, the constructor for the StaticSite reads constructor(parent: Construct, name: string, props: StaticSiteProps) and so it expects three arguments.

  1. The CDK app.
  2. The "name" or identifier for the stack.
  3. Props that adhere to our StaticSiteProps, so in our case an object that passes the domainName and siteSubDomain.

Updating package.json

Before deployment, let's adjust package.json for some scripts to help with the deployment.

{ // rest omitted for brevity "scripts": { "build": "tsc", "watch": "tsc -w", "cdk": "cdk", "deploy": "cdk deploy", "destroy": "cdk destroy", "synth": "cdk synth" } }

Now we are ready to roll.

Deploying our site

Note: you must have your static folder from another project ready for this to work. Please refer to my post on a static site export of NextJS 10 if you would like to follow what I am doing here.

To deploy our site, we need to transpile the TypeScript to JavaScript, then run the CDK synth and deploy commands.

Note: you'll need to make sure that your AWS credentials are configured for this to work. I personally use aws-vault.

# Transpile TypeScript npm run build # Synth npm run synth # Deploy npm run deploy

You'll need to accept the new resources template generated before the deployment will commence.

In my particular case, I used the NextJS static site example given from my post on Exporting Static NextJS 10 Websites

You can see the final, live deploy at https://nextjs-10-static-example.dennisokeeffe.com.

NextJS 10 Static Export on S3

NextJS 10 Static Export on S3


Image credit: Ignat Kushanrev

Personal image

Dennis O'Keeffe

  • Melbourne, Australia

Hi, I am a professional Software Engineer. Formerly of Culture Amp, UsabilityHub, Present Company and NightGuru.
I am currently working on Visibuild.


Get fresh posts + news direct to your inbox.

No spam. We only send you relevant content.

Deploying Static Websites To AWS S3 + CloudFront + Route53 Using The TypeScript AWS CDK


Share this post