Introducing CloudFront Hosting Toolkit

Today, we released the CloudFront Hosting Toolkit, an open source command line interface (CLI) tool to help you deploy fast and secure front-ends in the cloud. Install the CloudFront Hosting Toolkit CLI through npm, run two commands, and CloudFront Hosting Toolkit CLI automatically creates the deployment pipeline and infrastructure needed to build, deploy, and serve your front-end application following each Git push.

At the same time, you retain full control over the cloud resources powering your application and can modify the underlying resources at any time for complete flexibility. This frees you from time-consuming setup and allows you to quickly deploy, manage, and customize well-architected front-ends using your existing Git workflow.

Front-end developers need to deploy fast and secure web applications quickly and with minimal effort. Currently, developers’ first choice for hosting web applications on Amazon Web Services (AWS) is using a managed service like AWS Amplify. This allows them to focus on writing code rather than the time-consuming, unnecessary complexity needed to configure their hosting infrastructure and deployment pipelines. While developers love how easy it is to get started and automatically deploy changes, some customers tell us they need the flexibility to take control over various parts of their application’s infrastructure to further customize. For example, some developers need to configure the content delivery network (CDN) serving the front-end with CloudFront Functions to enrich the content delivery with custom logic. To achieve that level of flexibility, those customers must fall back to building their hosting infrastructure and deployment pipelines from scratch to configure storage, acceleration, caching, web serving, and security. Developers tell us they want the setup convenience of a managed front-end service with the flexibility to customize their application to meet their exact needs.

Now with CloudFront Hosting Toolkit, you can quickly deploy well-architected front-ends on AWS while retaining full control of the underlying cloud infrastructure. CloudFront Hosting Toolkit automatically creates the required infrastructure resources in your AWS account and configures Git-based deployments to deploy applications within minutes—without the need for you to have prior AWS experience. You can take full control over the underlying AWS resources to tailor your application to your exact needs by modifying elements of the existing infrastructure rather than starting from scratch. This gives you the convenience of a managed service while putting you in full control of the hosting infrastructure and deployment pipelines to make it your own.

This first version of CloudFront Hosting Toolkit supports the following capabilities:

• Hosting static front ends such as single page applications (SPAs) and those based on static site generation (SSG).
• Easy integration with GitHub for version control
• Atomic and immutable instant deploys
• CLI with a friendly wizard to simplify setup
• Security and caching best practices incorporated in the hosting infrastructure
• Custom domain name support

Getting started with the toolkit

The easiest way is to start with the CloudFront Hosting Toolkit CLI to deploy a front-end from your GitHub repository. First, install the toolkit prerequisites (Node.js 18+ and AWS CLI configured with the appropriate AWS account and the hosting AWS Region), then install the toolkit globally:

npm install -g @aws/cloudfront-hosting-toolkit

Then navigate to the local folder where you cloned the GitHub repository of your front-end and initialize your deployment configuration:

cd /path/to/your/repo
cloudfront-hosting-toolkit init

The CLI automatically detects the attributes of your front-end project, such as the web framework used—whether it’s React, Next.js, Vue.js, or AngularJS, and so on—and guides you through the initialization steps. In one of the steps, you are prompted to establish a connection to the GitHub repository in the AWS console, serving as the backbone of the deployment pipeline, automatically triggering new deployments with each push to your repository. Once the hosting parameters are set up in the initialization phase, deploy the hosting of your website within a couple of minutes.

cloudfront-hosting-toolkit deploy

Upon successful deployment, the CLI provides you with the website endpoint where your application is hosted unless you have configured your own domain name to serve it. Every time you make a change to your front-end code on GitHub, the toolkit automatically generates a new build and deploys it. In a few minutes, the new version is published without any additional actions on your side.

Behind the scenes – Architecture

The following architecture shows the main components deployed within the hosting infrastructure.

Figure 1: Architecture of CloudFront Hosting Toolkit

Front-ends are stored in an Amazon Simple Storage Service (Amazon S3) bucket and served through an Amazon CloudFront distribution configured according to performance and security best practices. The front-end deployment pipeline is managed by AWS CodePipeline, which uploads the front-end artifacts to the S3 bucket and instructs CloudFront to serve the latest version. The following sequence diagram explains the event flow:

Figure 2: CloudFront Hosting Toolkit – Event flow

1. A user makes a request to the about page of the web application.
2. When CloudFront receives the HTTP request, a CloudFront function is executed to add any file extension required by the used web framework (such as .html) and then maps the request to the file on Amazon S3 associated with the latest front-end version (for example, /1sd424Po/about.html). The function reads the version value from CloudFront KeyValueStore.
3. If there is a cache miss, the file is fetched from Amazon S3. Otherwise, it’s served from the CloudFront cache. Caching is enabled by default on CloudFront for 1 year, and headers are sent to browsers to cache it for 60 seconds. Security headers are added on HTTP responses to browsers, and the bucket is only accessible by CloudFront thanks to the origin access control feature.
4. At some point, the front-end developer pushes new code changes to the corresponding GitHub repository. (Alternatively, a .zip file is uploaded to an S3 bucket in the S3 based workflow.)
5. This automatically triggers a workflow in AWS CodePipeline. In the Build step of the pipeline, tasks such as compiling code and creating deployment artifacts are executed according to the detected web framework in the initialization step of the CLI.
6. The output deployment artifacts are then uploaded to the hosting S3 bucket under a new folder identified by the commit ID (for example, 94EdAd09)
7. In the Deploy step of the pipeline, an AWS Step Functions workflow orchestrates an update to CloudFront KeyValueStore to instruct the CloudFront Function to map requests to files in the newly created folder in Amazon S3.
8. Finally, when another user makes a request to the about page, CloudFront receives the request, and the same CloudFront function is executed. However, the function now maps the request to the file on Amazon S3 (for example, /94EdAd09/about.html) and bypasses the cached file of the previous front-end version because it adds the commit ID to the cache key.

CloudFront Hosting Toolkit adapts to your specific needs, whether you’re a developer looking for a straightforward deployment process using a CLI, an infrastructure specialist who prefers customizing AWS Cloud Development Kit (AWS CDK) code, or a project manager seeking a CDK L3 construct for seamless integration into AWS infrastructure projects. For advanced usage scenarios and in-depth configurations, please refer to the CloudFront Hosting Toolkit README page.

Conclusion

Some developers want a simple, convenient, and efficient workflow to deploy their front-ends to the cloud while retaining control over how their front-ends are served online. CloudFront Hosting Toolkit strikes a balance between the benefit of a managed hosting experience built by AWS experts and the level of flexibility and control developers love about AWS. Try the CLI and share your feedback on the project’s GitHub page, star it, report an issue, or file a feature request. If you are interested in helping us make this tool better, check out our Contributing Guidelines. CloudFront Hosting Toolkit is licensed under the Apache-2.0 License.

To learn more about how to accelerate and secure your websites and APIs, see the Application Security and Performance section of the AWS Developer Center.