Serverless Website Domain

A plugin that creates Route 53 records that point to your Cloudfront hosted static website, including www/non-www redirects.


A Serverless plugin specifically designed to set up domains for your static website (not API Gateway). It creates Route 53 entries that point to your Cloudfront Distribution.


  • Maps both HTTP & HTTPS non-www variants of your domain to
  • Works alongside other popular plugins: - serverless-certificate-creator - serverless-s3-sync - serverless-cloudfront-invalidate
  • Simple examples in /examples folder


This plugin requires that you use at least serverless version 2.27.0 because it relies on the new variable resolution system introduced in this PR here. You must also add 'variablesResolutionMode: 20210219' at the root of serverless.yml file, this will be removed once serverless v3 is released. If you are using alongside serverless-certificate-creator you must use version >= 1.5.0 so that it supports the new variable reoslution mode as well.

Before running you must manually create a Hosted Zone in Route 53. with domain name

How to use?

Add the plugin to your serverless.yml


Add plugin configuration to serverless.yml

  domainComponents: #Key not needed, just used as example.
    withWWW: www.${self:custom.domainComponents.withoutWWW}
    cloudfrontOutputKey: 'yourCloudfrontDomainName'
    domain: ${self:custom.domainComponents.withWWW} #must be hostedZoneDomain or subdomain of it
      basicAuthCredentials: ${env:BASIC_AUTH_CREDENTIALS}
        from: ${self:custom.domainComponents.withoutWWW}
        to: https://${self:custom.domainComponents.withWWW}
variablesResolutionMode: 20210219
        'Fn::GetAtt': [ CloudFrontDistribution, DomainName ]
      Type: AWS::CloudFront::Distribution
          - ${self:custom.domainComponents.withWWW}
          - ${self:custom.domainComponents.withoutWWW}
              - EventType: viewer-request
                LambdaFunctionARN: ${websiteDomain:edgeLambdaArn}
            #manually specify ARN:
            AcmCertificateArn: ${certificate:${self:custom.customCertificate.certificateName}.CertificateArn}

How to run

To create the domain

serverless create-edge-lambda #If you are using custom.websiteDomain.edgeLambda
serverless deploy #Called in after:deploy hook

There are also other manual commands you can run:

serverless remove-domain
serverless create-domain
serverless remove-edge-lambda

create-domain will also be called automatically by serverless deploy during the after:deploy hook. The recommended approach is to not use 'createDomain' and instead let it run automatically during deploy as it is dependent on the Cloudfront distribution first being deployed.

If you are using alongside serverless-certificate-creator you should call serverless create-cert before serverless create-redirect. You must also ensure that you include both www & non-www variants in subjectAlternativeNames. E.G:

  certificateName: ${self:custom.domainComponents.withWWW}
  hostedZoneNames: ${env:AWS_ROUTE53_HOSTED_ZONE_DOMAIN_NAME}.
    - '${self:custom.domainComponents.withoutWWW}'


It's highly recommended to look at the files in the examples directory to start with. It shows how to use this plugin alongside serverless-certificate-creator, serverless-s3-sync & serverless-cloudfront-invalidate for a full solution including environment specific domains (e.g


Name Required Data Type Default Description
cloudfrontOutputKey Y String Should match key in resource.outputs which contains Cloudfront domain name (e.g 'Fn::GetAtt': [ CloudFrontDistribution, DomainName ]).
domain Y String The domain you want to create. (e.g or Must exist under hosted zone of hostedZoneId.
edgeLambda N Object NULL Parent property
basicAuthCredentials N String NULL Specify to guard website with basic auth. Separate username & password with '/' or use empty string to disable.
redirect N Object NULL Parent property.
redirect.from Y Object NULL Required if .redirect set. 'It will be matched against lambda[0]. It will also create a route 53 A & AAAA record for it. If you want to redirect from to just enter '' here. Y Object NULL Required if .redirect set. It is the full destination URL including protocol. (E.G .
view on Github

Latest commit b2f54ec on Sep 24, 2017

New to serverless?

To get started, pop open your terminal & run:

npm install serverless -g