Configuration 

Configuration options and parameters for static site modules. Example uses of the options and parameters can be found in the Examples section.

Contents

Configuration
- Options
- Parameters

Options 

build_output: Optional[str] = None

Overrides default directory of top-level path setting.

Example

options:
  build_output: dist

build_steps: Optional[List[str]] = []

The steps to run during the build portion of deployment.

Example

options:
  build_steps:
    - npm ci
    - npm run build

extra_files: Optional[List[Dict[str, Union[str, Dict[str, Any]]]]] = []

Specifies extra files that should be uploaded to S3 after the build.

Use extra_files if you want to have a single build artifact that can be used in many environments. These files should be excluded from source hashing and the build system. The end result is that you have a build artifact that can be deployed in any environment and behave exactly the same.

See Extra Files for more details.

Example

options:
  extra_files:
    - name: config.json # yaml or other text files are supported
      content: # this object will be json or yaml serialized
        endpoint: ${var api_endpoint.${env DEPLOY_ENVIRONMENT}}
    - name: config.any
      content_type: text/yaml # Explicit content type
      content:
        endpoint: ${var api_endpoint.${env DEPLOY_ENVIRONMENT}}
    - name: logo.png
      content_type: image/png
      file: logo-${env DEPLOY_ENVIRONMENT}.png # a reference to an existing file

The example above produces a file named config.json with the contents below and a logo.png file.

{
  "endpoint": "<api_endpoint value>"
}

New in version 1.9.0.

pre_build_steps: Optional[List[Dict[str, str]]] = []

Commands to be run before generating the hash of files.

Example

options:
  pre_build_steps:
    - command: npm ci
      cwd: ../myothermodule # directory relative to top-level path setting
    - command: npm run export
      cwd: ../myothermodule

source_hashing: Optional[Dict[str, str]] = {}

Overrides for source hash collection and tracking

Example

options:
  source_hashing:
    enabled: true # if false, build & upload will occur on every deploy
    parameter: /${namespace}/myparam # defaults to <namespace>-<name/path>-hash
    directories: # overrides default hash directory of top-level path setting
      - path: ./
      - path: ../common
        # Additional (gitignore-format) exclusions to
        # hashing (.gitignore files are loaded automatically)
        exclusions:
          - foo/*

Parameters 

cloudformation_service_role: Optional[str] = None

IAM Role ARN that CloudFormation will use when creating, deleting and updating the CloudFormation stack resources.

See the AWS CloudFormation service role for more information.

Example

parameters:
  cloudformation_service_role: arn:aws:iam::123456789012:role/name

namespace: str

The unique namespace for the deployment.

Example

parameters:
  namespace: my-awesome-website-${env DEPLOY_ENVIRONMENT}

staticsite_acmcert_arn: Optional[str] = None

The certificate arn used for any alias domains supplied. This is a requirement when supplying any custom domain.

Example

parameters:
  staticsite_acmcert_arn: arn:aws:acm:<region>:<account-id>:certificate/<cert>

staticsite_aliases: Optional[str] = None

Any custom domains that should be added to the CloudFront Distribution. This should be represented as a comma delimited list of domains.

Requires staticsite_acmcert_arn.

Example

parameters:
  staticsite_aliases: example.com,foo.example.com

staticsite_auth_at_edge: Optional[bool] = False

Auth@Edge make the static site private by placing it behind an authorization wall. See Auth@Edge for more details.

Example

parameters:
  staticsite_auth_at_edge: true

New in version 1.5.0.

staticsite_cf_disable: Optional[bool] = False

Whether deployment of the CloudFront Distribution should be disabled.

Useful for a development site as it makes it accessible via an S3 url with a much shorter launch time. This cannot be set to true when using Auth@Edge.

Example

parameters:
  staticsite_cf_disable: false

New in version 1.5.0.

staticsite_compress: Optional[bool] = True

Whether the CloudFront default cache behavior will automatically compress certain files.

Example

parameters:
  staticsite_compress: false

staticsite_cookie_settings: Optional[Dict[str, str]] = {"idToken": "Path=/; Secure; SameSite=Lax", "accessToken": "Path=/; Secure; SameSite=Lax", "refreshToken": "Path=/; Secure; SameSite=Lax", "nonce": "Path=/; Secure; HttpOnly; Max-Age=1800; SameSite=Lax"}

The default cookie settings for retrieved tokens and generated nonce’s.

Requires staticsite_auth_at_edge.

Example

parameters:
  staticsite_cookie_settings:
    idToken: "Path=/; Secure; SameSite=Lax"
    accessToken: "Path=/; Secure; SameSite=Lax"
    refreshToken: "Path=/; Secure; SameSite=Lax"
    nonce: "Path=/; Secure; HttpOnly; Max-Age=1800; SameSite=Lax"

New in version 1.5.0.

staticsite_create_user_pool: Optional[bool] = False

Whether to create a User Pool for the Auth@Edge configuration.

Requires staticsite_auth_at_edge.

Example

parameters:
  staticsite_create_user_pool: true

New in version 1.5.0.

staticsite_custom_error_responses: Optional[List[Dict[str, Union[int, str]]]] = []

Define custom error responses.

Example

parameters:
  staticsite_custom_error_responses:
    - ErrorCode: 404
      ResponseCode: 200
      ResponsePagePath: /index.html

staticsite_enable_cf_logging: Optional[bool] = True

Whether logging should be enabled for the CloudFront distribution.

Example

parameters:
  staticsite_enable_cf_logging: true

staticsite_http_headers: Optional[Dict[str, str]] = {"Content-Security-Policy": "default-src https: 'unsafe-eval' 'unsafe-inline'; font-src 'self' 'unsafe-inline' 'unsafe-eval' data: https:; object-src 'none'; connect-src 'self' https://*.amazonaws.com https://*.amazoncognito.com", "Strict-Transport-Security": "max-age=31536000; includeSubdomains; preload", "Referrer-Policy": "same-origin", "X-XSS-Protection": "1; mode=block", "X-Frame-Options": "DENY", "X-Content-Type-Options": "nosniff"}

Headers that should be sent with each origin response.

Requires staticsite_auth_at_edge.

Note

Please note that the Content-Security-Policy is intentionally lax to allow for Single Page Application framework’s to work as expected. Review your Content Security Policy for your project and update these as need be to match.

Example

parameters:
  staticsite_http_headers:
    Content-Security-Policy: "default-src https: 'unsafe-eval' 'unsafe-inline'; font-src 'self' 'unsafe-inline' 'unsafe-eval' data: https:; object-src 'none'; connect-src 'self' https://*.amazonaws.com https://*.amazoncognito.com"
    Strict-Transport-Security: "max-age=31536000;  includeSubdomains; preload"
    Referrer-Policy: "same-origin"
    X-XSS-Protection: "1; mode=block"
    X-Frame-Options: "DENY"
    X-Content-Type-Options: "nosniff"

New in version 1.5.0.

staticsite_lambda_function_associations: Optional[List[Dict[str, str]]] = []

This section allows the user to deploy custom Lambda@Edge associations with their pre-build function versions. This takes precedence over staticsite_rewrite_directory_index and cannot currently be used with staticsite_auth_at_edge.

Example

parameters:
  staticsite_lambda_function_associations:
    - type: origin-request
      arn: arn:aws:lambda:<region>:<account-id>:function:<function>:<version>

staticsite_non_spa: Optional[bool] = False

Whether this site is a single page application (SPA).

A custom error response directing ErrorCode: 404 to the primary /index.html as a ResponseCode: 200 is added, allowing the SPA to take over error handling. If you are not running an SPA, setting this to true will prevent this custom error from being added. If provided, staticsite_custom_error_responses takes precedence over this setting.

Requires staticsite_auth_at_edge.

Example

parameters:
  staticsite_non_spa: true

New in version 1.5.0.

staticsite_oauth_scopes: Optional[List[str]] = ["phone", "email", "profile", "openid", "aws.cognito.signin.user.admin"]

Scope is a mechanism in OAuth 2.0 to limit an application’s access to a user’s account. An application can request one or more scopes. This information is then presented to the user in the consent screen and the access token issued to the application will be limited to the scopes granted.

Requires staticsite_auth_at_edge.

Example

parameters:
  staticsite_oauth_scopes:
    - phone
    - email
    - profile
    - openid
    - aws.cognito.signin.user.admin

New in version 1.5.0.

staticsite_redirect_path_auth_refresh: Optional[str] = "/refreshauth"

The path that a user is redirected to when their authorization tokens have expired (1 hour).

Requires staticsite_auth_at_edge.

Example

parameters:
  staticsite_redirect_path_auth_refresh: /refreshauth

New in version 1.5.0.

staticsite_redirect_path_sign_in: Optional[str] = "/parseauth"

The path that a user is redirected to after sign-in. This corresponds with the parseauth Lambda@Edge function which will parse the authentication details and verify the reception.

Requires staticsite_auth_at_edge.

Example

parameters:
  staticsite_redirect_path_sign_in: /parseauth

New in version 1.5.0.

staticsite_redirect_path_sign_out: Optional[str] = "/"

The path that a user is redirected to after sign-out. This typically should be the root of the site as the user will be asked to re-login.

Requires staticsite_auth_at_edge.

Example

parameters:
  staticsite_redirect_path_sign_out: /

New in version 1.5.0.

staticsite_rewrite_directory_index: Optional[str] = None

Deploy a Lambda@Edge function designed to rewrite directory indexes, e.g. supports accessing urls such as example.org/foo/

Example

parameters:
  staticsite_rewrite_directory_index: index.html

staticsite_role_boundary_arn: Optional[str] = None

Defines an IAM Managed Policy that will be set as the permissions boundary for any IAM Roles created to support the site. (e.g. when using staticsite_auth_at_edge or staticsite_rewrite_directory_index)

Example

parameters:
  staticsite_role_boundary_arn: arn:aws:iam::<account-id>:policy/<policy>

New in version 1.8.0.

staticsite_sign_out_url: Optional[str] = "/signout"

The path a user should access to sign themselves out of the application.

Requires staticsite_auth_at_edge.

Example

parameters:
  staticsite_sign_out_url: /signout

New in version 1.5.0.

staticsite_supported_identity_providers: Optional[str] = "COGNITO"

A comma delimited list of the User Pool client identity providers.

Requires staticsite_auth_at_edge.

Example

parameters:
  staticsite_supported_identity_providers: facebook,onelogin

New in version 1.5.0.

staticsite_user_pool_arn: Optional[str] = None

The ARN of a pre-existing Cognito User Pool to use with Auth@Edge.

Requires staticsite_auth_at_edge.

Example

parameters
  staticsite_user_pool_arn: arn:aws:cognito-idp:<region>:<account-id>:userpool/<pool>

New in version 1.5.0.

staticsite_additional_redirect_domains: Optional[str] = None

Additional domains (beyond the staticsite_aliases domains or the CloudFront URL if no aliases are provided) that will be authorized by the Auth@Edge UserPool AppClient. This parameter typically won’t be needed in production environments, but can be useful in development environments to allow bypassing Runway Auth@Edge.

This should be represented as a comma delimited list of domains with protocols. Requires staticsite_auth_at_edge.

Example

parameters:
  staticsite_additional_redirect_domains: http://localhost:3000

New in version 1.14.0.

staticsite_web_acl: Optional[str] = None

The ARN of a web access control list (web ACL) to associate with the CloudFront Distribution.

Example

parameters:
  staticsite_web_acl: arn:aws:waf::<account-id>:certificate/<cert>

staticsite_required_group: Optional[str] = None

Name of Cognito User Pool group of which users must be a member to be granted access to the site. Omit to allow all UserPool users to have access.

Requires staticsite_auth_at_edge.

Example

parameters:
  staticsite_required_group: AuthorizedUsers

New in version 1.5.0.

Configuration

Options

Parameters

Configuration 

Options 

Parameters 