Namespace Amazon.CDK.AWS.Amplify
AWS Amplify Construct Library
---AWS CDK v1 has reached End-of-Support on 2023-06-01.
This package is no longer being updated, and users should migrate to AWS CDK v2.
For more information on how to migrate, see the Migrating to AWS CDK v2 guide.
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 master = amplifyApp.AddBranch("master"); // `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 master;
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(master); // map master branch to domain root
domain.MapSubDomain(master, "www");
domain.MapSubDomain(dev);
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" }
}
} }
});
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. |
CfnApp | A CloudFormation |
CfnApp.AutoBranchCreationConfigProperty | Use the AutoBranchCreationConfig property type to automatically create branches that match a certain pattern. |
CfnApp.BasicAuthConfigProperty | Use the BasicAuthConfig property type to set password protection at an app level to all your branches. |
CfnApp.CustomRuleProperty | The CustomRule property type allows you to specify redirects, rewrites, and reverse proxies. |
CfnApp.EnvironmentVariableProperty | Environment variables are key-value pairs that are available at build time. |
CfnAppProps | Properties for defining a |
CfnBranch | A CloudFormation |
CfnBranch.BasicAuthConfigProperty | Use the BasicAuthConfig property type to set password protection for a specific branch. |
CfnBranch.EnvironmentVariableProperty | The EnvironmentVariable property type sets environment variables for a specific branch. |
CfnBranchProps | Properties for defining a |
CfnDomain | A CloudFormation |
CfnDomain.SubDomainSettingProperty | The SubDomainSetting property type enables you to connect a subdomain (for example, example.exampledomain.com) to a specific branch. |
CfnDomainProps | Properties for defining a |
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. |
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
CfnApp.IAutoBranchCreationConfigProperty | Use the AutoBranchCreationConfig property type to automatically create branches that match a certain pattern. |
CfnApp.IBasicAuthConfigProperty | Use the BasicAuthConfig property type to set password protection at an app level to all your branches. |
CfnApp.ICustomRuleProperty | The CustomRule property type allows you to specify redirects, rewrites, and reverse proxies. |
CfnApp.IEnvironmentVariableProperty | Environment variables are key-value pairs that are available at build time. |
CfnBranch.IBasicAuthConfigProperty | Use the BasicAuthConfig property type to set password protection for a specific branch. |
CfnBranch.IEnvironmentVariableProperty | The EnvironmentVariable property type sets environment variables for a specific branch. |
CfnDomain.ISubDomainSettingProperty | The SubDomainSetting property type enables you to connect a subdomain (for example, example.exampledomain.com) to a specific branch. |
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. |
ICfnAppProps | Properties for defining a |
ICfnBranchProps | Properties for defining a |
ICfnDomainProps | Properties for defining a |
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. |