aws-amplify-alpha-readme

@aws-cdk/aws-amplify-alpha module

LanguagePackage
.NETAmazon.CDK.AWS.Amplify.Alpha
Gogithub.com/aws/aws-cdk-go/awscdkamplifyalpha/v2
Javasoftware.amazon.awscdk.services.amplify.alpha
Pythonaws_cdk.aws_amplify_alpha
TypeScript@aws-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 Semantic Versioning 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:

import * as codebuild from 'aws-cdk-lib/aws-codebuild';

const amplifyApp = new amplify.App(this, 'MyApp', {
  sourceCodeProvider: new amplify.GitHubSourceCodeProvider({
    owner: '<user>',
    repository: '<repo>',
    oauthToken: SecretValue.secretsManager('my-github-token'),
  }),
  buildSpec: codebuild.BuildSpec.fromObjectToYaml({
    // Alternatively add a `amplify.yml` to the repo
    version: '1.0',
    frontend: {
      phases: {
        preBuild: {
          commands: [
            'yarn',
          ],
        },
        build: {
          commands: [
            'yarn build',
          ],
        },
      },
      artifacts: {
        baseDirectory: 'public',
        files:
        - '**/*',
      },
    },
  }),
});

Example not in your language?

To connect your App to GitLab, use the GitLabSourceCodeProvider:

const amplifyApp = new amplify.App(this, 'MyApp', {
  sourceCodeProvider: new amplify.GitLabSourceCodeProvider({
    owner: '<user>',
    repository: '<repo>',
    oauthToken: SecretValue.secretsManager('my-gitlab-token'),
  }),
});

Example not in your language?

To connect your App to CodeCommit, use the CodeCommitSourceCodeProvider:

import * as codecommit from 'aws-cdk-lib/aws-codecommit';

const repository = new codecommit.Repository(this, 'Repo', {
  repositoryName: 'my-repo',
});

const amplifyApp = new amplify.App(this, 'App', {
  sourceCodeProvider: new amplify.CodeCommitSourceCodeProvider({ repository }),
});

Example not in your language?

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

Add branches:

declare const amplifyApp: amplify.App;

const main = amplifyApp.addBranch('main'); // `id` will be used as repo branch name
const dev = amplifyApp.addBranch('dev', {
  performanceMode: true, // optional, enables performance mode
});
dev.addEnvironment('STAGE', 'dev');

Example not in your language?

Auto build and pull request preview are enabled by default.

Add custom rules for redirection:

declare const amplifyApp: amplify.App;
amplifyApp.addCustomRule({
  source: '/docs/specific-filename.html',
  target: '/documents/different-filename.html',
  status: amplify.RedirectStatus.TEMPORARY_REDIRECT,
});

Example not in your language?

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.

declare const mySinglePageApp: amplify.App;

mySinglePageApp.addCustomRule(amplify.CustomRule.SINGLE_PAGE_APPLICATION_REDIRECT);

Example not in your language?

Add a domain and map sub domains to branches:

declare const amplifyApp: amplify.App;
declare const main: amplify.Branch;
declare const dev: amplify.Branch;

const domain = amplifyApp.addDomain('example.com', {
  enableAutoSubdomain: true, // in case subdomains should be auto registered for branches
  autoSubdomainCreationPatterns: ['*', 'pr*'], // regex for branches that should auto register subdomains
});
domain.mapRoot(main); // map main branch to domain root
domain.mapSubDomain(main, 'www');
domain.mapSubDomain(dev); // sub domain prefix defaults to branch name

Example not in your language?

Restricting access

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

Use BasicAuth.fromCredentials when referencing an existing secret:

const amplifyApp = new amplify.App(this, 'MyApp', {
  sourceCodeProvider: new amplify.GitHubSourceCodeProvider({
    owner: '<user>',
    repository: '<repo>',
    oauthToken: SecretValue.secretsManager('my-github-token'),
  }),
  basicAuth: amplify.BasicAuth.fromCredentials('username', SecretValue.secretsManager('my-github-token')),
});

Example not in your language?

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

const amplifyApp = new amplify.App(this, 'MyApp', {
  sourceCodeProvider: new amplify.GitHubSourceCodeProvider({
    owner: '<user>',
    repository: '<repo>',
    oauthToken: SecretValue.secretsManager('my-github-token'),
  }),
  basicAuth: amplify.BasicAuth.fromGeneratedPassword('username'),
});

Example not in your language?

Basic auth can be added to specific branches:

declare const amplifyApp: amplify.App;
amplifyApp.addBranch('feature/next', {
  basicAuth: amplify.BasicAuth.fromGeneratedPassword('username'),
});

Example not in your language?

Automatically creating and deleting branches

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

const amplifyApp = new amplify.App(this, 'MyApp', {
  sourceCodeProvider: new amplify.GitHubSourceCodeProvider({
    owner: '<user>',
    repository: '<repo>',
    oauthToken: SecretValue.secretsManager('my-github-token'),
  }),
  autoBranchCreation: { // Automatically connect branches that match a pattern set
    patterns: ['feature/*', 'test/*'],
  },
  autoBranchDeletion: true, // Automatically disconnect a branch when you delete a branch from your repository
});

Example not in your language?

Adding custom response headers

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

const amplifyApp = new amplify.App(this, 'App', {
  sourceCodeProvider: new amplify.GitHubSourceCodeProvider({
    owner: '<user>',
    repository: '<repo>',
    oauthToken: SecretValue.secretsManager('my-github-token'),
  }),
  customResponseHeaders: [
    {
      pattern: '*.json',
      headers: {
        'custom-header-name-1': 'custom-header-value-1',
        'custom-header-name-2': 'custom-header-value-2',
      },
    },
    {
      pattern: '/path/*',
      headers: {
        'custom-header-name-1': 'custom-header-value-2',
      },
    },
  ],
});

Example not in your language?

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:

import * as assets from 'aws-cdk-lib/aws-s3-assets';

declare const asset: assets.Asset;
declare const amplifyApp: amplify.App;
const branch = amplifyApp.addBranch("dev", { asset: asset });

Example not in your language?