Namespace Amazon.CDK.AWS.Amplify.Alpha

AWS Amplify Construct Library

--- cdk-constructs: Experimental 
The APIs of higher level constructs in this module are experimental and under active development.
They are subject to non-backward compatible changes or removal in any future version. These are
not subject to the <a href="https://semver.org/">Semantic Versioning</a> model and breaking changes will be
announced in the release notes. This means that while you may use them, you may need to update
your source code when upgrading to a newer version of this package.

The AWS Amplify Console provides a Git-based workflow for deploying and hosting fullstack serverless web applications. A fullstack serverless app consists of a backend built with cloud resources such as GraphQL or REST APIs, file and data storage, and a frontend built with single page application frameworks such as React, Angular, Vue, or Gatsby.

Setting up an app with branches, custom rules and a domain

To set up an Amplify Console app, define an App:

using Amazon.CDK.AWS.CodeBuild;


var amplifyApp = new App(this, "MyApp", new AppProps {
    SourceCodeProvider = new GitHubSourceCodeProvider(new GitHubSourceCodeProviderProps {
        Owner = "<user>",
        Repository = "<repo>",
        OauthToken = SecretValue.SecretsManager("my-github-token")
    }),
    BuildSpec = BuildSpec.FromObjectToYaml(new Dictionary<string, object> {
        // Alternatively add a `amplify.yml` to the repo
        { "version", "1.0" },
        { "frontend", new Dictionary<string, IDictionary<string, IDictionary<string, string[]>>> {
            { "phases", new Struct {
                PreBuild = new Struct {
                    Commands = new [] { "yarn" }
                },
                Build = new Struct {
                    Commands = new [] { "yarn build" }
                }
            } },
            { "artifacts", new Struct {
                BaseDirectory = "public",
                Files = -"**/*"
            } }
        } }
    })
});

To connect your App to GitLab, use the GitLabSourceCodeProvider:

var amplifyApp = new App(this, "MyApp", new AppProps {
    SourceCodeProvider = new GitLabSourceCodeProvider(new GitLabSourceCodeProviderProps {
        Owner = "<user>",
        Repository = "<repo>",
        OauthToken = SecretValue.SecretsManager("my-gitlab-token")
    })
});

To connect your App to CodeCommit, use the CodeCommitSourceCodeProvider:

using Amazon.CDK.AWS.CodeCommit;


var repository = new Repository(this, "Repo", new RepositoryProps {
    RepositoryName = "my-repo"
});

var amplifyApp = new App(this, "App", new AppProps {
    SourceCodeProvider = new CodeCommitSourceCodeProvider(new CodeCommitSourceCodeProviderProps { Repository = repository })
});

The IAM role associated with the App will automatically be granted the permission to pull the CodeCommit repository.

Add branches:

App amplifyApp;


var main = amplifyApp.AddBranch("main"); // `id` will be used as repo branch name
var dev = amplifyApp.AddBranch("dev", new BranchOptions {
    PerformanceMode = true
});
dev.AddEnvironment("STAGE", "dev");

Auto build and pull request preview are enabled by default.

Add custom rules for redirection:

App amplifyApp;

amplifyApp.AddCustomRule(new Dictionary<string, object> {
    { "source", "/docs/specific-filename.html" },
    { "target", "/documents/different-filename.html" },
    { "status", RedirectStatus.TEMPORARY_REDIRECT }
});

When working with a single page application (SPA), use the CustomRule.SINGLE_PAGE_APPLICATION_REDIRECT to set up a 200 rewrite for all files to index.html except for the following file extensions: css, gif, ico, jpg, js, png, txt, svg, woff, ttf, map, json, webmanifest.

App mySinglePageApp;


mySinglePageApp.AddCustomRule(CustomRule.SINGLE_PAGE_APPLICATION_REDIRECT);

Add a domain and map sub domains to branches:

App amplifyApp;
Branch main;
Branch dev;


var domain = amplifyApp.AddDomain("example.com", new DomainOptions {
    EnableAutoSubdomain = true,  // in case subdomains should be auto registered for branches
    AutoSubdomainCreationPatterns = new [] { "*", "pr*" }
});
domain.MapRoot(main); // map main branch to domain root
domain.MapSubDomain(main, "www");
domain.MapSubDomain(dev);

To specify a custom certificate for your custom domain use the customCertificate property:

Certificate customCertificate;
App amplifyApp;


var domain = amplifyApp.AddDomain("example.com", new DomainOptions {
    CustomCertificate = customCertificate
});

Restricting access

Password protect the app with basic auth by specifying the basicAuth prop.

Use BasicAuth.fromCredentials when referencing an existing secret:

var amplifyApp = new App(this, "MyApp", new AppProps {
    SourceCodeProvider = new GitHubSourceCodeProvider(new GitHubSourceCodeProviderProps {
        Owner = "<user>",
        Repository = "<repo>",
        OauthToken = SecretValue.SecretsManager("my-github-token")
    }),
    BasicAuth = BasicAuth.FromCredentials("username", SecretValue.SecretsManager("my-github-token"))
});

Use BasicAuth.fromGeneratedPassword to generate a password in Secrets Manager:

var amplifyApp = new App(this, "MyApp", new AppProps {
    SourceCodeProvider = new GitHubSourceCodeProvider(new GitHubSourceCodeProviderProps {
        Owner = "<user>",
        Repository = "<repo>",
        OauthToken = SecretValue.SecretsManager("my-github-token")
    }),
    BasicAuth = BasicAuth.FromGeneratedPassword("username")
});

Basic auth can be added to specific branches:

App amplifyApp;

amplifyApp.AddBranch("feature/next", new BranchOptions {
    BasicAuth = BasicAuth.FromGeneratedPassword("username")
});

Automatically creating and deleting branches

Use the autoBranchCreation and autoBranchDeletion props to control creation/deletion of branches:

var amplifyApp = new App(this, "MyApp", new AppProps {
    SourceCodeProvider = new GitHubSourceCodeProvider(new GitHubSourceCodeProviderProps {
        Owner = "<user>",
        Repository = "<repo>",
        OauthToken = SecretValue.SecretsManager("my-github-token")
    }),
    AutoBranchCreation = new AutoBranchCreation {  // Automatically connect branches that match a pattern set
        Patterns = new [] { "feature/*", "test/*" } },
    AutoBranchDeletion = true
});

Adding custom response headers

Use the customResponseHeaders prop to configure custom response headers for an Amplify app:

var amplifyApp = new App(this, "App", new AppProps {
    SourceCodeProvider = new GitHubSourceCodeProvider(new GitHubSourceCodeProviderProps {
        Owner = "<user>",
        Repository = "<repo>",
        OauthToken = SecretValue.SecretsManager("my-github-token")
    }),
    CustomResponseHeaders = new [] { new CustomResponseHeader {
        Pattern = "*.json",
        Headers = new Dictionary<string, string> {
            { "custom-header-name-1", "custom-header-value-1" },
            { "custom-header-name-2", "custom-header-value-2" }
        }
    }, new CustomResponseHeader {
        Pattern = "/path/*",
        Headers = new Dictionary<string, string> {
            { "custom-header-name-1", "custom-header-value-2" }
        }
    } }
});

Configure server side rendering when hosting app

Setting the platform field on the Amplify App construct can be used to control whether the app will host only static assets or server side rendered assets in addition to static. By default, the value is set to WEB (static only), however, server side rendering can be turned on by setting to WEB_COMPUTE as follows:

var amplifyApp = new App(this, "MyApp", new AppProps {
    Platform = Platform.WEB_COMPUTE
});

Cache Config

Amplify uses Amazon CloudFront to manage the caching configuration for your hosted applications. A cache configuration is applied to each app to optimize for the best performance.

Setting the cacheConfigType field on the Amplify App construct can be used to control cache configguration. By default, the value is set to AMPLIFY_MANAGED. If you want to exclude all cookies from the cache key, set AMPLIFY_MANAGED_NO_COOKIES.

For more information, see Managing the cache configuration for an app.

var amplifyApp = new App(this, "MyApp", new AppProps {
    CacheConfigType = CacheConfigType.AMPLIFY_MANAGED_NO_COOKIES
});

Deploying Assets

sourceCodeProvider is optional; when this is not specified the Amplify app can be deployed to using .zip packages. The asset property can be used to deploy S3 assets to Amplify as part of the CDK:

using Amazon.CDK.AWS.S3.Assets;

Asset asset;
App amplifyApp;

var branch = amplifyApp.AddBranch("dev", new BranchOptions { Asset = asset });

Classes

App

(experimental) An Amplify Console application.
AppProps

(experimental) Properties for an App.
AutoBranchCreation

(experimental) Auto branch creation configuration.
BasicAuth

(experimental) Basic Auth configuration.
BasicAuthConfig

(experimental) A Basic Auth configuration.
BasicAuthProps

(experimental) Properties for a BasicAuth.
Branch

(experimental) An Amplify Console branch.
BranchOptions

(experimental) Options to add a branch to an application.
BranchProps

(experimental) Properties for a Branch.
CacheConfigType

(experimental) The type of cache configuration to use for an Amplify app.
CodeCommitSourceCodeProvider

(experimental) CodeCommit source code provider.
CodeCommitSourceCodeProviderProps

(experimental) Properties for a CodeCommit source code provider.
CustomResponseHeader

(experimental) Custom response header of an Amplify App.
CustomRule

(experimental) Custom rewrite/redirect rule for an Amplify App.
CustomRuleOptions

(experimental) Options for a custom rewrite/redirect rule for an Amplify App.
Domain

(experimental) An Amplify Console domain.
DomainOptions

(experimental) Options to add a domain to an application.
DomainProps

(experimental) Properties for a Domain.
GitHubSourceCodeProvider

(experimental) GitHub source code provider.
GitHubSourceCodeProviderProps

(experimental) Properties for a GitHub source code provider.
GitLabSourceCodeProvider

(experimental) GitLab source code provider.
GitLabSourceCodeProviderProps

(experimental) Properties for a GitLab source code provider.
Platform

(experimental) Available hosting platforms to use on the App.
RedirectStatus

(experimental) The status code for a URL rewrite or redirect rule.
SourceCodeProviderConfig

(experimental) Configuration for the source code provider.
SubDomain

(experimental) Sub domain settings.

Interfaces

IApp

(experimental) An Amplify Console application.
IAppProps

(experimental) Properties for an App.
IAutoBranchCreation

(experimental) Auto branch creation configuration.
IBasicAuthConfig

(experimental) A Basic Auth configuration.
IBasicAuthProps

(experimental) Properties for a BasicAuth.
IBranch

(experimental) A branch.
IBranchOptions

(experimental) Options to add a branch to an application.
IBranchProps

(experimental) Properties for a Branch.
ICodeCommitSourceCodeProviderProps

(experimental) Properties for a CodeCommit source code provider.
ICustomResponseHeader

(experimental) Custom response header of an Amplify App.
ICustomRuleOptions

(experimental) Options for a custom rewrite/redirect rule for an Amplify App.
IDomainOptions

(experimental) Options to add a domain to an application.
IDomainProps

(experimental) Properties for a Domain.
IGitHubSourceCodeProviderProps

(experimental) Properties for a GitHub source code provider.
IGitLabSourceCodeProviderProps

(experimental) Properties for a GitLab source code provider.
ISourceCodeProvider

(experimental) A source code provider.
ISourceCodeProviderConfig

(experimental) Configuration for the source code provider.
ISubDomain

(experimental) Sub domain settings.