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.
1 maintainer
Metadata
1 maintainer
Release files for cdk-simplewebsite-deploy 3.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cdk_simplewebsite_deploy-3.0.0.tar.gz | 62.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cdk_simplewebsite_deploy-3.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 122.9 kB
Release files / cdk_simplewebsite_deploy-3.0.0.tar.gz
| Download URL | cdk_simplewebsite_deploy-3.0.0.tar.gz |
|---|---|
| Size | 62.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d519648ef6521ef11356ceed5d2ef9b331c610981752815b1d7ba3e96004f275
|
|
BLAKE2b-256 checksum How to use checksums |
0d2bae95cdc2ef5a2f13e22361f59b460c31b9267490019fc96fa55905d3f243
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency logRelease files / cdk_simplewebsite_deploy-3.0.0-py3-none-any.whl
| Download URL | cdk_simplewebsite_deploy-3.0.0-py3-none-any.whl |
|---|---|
| Size | 60.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6fb312cc9a503d97d7b0b53ea95f23597519ac003e628a8c6b8ad84272a654ed
|
|
BLAKE2b-256 checksum How to use checksums |
a7d0a23e6293ce7f609b73467525b9bdad55e559287497dda3392acea2106930
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency log
