Skip to main content

License Build Release npm PyPI Maven Central

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.3

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.3
File Size Uploaded Provenance Actions
cdk_simplewebsite_deploy-3.0.3.tar.gz 62.5 kB With provenance Details for cdk_simplewebsite_deploy-3.0.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cdk-simplewebsite-deploy 3.0.3
File Interpreter ABI Platform Actions
cdk_simplewebsite_deploy-3.0.3-py3-none-any.whl Python 3 none any Details for cdk_simplewebsite_deploy-3.0.3-py3-none-any.whl

Total release size: 123.0 kB

Release files / cdk_simplewebsite_deploy-3.0.3.tar.gz

Download URL cdk_simplewebsite_deploy-3.0.3.tar.gz
Size 62.5 kB
Tags Source
SHA-256 checksum
How to use checksums
ea3f77514d40d7e6777109f3f32bd39d4c85327d75d1e4008a364922fc002be7
BLAKE2b-256 checksum
How to use checksums
37d198d2342ae39da9b671f1564da5dd063c7c20e6349af6067ed9f33e6fa5c5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.15.1

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 Nov 2, 2026.

Transparency log

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

Download URL cdk_simplewebsite_deploy-3.0.3-py3-none-any.whl
Size 60.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dd87f88c1c76d15703879c987d73621695b08ffd578ddd75d4aa42d6701e0cc2
BLAKE2b-256 checksum
How to use checksums
f7190d4c8b9014c6a317482870705c98a5944137689df5409dcde0875b3dde28
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.15.1

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 Nov 2, 2026.

Transparency log

Security for cdk-simplewebsite-deploy 3.0.3

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cdk_simplewebsite_deploy-3.0.3.tar.gz

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 Nov 2, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.0.3 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page