# Configuring the build settings for an Amplify application
<a name="build-settings"></a>

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
<a name="yml-specification-syntax"></a>

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
<a name="build-yaml-syntax"></a>

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
<a name="edit-build-settings"></a>

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
<a name="branch-specific-build-settings"></a>

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
<a name="navigating-to-a-subfolder"></a>

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
<a name="frontend-with-backend"></a>

**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
<a name="setting-the-output-folder"></a>

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
<a name="installing-packages-as-part-of-your-build"></a>

You can use the `npm` or `yarn` commands to install packages during the build.

```
frontend:
  phases:
    build:
      commands:
        - npm install -g <package>
        - <package> deploy
        - yarn run build
  artifacts:
    baseDirectory: public
```

## Using a private npm registry
<a name="using-a-private-npm-registry"></a>

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 <key> <value>
        - 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
<a name="installing-os-packages"></a>

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 <package>
```

## Setting key-value storage for every build
<a name="key-value-storage-for-every-build"></a>

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 <key> <value>
envCache --get <key>
```

## Skipping the build for a commit
<a name="skip-build-for-a-commit"></a>

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
<a name="disable-automatic-builds"></a>

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
<a name="enable-diff-deploy"></a>

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
<a name="enable-diff-backend"></a>

**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
<a name="monorepo-configuration"></a>

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
<a name="monorepo-yml-syntax"></a>

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
<a name="monorepo-build-yaml-syntax"></a>

```
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
<a name="setting-monorepo-environment-variable"></a>

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
<a name="setting-monorepo-environmnet-variable-automatically"></a>

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
<a name="setting-monorepo-environment-variable-manually"></a>

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
<a name="turborepo-pnpm-monorepo-configuration"></a>

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
```