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

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

Built distribution (wheel)

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

Total release size: 123.1 kB

Release files / cdk_simplewebsite_deploy-3.0.7.tar.gz

Download URL cdk_simplewebsite_deploy-3.0.7.tar.gz
Size 62.6 kB
Tags Source
SHA-256 checksum
How to use checksums
6fdac58c76e9463bad0cbc8043e45f8970758b3bad005e00af22c7bac6d786f4
BLAKE2b-256 checksum
How to use checksums
fc8b3de4e009fb4c4d720e2255336bcc11f41c374c010d6be42da791865caea4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.15.2

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 14, 2026.

Transparency log

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

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

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 14, 2026.

Transparency log

Security for cdk-simplewebsite-deploy 3.0.7

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.7.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 14, 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.7 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