# Managing the build configuration for an Amplify application You can customize the build settings and configuration for your Amplify deployments. When you deploy an application, Amplify automatically detects the frontend framework and the associated build settings. You can customize the build settings in the application's build specification (buildspec) to add environment variables, run build commands, and specify build dependencies. Amplify's default build image comes with several packages and dependencies pre-installed, but you can also use the live package updates feature to specify either a specific version, or ensure that the latest version is always installed. If you have specific dependencies that take a long time to install during a build using Amplify's default container, you can create your own custom build image. You can also customize the build instance size to provide your application deployment with the CPU, memory, and disk space resources it needs. Builds are initiated automatically with each commit to your Git repository and with each new deployment. You can set up the incoming webhooks feature to initiate a build without a commit to your Git repository. The build notifications feature allows you to share information with team members about build successes and failures. **Topics** + [Configuring the build settings for an Amplify application](build-settings.md) + [Customizing the build image](custom-build-image.md) + [Configuring the build instance for an Amplify application](custom-build-instance.md) + [Creating an incoming webhook to start a build](create-incoming-webhook.md) + [Setting up email notifications for builds](notifications.md) # Configuring the build settings for an Amplify application When you deploy an application, Amplify automatically detects the frontend framework and associated build settings by inspecting the app's `package.json` file in your Git repository. You have the following options for storing your app's build settings: + Save the build settings in the Amplify console - The Amplify console autodetects build settings and saves them so that they can be accessed by the Amplify console. Amplify applies these settings to all of your branches unless there is an `amplify.yml` file stored in your repository. + Save the build settings in your repository - Download the `amplify.yml` file and add it to the root of your repository. **Note** **Build settings** is visible in the Amplify console's **Hosting** menu only when an app is set up for continuous deployment and connected to a git repository. For instructions on this type of deployment, see [Getting started](getting-started.md). # Build specification reference The build specification (buildspec) for an Amplify application is a collection of YAML settings and build commands that Amplify uses to run your build. The following list describes these settings and how they are used. **version** The Amplify YAML version number. **appRoot** The path within the repository that this application resides in. *Ignored unless multiple applications are defined.* **env** Add environment variables to this section. You can also add environment variables using the console. **backend** Run Amplify CLI commands to provision a backend, update Lambda functions, or GraphQL schemas as part of continuous deployment. **frontend** Run frontend build commands. **test** Run commands during a test phase. Learn how to [add tests to your app](running-tests.md). **build phases** The frontend, backend, and test have three *phases* that represent the commands run during each sequence of the build. + **preBuild** - The preBuild script runs before the actual build starts, but after Amplify installs dependencies. + **build** - Your build commands. + **postBuild** - The post-build script runs after the build has finished and Amplify has copied all the necessary artifacts to the output directory. **buildpath** The path to use to run the build. Amplify uses this path to locate your build artifacts. If you don't specify a path, Amplify uses the monorepo app root, for example `apps/app`. **artifacts>base-directory** The directory in which your build artifacts exist. **artifacts>files** Specify files from your artifacts you want to deploy. Enter `**/*` to include all files. **cache** Specifies build-time dependencies such as the *node\$1modules* folder. During the first build, paths provided here are cached. On subsequent builds, Amplify restores the cache to the same paths before it runs your commands. Amplify considers all provided cache paths to be relative to your project root. However, Amplify doesn't allow traversing outside of the project root. For example, if you specify an absolute path, the build will succeed without an error, but the path won't be cached. ## Build specification YAML syntax reference The following example of a build specification demonstrates the basic YAML syntax. ``` version: 1 env: variables: key: value backend: phases: preBuild: commands: - *enter command* build: commands: - *enter command* postBuild: commands: - *enter command* frontend: buildpath: phases: preBuild: commands: - cd react-app - npm ci build: commands: - npm run build artifacts: files: - location - location discard-paths: yes baseDirectory: location cache: paths: - path # A cache path relative to the project root - path # Traversing outside of the project root is not allowed test: phases: preTest: commands: - *enter command* test: commands: - *enter command* postTest: commands: - *enter command* artifacts: files: - location - location configFilePath: *location* baseDirectory: *location* ``` # Editing the build specification You can customize an application's build settings by editing the build specification (buildspec) in the Amplify console. The build settings are applied to all the branches in your app, except for the branches that have an `amplify.yml` file saved in the Git repository. **To edit build settings in the Amplify console** 1. Sign in to the AWS Management Console and open the [Amplify console](https://console.aws.amazon.com/amplify/). 1. Choose the app that you want to edit the build settings for. 1. In the navigation pane, choose **Hosting**, then choose **Build settings**. 1. On the **Build settings** page, in the **App build specification** section, choose **Edit**. 1. In the **Edit build spec** window, enter your updates. 1. Choose **Save**. You can use the examples described in the following topics to update your build settings for specific scenarios. **Topics** + [Setting branch-specific build settings with scripting](#branch-specific-build-settings) + [Setting a command to navigate to a subfolder](#navigating-to-a-subfolder) + [Deploying the backend with the front end for a Gen 1 app](#frontend-with-backend) + [Setting the output folder](#setting-the-output-folder) + [Installing packages as part of a build](#installing-packages-as-part-of-your-build) + [Using a private npm registry](#using-a-private-npm-registry) + [Installing OS packages](#installing-os-packages) + [Setting key-value storage for every build](#key-value-storage-for-every-build) + [Skipping the build for a commit](#skip-build-for-a-commit) + [Turning off automatic builds on every commit](#disable-automatic-builds) + [Configuring diff based frontend build and deploy](#enable-diff-deploy) + [Configuring diff based backend builds for a Gen 1 app](#enable-diff-backend) ## Setting branch-specific build settings with scripting You can use bash shell scripting to set branch-specific build settings. For example, the following script uses the system environment variable *\$1AWS\$1BRANCH* to run one set of commands if the branch name is *main* and a different set of commands if the branch name is *dev*. ``` frontend: phases: build: commands: - if [ "${AWS_BRANCH}" = "main" ]; then echo "main branch"; fi - if [ "${AWS_BRANCH}" = "dev" ]; then echo "dev branch"; fi ``` ## Setting a command to navigate to a subfolder For monorepos, users want to be able to `cd` into a folder to run the build. After you run the `cd` command, it applies to all stages of your build so you don’t need to repeat the command in separate phases. ``` version: 1 env: variables: key: value frontend: phases: preBuild: commands: - cd react-app - npm ci build: commands: - npm run build ``` ## Deploying the backend with the front end for a Gen 1 app **Note** This section applies to Amplify Gen 1 applications only. A Gen 1 backend is created using Amplify Studio and the Amplify command line interface (CLI). The `amplifyPush` command is a helper script that helps you with backend deployments. The build settings below automatically determine the correct backend environment to deploy for the current branch. ``` version: 1 env: variables: key: value backend: phases: build: commands: - amplifyPush --simple ``` ## Setting the output folder The following build settings set the output directory to the public folder. ``` frontend: phases: commands: build: - yarn run build artifacts: baseDirectory: public ``` ## Installing packages as part of a build You can use the `npm` or `yarn` commands to install packages during the build. ``` frontend: phases: build: commands: - npm install -g - deploy - yarn run build artifacts: baseDirectory: public ``` ## Using a private npm registry You can add references to a private registry in your build settings or add it as an environment variable. ``` build: phases: preBuild: commands: - npm config set - npm config set registry https://registry.npmjs.org - npm config set always-auth true - npm config set email hello@amplifyapp.com - yarn install ``` ## Installing OS packages Amplify's AL2023 image runs your code with a non-privileged user named `amplify`. Amplify grants this user privileges to run OS commands using the Linux `sudo` command. If you want to install OS packages for missing dependencies, you can use commands such as `yum` and `rpm` with `sudo`. The following example build section demonstrates the syntax for installing an OS package using the `sudo` command. ``` build: phases: preBuild: commands: - sudo yum install -y ``` ## Setting key-value storage for every build The `envCache` provides key-value storage at build time. Values stored in the `envCache` can only be modified during a build and can be re-used at the next build. Using the `envCache`, we can store information on the deployed environment and make it available to the build container in successive builds. Unlike values stored in the `envCache`, changes to environment variables during a build are not persisted to future builds. Example usage: ``` envCache --set envCache --get ``` ## Skipping the build for a commit To skip an automatic build on a particular commit, include the text **[skip-cd]** at the end of the commit message. ## Turning off automatic builds on every commit You can configure Amplify to turn off automatic builds on every code commit. To set up, choose **App settings**, **Branch settings**, and then locate the **Branches** section that lists the connected branches. Select a branch, and then choose **Actions**, **Disable auto build**. New commits to that branch will no longer start a new build. ## Configuring diff based frontend build and deploy You can configure Amplify to use diff based frontend builds. If enabled, at the start of each build Amplify attempts to run a diff on either your `appRoot`, or the `/src/` folder by default. If Amplify doesn't find any differences, it skips the frontend build, test (if configured), and deploy steps, and does not update your hosted app. **To configure diff based frontend build and deploy** 1. Sign in to the AWS Management Console and open the [Amplify console](https://console.aws.amazon.com/amplify/). 1. Choose the app to configure diff based frontend build and deploy for. 1. In the navigation pane, choose **Hosting**, **Environment variables**. 1. In the **Environment variables** section, choose **Manage variables**. 1. The procedure for configuring the environment variable varies depending on whether you are enabling or disabling diff based frontend build and deploy. + To enable diff based frontend build and deploy 1. In the **Manage variables** section, under **Variable**, enter `AMPLIFY_DIFF_DEPLOY`. 1. For **Value**, enter `true`. + To disable diff based frontend build and deploy 1. Do one of the following: + In the **Manage variables** section, locate `AMPLIFY_DIFF_DEPLOY`. For **Value**, enter `false`. + Remove the `AMPLIFY_DIFF_DEPLOY` environment variable. 1. Choose **Save**. Optionally, you can set the `AMPLIFY_DIFF_DEPLOY_ROOT` environment variable to override the default path with a path relative to the root of your repo, such as `dist`. ## Configuring diff based backend builds for a Gen 1 app **Note** This section applies to Amplify Gen 1 applications only. A Gen 1 backend is created using Amplify Studio and the Amplify command line interface (CLI). You can configure Amplify Hosting to use diff based backend builds using the `AMPLIFY_DIFF_BACKEND` environment variable. When you enable diff based backend builds, at the start of each build Amplify attempts to run a diff on the `amplify` folder in your repository. If Amplify doesn't find any differences, it skips the backend build step, and doesn't update your backend resources. If your project doesn't have an `amplify` folder in your repository, Amplify ignores the value of the `AMPLIFY_DIFF_BACKEND` environment variable. If you currently have custom commands specified in the build settings of your backend phase, conditional backend builds won't work. If you want those custom commands to run, you must move them to the frontend phase of your build settings in your app's `amplify.yml` file. **To configure diff based backend builds** 1. Sign in to the AWS Management Console and open the [Amplify console](https://console.aws.amazon.com/amplify/). 1. Choose the app to configure diff based backend builds for. 1. In the navigation pane, choose **Hosting**, **Environment variables**. 1. In the **Environment variables** section, choose **Manage variables**. 1. The procedure for configuring the environment variable varies depending on whether you are enabling or disabling diff based backend builds. + To enable diff based backend builds 1. In the **Manage variables** section, under **Variable**, enter `AMPLIFY_DIFF_BACKEND`. 1. For **Value**, enter `true`. + To disable diff based backend builds 1. Do one of the following: + In the **Manage variables** section, locate `AMPLIFY_DIFF_BACKEND`. For **Value**, enter `false`. + Remove the `AMPLIFY_DIFF_BACKEND` environment variable. 1. Choose **Save**. # Configuring monorepo build settings When you store multiple projects or microservices in a single repository, it is called a monorepo. You can use Amplify Hosting to deploy applications in a monorepo without creating multiple build configurations or branch configurations. Amplify supports apps in generic monorepos as well as apps in monorepos created using npm workspace, pnpm workspace, Yarn workspace, Nx, and Turborepo. When you deploy your app, Amplify automatically detects the monorepo build tool that you are using. Amplify automatically applies build settings for apps in an npm workspace, Yarn workspace or Nx. Turborepo and pnpm apps require additional configuration. For more information, see [Configuring Turborepo and pnpm monorepo apps](#turborepo-pnpm-monorepo-configuration). You can save the build settings for a monorepo in the Amplify console or you can download the `amplify.yml` file and add it to the root of your repository. Amplify applies the settings saved in the console to all of your branches unless it finds an `amplify.yml` file in your repository. When an `amplify.yml` file is present, its settings override any build settings saved in the Amplify console. ## Monorepo build specification YAML syntax reference The YAML syntax for a monorepo build specification differs from the YAML syntax for a repo that contains a single application. For a monorepo, you declare each project in a list of applications. You must provide the following additional `appRoot` key for each application you declare in your monorepo build specification: **appRoot** The root, within the repository, that the application starts in. This key must exist, and have the same value as the `AMPLIFY_MONOREPO_APP_ROOT` environment variable. For instructions on setting this environment variable, see [Setting the AMPLIFY\$1MONOREPO\$1APP\$1ROOT environment variable](#setting-monorepo-environment-variable). The following monorepo build specification example demonstrates how to declare multiple Amplify applications in the same repo. The two apps, `react-app`, and `angular-app` are declared in the `applications` list. The `appRoot` key for each app indicates that the app is located in the `apps` root folder in the repo. The `buildpath` attribute is set to `/` to run and build the app from the monorepo project root. The `baseDirectory` attribute is the relative path of `buildpath`. ### Monorepo build specification YAML syntax ``` version: 1 applications: - appRoot: apps/react-app env: variables: key: value backend: phases: preBuild: commands: - *enter command* build: commands: - *enter command* postBuild: commands: - *enter command* frontend: buildPath: / # Run install and build from the monorepo project root phases: preBuild: commands: - *enter command* - *enter command* build: commands: - *enter command* artifacts: files: - location - location discard-paths: yes baseDirectory: location cache: paths: - path - path test: phases: preTest: commands: - *enter command* test: commands: - *enter command* postTest: commands: - *enter command* artifacts: files: - location - location configFilePath: *location* baseDirectory: *location* - appRoot: apps/angular-app env: variables: key: value backend: phases: preBuild: commands: - *enter command* build: commands: - *enter command* postBuild: commands: - *enter command* frontend: phases: preBuild: commands: - *enter command* - *enter command* build: commands: - *enter command* artifacts: files: - location - location discard-paths: yes baseDirectory: location cache: paths: - path - path test: phases: preTest: commands: - *enter command* test: commands: - *enter command* postTest: commands: - *enter command* artifacts: files: - location - location configFilePath: *location* baseDirectory: *location* ``` An app using the following example build specification, will be built under the project root and the build artifacts will be located at `/packages/nextjs-app/.next`. ``` applications: - frontend: buildPath: '/' # run install and build from monorepo project root phases: preBuild: commands: - npm install build: commands: - npm run build --workspace=nextjs-app artifacts: baseDirectory: packages/nextjs-app/.next files: - '**/*' cache: paths: - node_modules/**/* appRoot: packages/nextjs-app ``` ## Setting the AMPLIFY\$1MONOREPO\$1APP\$1ROOT environment variable When you deploy an app stored in a monorepo, the app's `AMPLIFY_MONOREPO_APP_ROOT` environment variable must have the same value as the path of the app root, relative to the root of your repository. For example, a monorepo named `ExampleMonorepo` with a root folder named `apps`, that contains, `app1`, `app2`, and `app3` has the following directory structure: ``` ExampleMonorepo apps app1 app2 app3 ``` In this example, the value of the `AMPLIFY_MONOREPO_APP_ROOT` environment variable for `app1` is `apps/app1`. When you deploy a monorepo app using the Amplify console, the console automatically sets the `AMPLIFY_MONOREPO_APP_ROOT` environment variable using the value that you specify for the path to the app's root. However, if your monorepo app already exists in Amplify or is deployed using AWS CloudFormation, you must manually set the `AMPLIFY_MONOREPO_APP_ROOT` environment variable in the **Environment variables** section in the Amplify console. ### Setting the AMPLIFY\$1MONOREPO\$1APP\$1ROOT environment variable automatically during deployment The following instructions demonstrate how to deploy a monorepo app with the Amplify console. Amplify automatically sets the `AMPLIFY_MONOREPO_APP_ROOT` environment variable using the app's root folder that you specify in the console. **To deploy a monorepo app with the Amplify console** 1. Sign in to the AWS Management Console and open the [Amplify console](https://console.aws.amazon.com/amplify/). 1. Choose **Create new app** in the upper right corner. 1. On the **Start building with Amplify** page, choose your Git provider, then choose **Next**. 1. On the **Add repository branch** page, do the following: 1. Choose the name of your repository from the list. 1. Choose the name of the branch to use. 1. Select **My app is a monorepo** 1. Enter the path to your app in your monorepo, for example, **apps/app1**. 1. Choose **Next**. 1. On the **App settings** page, you can use the default settings or customize the build settings for your app. In the **Environment variables** section, Amplify sets `AMPLIFY_MONOREPO_APP_ROOT` to the path you specified in step 4d. 1. Choose **Next**. 1. On the **Review** page, choose **Save and deploy**. ### Setting the AMPLIFY\$1MONOREPO\$1APP\$1ROOT environment variable for an existing app Use the following instructions to manually set the `AMPLIFY_MONOREPO_APP_ROOT` environment variable for an app that is already deployed to Amplify, or has been created using CloudFormation. **To set the AMPLIFY\$1MONOREPO\$1APP\$1ROOT environment variable for an existing app** 1. Sign in to the AWS Management Console and open the [Amplify console](https://console.aws.amazon.com/amplify/). 1. Choose the name of the app to set the environment variable for. 1. In the navigation pane, choose **Hosting**, and then choose **Environment variables**. 1. On the **Environment variables** page, choose **Manage variables**. 1. In the **Manage variables** section, do the following: 1. Choose **Add new**. 1. For **Variable**, enter the key `AMPLIFY_MONOREPO_APP_ROOT`. 1. For **Value**, enter the path to the app, for example **apps/app1**. 1. For **Branch**, by default Amplify applies the environment variable to all branches. 1. Choose **Save**. ## Configuring Turborepo and pnpm monorepo apps The Turborepo and pnpm workspace monorepo build tools get configuration information from `.npmrc` files. When you deploy a monorepo app created with one of these tools, you must have an `.npmrc` file in your project root directory. In the `.npmrc` file, set the linker for installing Node packages to `hoisted`. You can copy the following line to your file. ``` node-linker=hoisted ``` For more information about `.npmrc` files and settings, see [pnpm .npmrc](https://pnpm.io/next/npmrc) in the *pnpm documentation*. Pnpm is not included in the Amplify default build container. For pnpm workspace and Turborepo apps, you must add a command to install pnpm in the `preBuild` phase of your app's build settings. The following example excerpt from a build specification shows a `preBuild` phase with a command to install pnpm. ``` version: 1 applications: - frontend: phases: preBuild: commands: - npm install -g pnpm ``` # Customizing the build image You can use a custom build image to provide a customized build environment for an Amplify app. If you have specific dependencies that take a long time to install during a build using Amplify's default container, you can create your own Docker image and reference it during a build. Images can be hosted on Amazon Elastic Container Registry Public. For a custom build image to work as an Amplify build image, it must meet the following requirements. **Custom build image requirements** 1. A Linux distribution that supports the GNU C Library (glibc), such as Amazon Linux, compiled for the x86-64 architecture. 1. **cURL**: When we launch your custom image, we download our build runner into your container, and therefore we require cURL to be present. If this dependency is missing, the build instantly fails without any output as our build-runner is unable to produce any output. 1. **Git**: In order to clone your Git repository we require Git to be installed in the image. If this dependency is missing, the **Cloning repository** step will fail. 1. **OpenSSH**: In order to securely clone your repository we require OpenSSH to set up the SSH key temporarily during the build. The OpenSSH package provides the commands that the build runner requires to do this. 1. **Bash and The Bourne Shell**: These two utilities are used to run commands at build time. If they aren't installed, your builds might fail prior to starting. 1. **Node.JS\$1NPM**: Our build runner doesn't install Node. Instead, it relies on Node and NPM being installed in the image. This is only required for builds that require NPM packages or Node specific commands. However, we strongly recommend installing them because when they are present, the Amplify build runner can use these tools to improve the build execution. Amplify's package override feature uses NPM to install the Hugo-extended package when you set an override for Hugo. The following packages aren't required, but we strongly recommend that you install them. 1. **NVM (Node Version Manager)**: We recommend that you install this version manager if you need to handle different versions of Node. When you set an override, Amplify’s package override feature uses NVM to change Node.js versions before each build. 1. **Wget**: Amplify can use the Wget utility to download files during the build process. We recommend that you install it in your custom image. 1. **Tar**: Amplify can use the Tar utility to uncompress downloaded files during the build process. We recommend that you install it in your custom image. ## Configuring a custom build image for an app Use the following procedure to configure a custom build image for an application in the Amplify console. **To configure a custom build image hosted in Amazon ECR** 1. See [Getting started](https://docs.aws.amazon.com/AmazonECR/latest/public/public-getting-started.html) in the *Amazon ECR Public User guide* to set up an Amazon ECR Public repository with a Docker image. 1. Sign in to the AWS Management Console and open the [Amplify console](https://console.aws.amazon.com/amplify/). 1. Choose the app that you want to configure a custom build image for. 1. In the navigation pane, choose **Hosting**, **Build settings**. 1. On the **Build settings** page, in the **Build image settings** section, choose **Edit**. 1. On the **Edit build image settings** page, expand the **Build image** menu, and choose **Custom Build Image**. 1. Enter the name of the Amazon ECR Public repo that you created in step one. This is where your build image is hosted. For example, if the name of your repo is *ecr-examplerepo*, you would enter **public.ecr.aws/xxxxxxxx/ecr-examplerepo**. 1. Choose **Save**. ## Using specific package and dependency versions in the build image Live package updates enable you to specify the versions of packages and dependencies to use in the Amplify default build image. The default build image comes with several packages and dependencies pre-installed (e.g. Hugo, Amplify CLI, Yarn, etc). With live package updates you can override the version of these dependencies and specify either a specific version, or ensure that the latest version is always installed. If live package updates is enabled, before your build runs, the build runner first updates (or downgrades) the specified dependencies. This increases the build time proportional to the time it takes to update the dependencies, but the benefit is that you can ensure the same version of a dependency is used to build your app. **Warning** Setting the Node.js version to **latest** causes builds to fail. Instead, you must specify an exact Node.js version, such as `18`, `21.5`, or `v0.1.2`. **To configure live package updates** 1. Sign in to the AWS Management Console and open the [Amplify console](https://console.aws.amazon.com/amplify/). 1. Choose the app that you want to configure live package updates for. 1. In the navigation pane, choose **Hosting**, **Build settings**. 1. On the **Build settings** page, in the **Build image settings** section, choose **Edit**. 1. On the **Edit build image settings** page, **Live package updates** list, choose **Add new**. 1. For **Package**, select the dependency to override. 1. For **Version**, either keep the default **latest** or enter a specific version of the dependency. If you use **latest**, the dependency will always be upgraded to the latest version available. 1. Choose **Save**. # Configuring the build instance for an Amplify application Amplify Hosting offers configurable build instance sizes that enable you to provide your application's build instance with the CPU, memory, and disk space resources that it requires. Prior to the release of this feature, Amplify provided a fixed size build instance configuration of 8 GiB of memory and 4 vCPUs. Amplify supports three build instance types: Standard, Large, and XLarge. If you don't specify an instance type, Amplify uses the default Standard instance. You can configure the build instance type for an application using the Amplify console, the AWS CLI, or the SDKs. The cost for each build instance type is calculated per build minute. For pricing details, see [AWS Amplify Pricing](https://aws.amazon.com/amplify/pricing/). The following table describes the compute specifications for each build instance type: | Build instance type | vCPUs | Memory | Disk space | | --- | --- | --- | --- | | Standard | 4 vCPUs | 8 GiB | 128 GB | | Large | 8 vCPUs | 16 GiB | 128 GB | | XLarge | 36 vCPUs | 72 GiB | 256 GB | **Topics** + [Understanding build instance types](#understanding-build-instance-sizes) + [Configuring the build instance type in the Amplify console](#configure-build-instance-type) + [Configuring an application's heap memory to utilize large instance types](#configuring-heap-memory) ## Understanding build instance types The build instance type setting is configured at the application level and extends to all of the application's branches. The following key details apply to build instance types: + The build instance type that you configure for an application automatically applies to auto-created branches and pull request previews. + The *Concurrent jobs* service quota applies across all build instance types in your AWS account. For example, if your *Concurrent jobs* limit is five, you can run up to a maximum of 5 builds across all instance types in your AWS account. + The cost for each build instance type is calculated per build minute. The build instance allocation process can require additional overhead time before your build starts. For larger instances, especially XLarge, your build might experience latency before the build starts, due to this overhead time. However, you are billed only for the actual build time, not the overhead time. You can configure the build instance type when you create a new application or you can update the instance type on an existing application. For instructions on configuring this setting in the Amplify console, see [Configuring the build instance type in the Amplify console](#configure-build-instance-type). You can also update this setting using the SDKs. For more information, see the [CreateApp](https://docs.aws.amazon.com/amplify/latest/APIReference/API_CreateApp.html), and [UpdateApp](https://docs.aws.amazon.com/amplify/latest/APIReference/API_UpdateApp.html) APIs in the *Amplify API Reference*. If you have existing applications in your account that were created before the release of the customizable build instance type feature, they are using the default Standard instance type. When you update the build instance type for an existing application, any builds that are queued or in progress before your update will utilize the previously configured build instance type. For example, if you have an existing application with the `main` branch deployed to Amplify and you update its build instance type from **Standard** to **Large**, all new builds that you initiate from the `main` branch will use the **Large** build instance type. However, any builds that are in progress at the time that you update the build instance type will continue to run on the **Standard** instance. ## Configuring the build instance type in the Amplify console Use the following procedure to configure the build instance type when you create a new Amplify application. **To configure the build instance type for a new application** 1. Sign in to the AWS Management Console and open the [Amplify console](https://console.aws.amazon.com/amplify/). 1. On the **All apps** page, choose **Create new app**. 1. On the **Start building with Amplify** page, choose your Git repository provider, then choose **Next**. 1. On the **Add repository branch** page, do the following: 1. In the **Recently updated repositories** list, select the name of the repository to connect. 1. In the **Branch** list, select the name of the repository branch to connect. 1. Choose **Next**. 1. On the **App settings** page, open the **Advanced settings** section. 1. For **Build instance type**, choose your desired instance type from the list. 1. If you are deploying a Node.js runtime based application, configure the heap memory size to effectively utilize a large instance type. You can do this on the **App settings** page by either setting an environment variable or updating the build settings. For more information, see [Configuring an application's heap memory to utilize large instance types](#configuring-heap-memory). + Set an environment variable 1. In the **Advanced settings**, **Environment variables** section, choose **Add new**. 1. For **Key** enter **NODE\$1OPTIONS**. 1. For **Value**, enter `--max-old-space-size=memory_size_in_mb`. Replace *memory\$1size\$1in\$1mb* with your desired heap memory size in megabytes. + Update the build settings 1. In the **Build settings** section, choose **Edit YML file**. 1. Add the following command to the `preBuild` phase. Replace *memory\$1size\$1in\$1mb* with your desired heap memory size in megabytes. ``` export NODE_OPTIONS='--max-old-space-size=memory_size_in_mb' ``` 1. Choose **Save**. 1. Choose, **Next**. 1. On the **Review** page, choose **Save and deploy**. Use the following procedure to configure the build instance type for an existing Amplify application. **To configure the build instance type for an existing application** 1. Sign in to the AWS Management Console and open the [Amplify console](https://console.aws.amazon.com/amplify/). 1. Choose the app that you want to configure the build instance type for. 1. In the navigation pane, choose **Hosting**, the choose **Build settings**. 1. On the **Build settings** page, in the **Advanced settings** section, choose **Edit**. 1. On the **Edit settings** page, for **Build instance type**, choose your desired instance type from the list. 1. Choose **Save**. This change will take effect the next time you deploy the application. 1. (Optional) To deploy the updated application immediately, do the following: 1. In the navigation pane, choose **Overview**. 1. On your application's overview page, choose the branch to redeploy. 1. On the **Deployment** page, choose a deployment, such as the most recent deployment. Then, choose **Redeploy this version**. A new deployment will begin. 1. When the deployment completes, the application's build settings will show that the branch is using the updated build instance type. ## Configuring an application's heap memory to utilize large instance types If you are building memory intensive applications, use this section to understand how to configure your application to utilize large instance types. Programming languages and frameworks often rely on allocating dynamic memory, also known as heap memory, during runtime to manage application memory requirements. Heap memory is requested by the runtime environment and allocated by the host operating system. By default, runtime environments enforce a maximum heap size limit available to the application. This means that no additional memory will be available for the application beyond the heap size, even though the host operating system or container has a larger amount of memory available. As an example, the JavaScript Node.js v8 runtime environment enforces a default heap size limit which depends on several factors, including the host memory size. As a result, Standard and Large build instances have a default Node.js heap size of 2096 MB and the XLarge instance has a default heap size of 4144 MB. Therefore, building an application with a 6000 MB memory requirement using the default Node.js heap size on any Amplify build instance type will result in a failed build due to an out-of-memory error. To work around the Node.js default heap size memory limits, you can do one of the following: + Set the `NODE_OPTIONS` environment variable in your Amplify application to the value `--max-old-space-size=memory_size_in_mb`. For `memory_size_in_mb`, specify your desired heap memory size in megabytes. For instructions, see [Setting environment variables](setting-env-vars.md). + Add the following command to the `preBuild` phase in your Amplify application's build specification. ``` export NODE_OPTIONS='--max-old-space-size=memory_size_in_mb' ``` You can update the build specification in the Amplify console or in your application's `amplify.yml` file in your project repository. For instructions, see [Configuring the build settings for an Amplify application](build-settings.md). The following example Amplify build specification sets a Node.js heap memory size to 7000 MB for building a React frontend application: ``` version: 1 frontend: phases: preBuild: commands: # Set the heap size to 7000 MB - export NODE_OPTIONS='--max-old-space-size=7000' # To check the heap size memory limit in MB - node -e "console.log('Total available heap size (MB):', v8.getHeapStatistics().heap_size_limit / 1024 / 1024)" - npm ci --cache .npm --prefer-offline build: commands: - npm run build artifacts: baseDirectory: build files: - '**/*' cache: paths: - .npm/**/* ``` To effectively utilize large instance types, it is important to have a sufficient heap memory size configured. Configuring a small heap size for a memory intensive application will likely result in a build failure. The application's build logs might not directly indicate an out-of-memory error as the application runtime can crash unexpectedly. Configuring a heap size as large as the host memory might result in the host operating system swapping or terminating other processes, and potentially disrupting your build process. As a reference, Node.js recommends setting a maximum heap size of 1536 MB on a machine with approximately 2000 MB of memory to leave some memory for other uses. The optimal heap size depends on your application's needs and resource usage. If you encounter out-of-memory errors, start with a moderate heap size and then gradually increase it as needed. As a guideline, we recommend starting with 6000 MB for a Standard instance type, 12000 MB for a Large instance type, and 60000 MB for an XLarge instance type. # Creating an incoming webhook to start a build Set up an incoming webhook in the Amplify console to start a build without committing code to your Git repository. You can use webhooks with headless CMS tools (such as Contentful or GraphCMS) to start a build whenever content changes, or to perform daily builds using services such as Zapier. **To create an incoming webhook** 1. Sign in to the AWS Management Console and open the [Amplify console](https://console.aws.amazon.com/amplify/). 1. Choose the app that you want to create a webhook for. 1. In the navigation pane, choose **Hosting**, then **Build settings**. 1. On the **Build settings** page, scroll down to the **Incoming webhooks** section and choose **Create webhook**. 1. In the **Create webhook** dialog box, do the following: 1. For **Webhook name** enter a name for the webhook. 1. For **Branch to build**, select the branch to build on incoming webhook requests. 1. Choose **Create webhook**. 1. In the **Incoming webhooks** section, do one of the following: + Copy the webhook URL and provide it to a headless CMS tool or other service to initiate builds. + Run the curl command in a terminal window to start a new build. # Setting up email notifications for builds You can set up email notifications for an AWS Amplify app to alert stakeholders or team members when a build succeeds or fails. Amplify Hosting creates an Amazon Simple Notification Service (SNS) topic in your account and uses it to configure email notifications. Notifications can be configured to apply to all branches or specific branches of an Amplify app. ## Setting up email notifications Use the following procedures to set up email notifications for all branches or specific branches of an Amplify app. **To set up email notifications for an Amplify app** 1. Sign in to the AWS Management Console and open the [Amplify console](https://console.aws.amazon.com/amplify/). 1. Choose the app that you want to set up email notifications for. 1. In the navigation pane, choose **Hosting**, **Build notifications**. On the **Build notifications** page, choose **Manage notifications**. 1. On the **Manage notifications** page, choose **Add new**. 1. Do one of the following: + To send notifications for a single branch, for **Email**, enter the email address to send notifications to. For **Branch**, select the name of the branch to send notifications for. + To send notifications for all connected branches, for **Email**, enter the email address to send notifications to. For **Branch**, choose *All Branches*. 1. Choose **Save**.