[CDK Pattern] SPA-Website

This CDK Pattern to make deploying a Single Page Application (SPA) Website (ReactJS / VueJS / Angular) to AWS S3 behind CloudFront CDN, Route53 DNS, AWS Certificate Manager SSL easier.

The workflow for an SPA-Website supporting customer-specific subdomains:

1. Customers access your application through a browser by entering their personal subdomain (for example, https://devax.job4u.vn).
2. Amazon Route53 receives the request for the customer-specific subdomain and routes it to the Amazon CloudFront Distribution.
3. CloudFront caches your web application from the Amazon S3 Bucket where it is stored. Note that the CloudFront Distribution is configured with read-only permissions to access files in Amazon S3.
4. CloudFront uses a TLS certificate provisioned in ACM to deliver the content from the nearest edge location.

Installation and Usage

import * as cdk from '@aws-cdk/core';
import { SpaWebsite } from 'spa-website';

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

    /** Deploying a Website to AWS S3 */
    new SpaWebsite(this, 'SPA-Website-S3')
      .createBasicSite({
        indexDoc: 'index.html',
        websiteFolder: '../../projects/startup-blueprint'
      });

    /** Deploying a SPA-Website to AWS S3 behind CloudFront CDN */
    new SpaWebsite(this, 'SPA-Website-Cloudfront')
      .createSiteWithCloudfront({
        indexDoc: 'index.html',
        websiteFolder: '../../projects/admin-dashboard/build'
      });
  }
}

Advanced Usage

Auto Deploy From Hosted Zone Name

If you purchased your domain through route 53 and already have a hosted zone then just use the name to deploy your site behind cloudfront. This handles the SSL cert and everything for you.

new SpaWebsite(this, 'SPA-Website', { encryptBucket: true })
  .createSiteFromHostedZone({
    zoneName: 'devax.job4u.vn',
    indexDoc: 'index.html',
    websiteFolder: '../../projects/admin-dashboard/build'
  });

Custom Domain and SSL Certificates

You can also pass the ARN for an SSL certification and your alias routes to cloudfront

import * as cdk from '@aws-cdk/core';
import { SpaWebsite } from 'spa-website';

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

    new SpaWebsite(this, 'SPA-Website-Cloudfront')
      .createSiteWithCloudfront({
        indexDoc: '../../projects/startup-blueprint',
        certificateARN: 'arn:...',
        cfAliases: ['www.alias.com']
      });
  }  
}

Encrypted S3 Bucket

Pass in one boolean to tell SPA Deploy to encrypt your website bucket

new SpaWebsite(this, 'SPA-Website-Cloudfront', {encryptBucket: true}).createBasicSite({
    indexDoc: 'index.html',
    websiteFolder: 'website'
});

Custom Origin Behaviors

Pass in an array of CloudFront Behaviors

new SpaWebsite(this, 'SPA-Website-Cloudfront').createSiteWithCloudfront({
  indexDoc: 'index.html',
  websiteFolder: 'website',
  cfBehaviors: [
    {
      isDefaultBehavior: true,
      allowedMethods: cf.CloudFrontAllowedMethods.ALL,
      forwardedValues: {
        queryString: true,
        cookies: { forward: 'all' },
        headers: ['*'],
      },
    },
    {
      pathPattern: '/virtual-path',
      allowedMethods: cf.CloudFrontAllowedMethods.GET_HEAD,
      cachedMethods: cf.CloudFrontAllowedCachedMethods.GET_HEAD,
    },
  ],
});

Restrict Access to Known IPs

Pass in a boolean and an array of IP addresses and your site is locked down!

new SpaWebsite(stack, 'SPA-Website', { 
  encryptBucket: true, 
  ipFilter: true, 
  ipList: ['1.1.1.1']
}).createBasicSite({
    indexDoc: 'index.html',
    websiteFolder: 'website'
  })

Modifying S3 Bucket Created in Construct

An object is now returned containing relevant artifacts created if you need to make any further modifications:

• The S3 bucket is present for all of the methods
• When a CloudFront Web distribution is created it will be present in the return object

export interface SpaWebsiteDeployment {
  readonly websiteBucket: s3.Bucket,
}

export interface SpaWebsiteDeploymentWithCloudFront extends SPADeployment {
  readonly distribution: CloudFrontWebDistribution,
}

Project Directory

/cdk/constructs/spa-website
├── README.md
├── jest.config.js
├── lib
|  └── index.ts
├── package.json
├── test
|  └── spa-website.test.ts
├── tsconfig.json
├── tsconfig.tsbuildinfo
└── website
   └── index.html