This repository defines a CDK construct for hosting a static website on AWS using S3 and CloudFront.
It can be imported and used within CDK applications. By default this construct will create a CloudFront distribution with an S3 bucket as the origin. It will also create an IAM user and group that have permission to create files in the S3 bucket.
It has the following features that can optionally be enabled:
- Create a DNS record in an existing hosted zone
- Store CloudFront logs in an S3 bucket
- Add a custom backend origin
- Remap static files to the the S3 or backend origin
- Domain name for the stack. Combined with the subDomainName it is used as the name for the S3 origin and an alternative domain name for the CloudFront distribution
- Subdomain name for the stack. Combined with the domainName it is used as the name for the S3 origin and an alternative domain name for the CloudFront distribution
- An array of additional Cloudfront alternative domain names.
Default: undefined
- The arn of the certificate to attach to the CloudFront distribution. Must be created in us-east-1
- Custom backend host to add as a second origin to the CloudFront distribution
Default: undefined
- The hosted zone name to create a DNS record in. If not supplied a DNS record will not be created
Default: undefined
- Whether to create a group with permissions to publish to the S3 bucket.
Default: true
- Whether to create a user with permissions to publish to the S3 bucket. The user will not have permissions unless the publisher group is also created
Default: true
- Enable CloudFront access logs
Default: false
- Enable S3 access logging
Default: false
- Enable returning the errorResponsePagePath on a 404. Not required when using Prerender or Feature environment Lambda@Edge functions
Default: false
- Custom error response page path
Default: /index.html
- Create behaviours for the following file extensions to route straight to the S3 origin:
- js, css, json, svg, jpg, jpeg, png, gif, ico, woff, woff2, otf
Default: true
{
prefix: string;
behaviourOverride: Partial<BehaviorOptions>;
}[]
- Overrides default behaviour paths with a prefix and takes in behviour options to apply on the prefix behaviour
Default: true
- Optional additional properties for static file remap behaviours
Default: none
- Paths to remap on the default behaviour. For example you might remap deployed_sitemap.xml -> sitemap.xml
- Created a behaviour in CloudFront to handle the remap. If the paths are different it will also deploy a Lambda@Edge function to perform the required remap. The "to" path is optional, and the Lambda@Edge function will not be deployed if not provided.
Default: undefined
- Functions the same as remapPaths but uses the backendHost as the origin.
- Requires a valid backendHost to be configured
Default: undefined
- Override the default root object
Default: index.html
- Enforce ssl on bucket requests
Default: true
- Disable the use of the CSP header
Default: false
- Adds custom CSP directives and URLs to the header.
- AWS limits the max header size to 1kb, this is too small for complex csp headers.
- The main purpose of this csp header is to provide a method of setting a report-uri.
Default: undefined
- This will generate a csp based purely on the provided csp object. Therefore disabling the automatic adding of common use-case properties.
Default: false
- Extend the default props for S3 bucket
Default: undefined
- Add an external WAF via an arn
Default: undefined
- Add response headers policies to the default behaviour
Default: undefined
- Additional behaviours
Default: undefined
- Lambda@Edge functions to add to the default behaviour
Default: undefined
- A request policy used on the default behavior
Default: undefined
- A cache policy used on the default behavior
Default: undefined
- Additional headers to include in OriginRequestHeaderBehavior
- Additional headers to include in CacheHeaderBehavior
- After switching constructs, you need to maintain the same logical ID for the underlying CfnDistribution if you wish to avoid the deletion and recreation of your distribution.
- To do this, use escape hatches to override the logical ID created by the new Distribution construct with the logical ID created by theold construct
See: Migrating from original cfnDistribution - AWS Docs
Default: undefined
- A string to prefix CloudFormation outputs with
Default: undefined
- Add a comment to the CloudFront distribution
Default: undefined
The following CDK snippet can be used to provision a static hosting stack using this construct.
import 'source-map-support/register';
import * as cdk from '@aws-cdk/core';
import { StaticHosting, StaticHostingProps } from '@aligent/cdk-static-hosting'
import { Construct, Stack, StackProps } from '@aws-cdk/core';
const HostingStackProps : StaticHostingProps = {
subDomainName: 'sub.domain',
domainName: 'domain.tld',
certificateArn: 'arn:aws:acm:us-east-1:123456789:certificate/some-arn-id',
createDnsRecord: false,
enableErrorConfig: true
};
class HostingStack extends Stack {
constructor(scope: Construct, id: string, props: StackProps) {
super(scope, id, props);
new StaticHosting(this, 'hosting-stack', HostingStackProps);
}
}
const app = new cdk.App();
new HostingStack(app, 'hosting-stack', {
env: {
region: 'ap-southeast-2',
account: 'account-id',
}
});
You can initialize Response Headers Policies, map them and pass to the construct.
-
Create a policy
// Creating a custom response headers policy -- all parameters optional const reportUriPolicy = new ResponseHeadersPolicy(this, 'ReportUriPolicy', { responseHeadersPolicyName: 'ReportUriPolicy', comment: 'To enable CSP Reporting', customHeadersBehavior: { customHeaders: [ { header: 'content-security-policy-report-only', value: `default-src 'none'; form-action 'none'; frame-ancestors 'none'; report-uri https://some-report-uri-domain.report-uri.com/r/t/csp/wizard`, override: true }, ], }, });
-
Attached policy to desired cache behavior or path
const responseHeaders: ResponseHeaderMappings[] = [{ header: reportUriPolicy, pathPatterns: ['/au*', '/nz*'] attachToDefault: false }];
If you should attached the policy to the Default Behavior, set
attachToDefault: true
-
Include the config as props
new StaticHosting(this, 'pwa-stack', {...staticProps, ...{behaviors, customOriginConfigs, responseHeaders}});