Build Release

cdk-simplewebsite-deploy

This is an AWS CDK v2 construct library for deploying a single-page website using CloudFront distributions, with S3, Route 53, and ACM. CreateCloudfrontSite uses a private S3 origin with CloudFront Origin Access Control (OAC).

Installation and Usage

CreateCloudfrontSite

Creates a website using a private S3 bucket, a CloudFront distribution, and DNS records in Route 53.

Typescript

yarn add cdk-simplewebsite-deploy

import * as cdk from 'aws-cdk-lib';
import { CreateCloudfrontSite } from 'cdk-simplewebsite-deploy';
import { Construct } from 'constructs';

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

    new CreateCloudfrontSite(this, 'test-website', {
      websiteFolder: './src/dist',
      indexDoc: 'index.html',
      hostedZone: 'example.com',
      subDomain: 'www.example.com',
    });
  }
}

Java

<dependency>
	<groupId>com.thonbecker.simplewebsitedeploy</groupId>
	<artifactId>cdk-simplewebsite-deploy</artifactId>
	<version>VERSION</version>
</dependency>

Replace VERSION with the version shown on the Maven Central badge.

package com.myorg;

import com.thonbecker.simplewebsitedeploy.CreateCloudfrontSite;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.constructs.Construct;

public class MyProjectStack extends Stack {
    public MyProjectStack(final Construct scope, final String id) {
        this(scope, id, null);
    }

    public MyProjectStack(final Construct scope, final String id, final StackProps props) {
        super(scope, id, props);

        CreateCloudfrontSite.Builder.create(this, "test-website")
                .websiteFolder("./src/build")
                .indexDoc("index.html")
                .hostedZone("example.com")
                .subDomain("www.example.com")
                .build();
    }
}

Python

pip install cdk-simplewebsite-deploy

from aws_cdk import Stack
from cdk_simplewebsite_deploy import CreateCloudfrontSite
from constructs import Construct


class MyProjectStack(Stack):

    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        CreateCloudfrontSite(self, 'test-website', website_folder='./src/build',
                             index_doc='index.html',
                             hosted_zone='example.com',
                             sub_domain='www.example.com')

Upgrading to 3.0.0

CreateBasicSite is removed. Use CreateCloudfrontSite.

CreateCloudfrontSite now creates the bucket, distribution, deployment, and DNS records on the construct instead of the parent stack. CloudFormation logical IDs change, so an upgrade replaces those resources. The website bucket is replaced: the previous bucket is deleted (RemovalPolicy.DESTROY with auto-delete) and a new bucket is created. Redeploy the site contents from websiteFolder after the replacement.

🚀 Enhanced Features

The CreateCloudfrontSite construct includes optional advanced features for security, performance, and monitoring.

Security Headers

Enable security headers including HSTS, X-Frame-Options, Content-Type-Options, and a referrer policy:

new CreateCloudfrontSite(this, 'secure-website', {
  websiteFolder: './src/dist',
  indexDoc: 'index.html',
  hostedZone: 'example.com',
  enableSecurityHeaders: true, // 🔒 Adds security headers
});

IPv6 Support

Enable IPv6 connectivity with AAAA records:

new CreateCloudfrontSite(this, 'ipv6-website', {
  websiteFolder: './src/dist',
  indexDoc: 'index.html',
  hostedZone: 'example.com',
  enableIpv6: true, // 🌐 Adds AAAA records for IPv6
});

Access Logging

Enable CloudFront access logging for analytics and monitoring:

new CreateCloudfrontSite(this, 'logged-website', {
  websiteFolder: './src/dist',
  indexDoc: 'index.html',
  hostedZone: 'example.com',
  enableLogging: true, // 📊 Enables access logging
  // logsBucket: myCustomBucket, // Optional: use existing bucket
});

WAF Integration

Integrate with AWS WAF for enhanced security:

new CreateCloudfrontSite(this, 'waf-protected-website', {
  websiteFolder: './src/dist',
  indexDoc: 'index.html',
  hostedZone: 'example.com',
  webAclId: 'arn:aws:wafv2:us-east-1:123456789012:global/webacl/my-web-acl/12345678-1234-1234-1234-123456789012', // 🛡️ WAF protection
});

Origin Access Levels

Grant additional OAC permissions to the website bucket. This can be useful when you need CloudFront to distinguish missing objects from access-denied responses.

import * as cloudfront from 'aws-cdk-lib/aws-cloudfront';

new CreateCloudfrontSite(this, 'website-with-list-access', {
  websiteFolder: './src/dist',
  indexDoc: 'index.html',
  hostedZone: 'example.com',
  originAccessLevels: [
    cloudfront.AccessLevel.READ,
    cloudfront.AccessLevel.LIST,
  ],
});

CloudFront Function Associations

Attach CloudFront Functions to the default behavior for lightweight viewer request or viewer response logic.

import * as cloudfront from 'aws-cdk-lib/aws-cloudfront';

const rewriteFunction = new cloudfront.Function(this, 'RewriteFunction', {
  code: cloudfront.FunctionCode.fromInline(
    'function handler(event) { return event.request; }',
  ),
});

new CreateCloudfrontSite(this, 'website-with-function', {
  websiteFolder: './src/dist',
  indexDoc: 'index.html',
  hostedZone: 'example.com',
  functionAssociations: [
    {
      eventType: cloudfront.FunctionEventType.VIEWER_REQUEST,
      function: rewriteFunction,
    },
  ],
});

Custom Cache Behaviors

Add custom cache behaviors for different content types:

import * as cloudfront from 'aws-cdk-lib/aws-cloudfront';

new CreateCloudfrontSite(this, 'optimized-website', {
  websiteFolder: './src/dist',
  indexDoc: 'index.html',
  hostedZone: 'example.com',
  additionalBehaviors: {
    '/api/*': {
      origin: myApiOrigin,
      allowedMethods: cloudfront.AllowedMethods.ALLOW_ALL,
      cachePolicy: cloudfront.CachePolicy.CACHING_DISABLED,
    },
    '/static/*': {
      cachePolicy: cloudfront.CachePolicy.CACHING_OPTIMIZED_FOR_UNCOMPRESSED_OBJECTS,
    },
  }, // ⚡ Custom caching strategies
});

Custom Error Responses

Define custom error handling:

new CreateCloudfrontSite(this, 'custom-errors-website', {
  websiteFolder: './src/dist',
  indexDoc: 'index.html',
  hostedZone: 'example.com',
  customErrorResponses: [
    {
      httpStatus: 404,
      responseHttpStatus: 200,
      responsePagePath: '/index.html', // SPA routing
    },
    {
      httpStatus: 403,
      responseHttpStatus: 200,
      responsePagePath: '/index.html',
    },
  ], // 🎯 Custom error handling
});

Complete Example with All Features

import * as cdk from 'aws-cdk-lib';
import * as cloudfront from 'aws-cdk-lib/aws-cloudfront';
import { CreateCloudfrontSite } from 'cdk-simplewebsite-deploy';
import { Construct } from 'constructs';

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

    const rewriteFunction = new cloudfront.Function(this, 'RewriteFunction', {
      code: cloudfront.FunctionCode.fromInline(
        'function handler(event) { return event.request; }',
      ),
    });

    new CreateCloudfrontSite(this, 'advanced-website', {
      websiteFolder: './dist',
      indexDoc: 'index.html',
      errorDoc: 'error.html',
      hostedZone: 'example.com',
      subDomain: 'www.example.com',

      // Performance & Security
      priceClass: cloudfront.PriceClass.PRICE_CLASS_ALL,
      enableSecurityHeaders: true,
      enableIpv6: true,
      originAccessLevels: [
        cloudfront.AccessLevel.READ,
        cloudfront.AccessLevel.LIST,
      ],

      // Monitoring & Protection
      enableLogging: true,
      webAclId: 'arn:aws:wafv2:us-east-1:123456789012:global/webacl/my-web-acl/12345678-1234-1234-1234-123456789012',

      // Custom Behaviors
      additionalBehaviors: {
        '/api/*': {
          allowedMethods: cloudfront.AllowedMethods.ALLOW_ALL,
          cachePolicy: cloudfront.CachePolicy.CACHING_DISABLED,
        },
      },

      // Edge Logic
      functionAssociations: [
        {
          eventType: cloudfront.FunctionEventType.VIEWER_REQUEST,
          function: rewriteFunction,
        },
      ],

      // SPA Error Handling
      customErrorResponses: [
        {
          httpStatus: 404,
          responseHttpStatus: 200,
          responsePagePath: '/index.html',
        },
      ],
    });
  }
}

🎯 Key Benefits

🔒 Enhanced Security

Security Headers: Automatic HSTS, X-Frame-Options, Content-Type-Options, and a referrer policy
WAF Integration: Support for AWS WAF Web ACLs for advanced threat protection
Origin Access Control: Modern S3 bucket protection (replaces deprecated OAI)
Configurable OAC Permissions: Optional origin access levels for the website bucket

⚡ Optimized Performance

Smart Caching: Optimized cache policies for better performance
HTTP/2 & HTTP/3: Latest protocol support for faster loading
Global Edge Locations: Configurable price classes for worldwide distribution
IPv6 Support: Dual-stack networking for better connectivity
CloudFront Functions: Optional viewer request and response function associations

📊 Comprehensive Monitoring

Access Logging: CloudFront access logs for analytics
Custom Error Handling: Flexible error response configuration
SPA Support: Built-in single-page application routing support

🚀 Developer Experience

v3 migration: See Upgrading to 3.0.0 before upgrading an existing stack
Type Safe: Full TypeScript support with comprehensive interfaces
CDK v2 Ready: Built for the latest AWS CDK version
Multi-Language: Support for TypeScript, Python, and Java

License

Distributed under the Apache-2.0 license.

Metadata

Release files for cdk-simplewebsite-deploy 3.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cdk-simplewebsite-deploy 3.0.1
File	Size	Uploaded
cdk_simplewebsite_deploy-3.0.1.tar.gz	62.4 kB	Oct 17, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cdk-simplewebsite-deploy 3.0.1
File	Interpreter	ABI	Platform	Reset
cdk_simplewebsite_deploy-3.0.1-py3-none-any.whl 60.5 kB Oct 17, 2026	Python 3	none	any	Details

Total release size: 122.9 kB

Release files / cdk_simplewebsite_deploy-3.0.1.tar.gz

Download URL	cdk_simplewebsite_deploy-3.0.1.tar.gz
Size	62.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`c58c4045198736ff40e5a3271943c4658ddc9eaf1bd9c5da0a1373611576bfff`
BLAKE2b-256 checksum How to use checksums	`d30151452b925935baf3d86a74c25d5e3adaff1228a1e66ec01706cd2e3e4893`
Upload date	Oct 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.14.8`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/SnapPetal/cdk-simplewebsite-deploy
Publishing commit: github.com/SnapPetal/cdk-simplewebsite-deploy/tree/5cef5b9ec13c8d27f0bbe56dcfe0c8feb61f384b

Workflow

Publishing configuration: github.com/SnapPetal/cdk-simplewebsite-deploy/blob/5cef5b9ec13c8d27f0bbe56dcfe0c8feb61f384b/.github/workflows/release.yml
Publishing logs: github.com/SnapPetal/cdk-simplewebsite-deploy/actions/runs/39061707995/attempts/1

Artifact

Subject: cdk_simplewebsite_deploy-3.0.1.tar.gz
SHA-256 checksum: c58c4045198736ff40e5a3271943c4658ddc9eaf1bd9c5da0a1373611576bfff Verifying attestations

Release files / cdk_simplewebsite_deploy-3.0.1-py3-none-any.whl

Download URL	cdk_simplewebsite_deploy-3.0.1-py3-none-any.whl
Size	60.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`8ed4abfb806fa66126edb1cf90694196e69ca86eb355f8c058e8380572b4cb78`
BLAKE2b-256 checksum How to use checksums	`fa6853192f39d17689c7cd8cea58c3b9dbf87075056d2c4630417a614eb441cd`
Upload date	Oct 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.14.8`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/SnapPetal/cdk-simplewebsite-deploy
Publishing commit: github.com/SnapPetal/cdk-simplewebsite-deploy/tree/5cef5b9ec13c8d27f0bbe56dcfe0c8feb61f384b

Workflow

Publishing configuration: github.com/SnapPetal/cdk-simplewebsite-deploy/blob/5cef5b9ec13c8d27f0bbe56dcfe0c8feb61f384b/.github/workflows/release.yml
Publishing logs: github.com/SnapPetal/cdk-simplewebsite-deploy/actions/runs/39061707995/attempts/1

Artifact

Subject: cdk_simplewebsite_deploy-3.0.1-py3-none-any.whl
SHA-256 checksum: 8ed4abfb806fa66126edb1cf90694196e69ca86eb355f8c058e8380572b4cb78 Verifying attestations