Hosting a Static Website on AWS with CDK

When it comes to hosting a static website—be it a single-page app or a feature-rich client-side framework—AWS provides an extremely reliable and cost-effective solution using S3 and CloudFront. With the AWS Cloud Development Kit (CDK), we can define all necessary resources in TypeScript (or other supported languages) and deploy them as Infrastructure as Code (IaC), making the process repeatable and easily maintainable.

This post will walk you through:

1. Setting up your local environment
2. Initializing a new CDK project
3. Creating a custom CDK construct for hosting a static site (S3 + CloudFront + Route53)
4. Deploying your website step-by-step (build → synth → deploy)

Prerequisites & Setup

1. AWS Account

You’ll need an AWS account to deploy your website. If you don’t have one yet, head over to aws.amazon.com to sign up. It’s free to create an account, and you get 12 months of free tier access to many services.

2. Domain and Hosted Zone

For a custom domain such as my private timhartmann.de, you need a Hosted Zone in Route53. This is a requirement for setting up the DNS records and getting a valid SSL certificate via AWS Certificate Manager.

• If you’ve purchased a domain directly through AWS, the system automatically sets up a Hosted Zone for you.
• If you own a domain elsewhere, you’ll need to manually create and configure a Hosted Zone in Route53, then update your domain registrar’s name servers to use Route53.

3. AWS CLI and CDK Installation

If you haven’t installed the AWS Command Line Interface (CLI) yet, you can do so by following the AWS CLI installation docs. Once installed, run:

aws configure

to set your AWS credentials and default region.

Then, install the AWS CDK:

npm install -g aws-cdk

4. Initialize a CDK App

Create a new directory for your project, then initialize a new TypeScript-based CDK app:

mkdir my-static-website
cd my-static-website
cdk init app --language typescript

This sets up a basic CDK project structure, including a bin and lib folder, a cdk.json config file, and more.

5. Standard Project Setup

Inside the newly created directory, install any Node dependencies we may need and then build it a first time:

npm install
npm run build

---

The Static Website Construct

Below is a custom construct that bundles together:

• An S3 bucket (for website files)
• A CloudFront distribution (to deliver files worldwide over AWS’s edge network)
• Route53 DNS records (so that your custom domain points to the site)
• SSL certificate for HTTPS via AWS Certificate Manager

import { Construct } from 'constructs';
import { ARecord, HostedZone, RecordTarget } from 'aws-cdk-lib/aws-route53';
import { CloudFrontTarget } from 'aws-cdk-lib/aws-route53-targets';
import { Bucket, BucketEncryption, BlockPublicAccess } from 'aws-cdk-lib/aws-s3';
import { AccessLevel, Distribution } from 'aws-cdk-lib/aws-cloudfront';
import { BucketDeployment, Source } from 'aws-cdk-lib/aws-s3-deployment';
import { DnsValidatedCertificate } from 'aws-cdk-lib/aws-certificatemanager';
import { S3BucketOrigin } from 'aws-cdk-lib/aws-cloudfront-origins';
import { Duration, RemovalPolicy } from 'aws-cdk-lib';

export interface StaticWebsiteProps {
   hostedZoneId: string;
   domainName: string;
   aliasDomainNames?: string[];
   assetPath: string;
}

/**
 * Construct to create a static website hosted on S3 with CloudFront distribution and Route 53 DNS record
 *
 * if apiGwUrl is provided, it will be injected as json file to the frontend package
 */
export class StaticWebsiteConstruct extends Construct {
   constructor( scope: Construct, id: string, props: StaticWebsiteProps ) {
      super( scope, id );

      // Set up the hosted zone and DNS
      const hostedZone = HostedZone.fromHostedZoneAttributes( this, 'HostedZone', {
         hostedZoneId: props.hostedZoneId,
         zoneName: props.domainName,
      } );

      // Create a certificate for CloudFront (must be in us-east-1)
      // This Construct will be marked as deprecated, but there is no alternative yet
      // It will still work for the time being until CDKv3 is released
      const certificate = new DnsValidatedCertificate( this, 'WebsiteCertificate', {
         domainName: props.domainName,
         hostedZone: hostedZone,
         region: 'us-east-1',
         subjectAlternativeNames: props.aliasDomainNames,
      } );

      // Create a secure S3 bucket for website hosting
      const websiteBucket = new Bucket( this, 'WebsiteBucket', {
         encryption: BucketEncryption.S3_MANAGED,
         versioned: true,
         blockPublicAccess: BlockPublicAccess.BLOCK_ALL,
         removalPolicy: RemovalPolicy.DESTROY,
      } );

      // Create a CloudFront distribution using the S3 bucket as origin with OAI
      const distribution = new Distribution( this, 'Distribution', {
         defaultBehavior: {
            origin: S3BucketOrigin.withOriginAccessControl( websiteBucket, {
               originAccessLevels: [ AccessLevel.READ, AccessLevel.LIST ],
            } ),
            compress: true,
         },
         domainNames: [ props.domainName, ...( props.aliasDomainNames ?? [] ) ],
         certificate: certificate,
         defaultRootObject: 'index.html',
         errorResponses: [
            {
               httpStatus: 404,
               responseHttpStatus: 200,
               responsePagePath: '/index.html',
               ttl: Duration.seconds( 0 ),
            },
         ],
      } );

      // Create a DNS record pointing to the CloudFront distribution
      new ARecord( this, 'AliasRecord', {
         zone: hostedZone,
         target: RecordTarget.fromAlias( new CloudFrontTarget( distribution ) ),
      } );

      for ( const alias of props.aliasDomainNames ?? [] ) {
         new ARecord( this, `AliasRecord-${ alias }`, {
            zone: hostedZone,
            target: RecordTarget.fromAlias( new CloudFrontTarget( distribution ) ),
            recordName: alias,
         } );
      }

      // Prepare website assets (frontend package and optional API endpoint)
      const websiteAssets = [
         Source.asset( props.assetPath )
      ];

      // Deploy the assets to the S3 bucket and invalidate CloudFront cache if needed
      new BucketDeployment( this, 'WebsiteDeployment', {
         sources: [ ...websiteAssets ],
         destinationBucket: websiteBucket,
         destinationKeyPrefix: '/',
         distributionPaths: [ '/*' ],
         distribution: distribution,
      } );
   }
}

Usage in a CDK Stack

Here’s an example of how to use this construct inside a CDK Stack. You might place this in lib/MyWebsiteStack.ts:

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { StaticWebsiteConstruct } from './StaticWebsite-Construct';

export class TimHartmannDeStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    new StaticWebsiteConstruct(this, 'TimHartmannDeStaticPageStack', {
      assetPath: './site-contents',
      domainName: 'timhartmann.de',
      hostedZoneId: 'Z1XXXXXXXXXXXX', 
      aliasDomainNames: ['www.timhartmann.de'],
    });
  }
}

Make sure to substitute the hostedZoneId with your actual Hosted Zone ID. If you’re copying from Route53, you’ll see it labeled as “Hosted Zone ID.”

Deploying the Stack

When we initialized the CDK project, it created a bin folder with a TypeScript file, named like your project, that defines the infrastructure to deploy.
This file is the entry point for your CDK app and is where you define the stacks to deploy. This example only has a single Stack.

#!/usr/bin/env node
import 'source-map-support/register';
import * as cdk from 'aws-cdk-lib';
import { TimHartmannDeStack } from '../lib/TimHartmannDeStack';

const app = new cdk.App();
new TimHartmannDeStack(app, 'TimHartmannDeStaticPageStack', {
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT,
    region: process.env.CDK_DEFAULT_REGION, // or specify your region here, e.g., 'us-east-1'
  },
});

Assuming you already ran cdk init and have your project structure in place, you can follow these steps anytime you change either the infrastructure code (e.g., the CloudFront distribution) or your actual website files:

1. Update your website files in the site-contents folder.
2. Build (if you have a build step):

   npm run build

   This compiles your TypeScript code.
3. Synthesize your CloudFormation template:

   cdk synth

   This produces the final CloudFormation stack.
4. Deploy to AWS:

   cdk deploy

CDK will zip up and upload the contents from site-contents into the S3 bucket and create or update any AWS resources defined in our construct. After the deployment finishes, you’ll have a fully functioning static website available over HTTPS at your custom domain!

---

Why CloudFront?

Using CloudFront in front of your S3 bucket offers several benefits:

• Global Edge Locations: Your content is served from edge caches around the world, resulting in faster load times.
• Security & SSL: CloudFront handles SSL certificates from AWS Certificate Manager, ensuring your site is always served over HTTPS.
• Cost-Effectiveness: Storing static assets in S3 is cheap, and you pay only for what you use in CloudFront.
• Scalability & Reliability: Automatically handles traffic spikes without you having to manage any servers or capacity.

---

Conclusion

Deploying a static website with AWS CDK is straightforward and powerful. By treating your infrastructure as code, you get repeatability, version control, and the ability to continuously evolve your stack. With CloudFront’s caching and Route53’s DNS integration, your website is served quickly and reliably from a globally distributed network.

Try it out for personal projects or even for enterprise-grade frontends that don’t require complex server-side logic. If you have any questions or run into any issues, feel free to drop me a message on GitHub or LinkedIn!