Skip to content

Latest commit

 

History

History
247 lines (171 loc) · 6.95 KB

static-website.md

File metadata and controls

247 lines (171 loc) · 6.95 KB
Raw

Static website

The static-website construct deploys:

  • single-page applications, for example React or VueJS applications
  • plain static websites composed of HTML files and assets (CSS, JS…)

Quick start

serverless plugin install -n serverless-lift
service: my-app
provider:
    name: aws

constructs:
    landing:
        type: static-website
        path: public

plugins:
    - serverless-lift

On serverless deploy, the public/ directory will be deployed as a public website.

Note: the first deployment takes 4 minutes. Next deployments only take seconds.

The website is served over HTTPS and cached all over the world via the CloudFront CDN.

How it works

On the first serverless deploy, Lift creates:

  • an S3 bucket
  • a CloudFront CDN configured to serve the website from S3 over HTTPS, with caching at the edge
  • CloudFront Functions to set security HTTP headers

Additionally, every time serverless deploy runs, Lift:

  • uploads all files from the configured directory to the S3 bucket
  • invalidates the CloudFront cache so that the new version of the website is live

To learn more about the architecture of this construct, read this article.

Note: the S3 bucket is public and entirely managed by Lift. Do not store or upload files to the bucket, they will be removed by Lift on the next deployment. Instead, create a separate bucket to store any extra file.

React

To deploy a React app, use the following configuration:

constructs:
    react:
        type: static-website
        path: build

To deploy, run:

npm run build
serverless deploy

Vue

To deploy a Vue app, use the following configuration:

constructs:
    vue:
        type: static-website
        path: dist

To deploy, run:

npm run build
serverless deploy

Commands

serverless deploy deploys everything configured in serverless.yml and uploads website files.

It is possible to skip the CloudFormation deployment and directly publish website changes via:

serverless <construct-name>:upload

# For example:
serverless landing:upload

This command only takes seconds: it directly uploads files to S3 and clears the CloudFront cache.

Variables

All static-website constructs expose the following variables:

  • cname: the domain name of the resource, such as d111111abcdef8.cloudfront.net

This can be used to reference the bucket from Route53 configuration, for example:

constructs:
    landing:
        type: static-website
        path: public

resources:
  Resources:
    Route53Record:
      Type: AWS::Route53::RecordSet
      Properties:
        HostedZoneId: ZXXXXXXXXXXXXXXXXXXJ # Your HostedZoneId
        Name: app.mydomain
        Type: A
        AliasTarget:
          HostedZoneId: Z2FDTNDATAQYW2 # Cloudfront Route53 HostedZoneId. This does not change.
          DNSName: ${construct:landing.cname}

How it works: the ${construct:landing.cname} variable will automatically be replaced with a CloudFormation reference to the CloudFront Distribution.

Configuration reference

Path

constructs:
    landing:
        type: static-website
        path: public

The path option should point to the local directory containing the static website. Use path: . to upload the content of the current directory.

All files in that directory will be deployed and made available publicly.

When using a JavaScript bundler (for example when working with Webpack, VueJS, React, etc.), upload the compiled files. For example this could be the dist/ directory.

Custom domain

constructs:
    landing:
        # ...
        domain: mywebsite.com
        # ARN of an ACM certificate for the domain, registered in us-east-1
        certificate: arn:aws:acm:us-east-1:123456615250:certificate/0a28e63d-d3a9-4578-9f8b-14347bfe8123

The configuration above will activate the custom domain mywebsite.com on CloudFront, using the provided HTTPS certificate.

After running serverless deploy (or serverless info), you should see the following output in the terminal:

landing:
  url: https://mywebsite.com
  cname: s13hocjp.cloudfront.net

Create a CNAME DNS entry that points your domain to the xxx.cloudfront.net domain. After a few minutes/hours, the domain should be available.

HTTPS certificate

To create the HTTPS certificate:

  • Open the ACM Console in the us-east-1 region (CDN certificates must be in us-east-1, regardless of where your application is hosted)
  • Click "Request a new certificate", add your domain name and click "Next"
  • Choose a domain validation method:
    • Domain validation will require you to add CNAME entries to your DNS configuration
    • Email validation will require you to click a link in an email sent to admin@your-domain.com

After the certificate is created and validated, you should see the ARN of the certificate.

Multiple domains

It is possible to set up multiple domains:

constructs:
    landing:
        # ...
        domain:
            - mywebsite.com
            - app.mywebsite.com

Redirect all domains to a single one

It is sometimes necessary to redirect one or several domains to a single one. A common example is to redirect the root domain to the www version.

constructs:
    website:
        # ...
        domain:
            - www.mywebsite.com
            - mywebsite.com
        redirectToMainDomain: true

The first domain in the list will be considered the main domain. In this case, mywebsite.com will redirect to www.mywebsite.com.

Error page

By default, all 404 requests are redirected to index.html with a 200 response status. This behavior is optimized for Single-Page Applications: it allows doing client-side URL routing with JavaScript frameworks.

For static websites that are not SPA, it is possible to serve a custom "Not found" error page:

constructs:
    landing:
        # ...
        errorPage: error.html # can be any HTML file in your project

When a browser requests the URL of a non-existing file, the error.html file will be served with a 404 response status.

Do not use this setting when doing JavaScript URL routing: this will break URL routing.

Allow iframes

By default, as recommended for security reasons, the static website cannot be embedded in an iframe.

To allow embedding the website in an iframe, set it up explicitly:

constructs:
    landing:
        # ...
        security:
            allowIframe: true

More options

Looking for more options in the construct configuration? Open a GitHub issue.