Configurar as definições de compilação

Quando você implanta um aplicativo com o Amplify Hosting, ele detecta automaticamente a estrutura de front-end e as configurações de compilação associadas, inspecionando o arquivo package.json em seu repositório. Você tem as seguintes opções para armazenar as configurações de compilação do seu aplicativo:

• Salvar as configurações de compilação no console do Amplify – O console do Amplify detecta automaticamente configurações de compilação e as salva para que possam ser acessadas por meio do console do Amplify. O Amplify aplica essas configurações a todas as suas ramificações, a menos que um arquivo amplify.yml seja encontrado em seu repositório.

• Salvar as configurações de compilação no repositório – Faça download do arquivo amplify.yml e adicione-o à raiz do repositório.

Você pode editar as configurações de criação de um aplicativo no console do Amplify escolhendo Hospedagem e, em seguida, Configurações de criação no painel de navegação. As configurações são aplicadas a todas as ramificações do aplicativo, exceto às ramificações que têm um arquivo amplify.yml salvo no repositório.

nota

As configurações de compilação ficam visíveis no menu Hospedagem do console do Amplify somente quando um aplicativo é configurado para implantação contínua e conectado a um repositório git. Para obter instruções sobre esse tipo de implantação, consulte Introdução.

Comandos e configurações de especificação de compilação

O YAML de especificação de compilação contém uma coleção de comandos de compilação e configurações relacionadas que o Amplify usa para executar a compilação. A lista a seguir descreve essas configurações e como elas são usadas.

versão

O número da versão YAML do Amplify.

appRoot

O caminho dentro do repositório em que esse aplicativo reside em. Ignorado, a menos que vários aplicativos sejam definidos.

env

Adicione variáveis de ambiente a essa seção. Também é possível adicionar variáveis de ambiente usando o console.

back-end

Execute comandos da Amplify CLI para provisionar um back-end, atualizar funções do Lambda ou esquemas do GraphQL como parte da implantação contínua.

front-end

Executa comandos de compilação de front-end.

teste

Execute comandos durante uma fase de teste. Saiba como adicionar testes ao seu aplicativo.

fases da compilação

O front-end, o back-end e o teste têm três fases que representam os comandos executados durante cada sequência da compilação.

• preBuild – O script preBuild é executado antes que a compilação em si seja iniciada, mas depois que o Amplify instala as dependências.

• build (criação) – Seus comandos de criação.

• postBuild – O script pós-compilação é executado depois que a compilação tiver sido concluída e o Amplify copiou todos os artefatos necessários para o diretório de saída.

buildpath

O caminho a ser usado para executar a compilação. O Amplify usa esse caminho para localizar seus artefatos de compilação. Se você não especificar um caminho, o Amplify usa a raiz do aplicativo monorepo, por exemplo apps/app.

artifacts>base-directory

O diretório no qual os artefatos de compilação existem.

artifacts>files

Especifique os arquivos dos artefatos que você deseja implantar. Digite **/* para incluir todos os arquivos.

cache

O campo cache do buildspec é usado para armazenar em cache dependências de tempo de construção, como a pasta node_modules, e é sugerido automaticamente com base no gerenciador de pacotes e na estrutura em que o aplicativo do cliente está incorporado. Durante a primeira compilação, todos os caminhos aqui são armazenados em cache e, nas compilações subsequentes, reinflamos o cache e usamos essas dependências em cache sempre que possível para acelerar o tempo de construção.

O exemplo de especificação de compilação a seguir demonstra a sintaxe básica do YAML:

Sintaxe YAML de especificação de compilação

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
        - path
test:
  phases:
    preTest:
      commands:
        - *enter command*
    test:
      commands:
        - *enter command*
    postTest:
      commands:
        - *enter command*
  artifacts:
    files:
        - location
        - location
    configFilePath: *location*
    baseDirectory: *location*

Configurações de compilação específicas de ramificação

É possível usar o script shell bash para definir configurações de compilação específicas de ramificação. Por exemplo, o script a seguir usa a variável de ambiente do sistema $AWS_BRANCH para executar um conjunto de comandos se o nome da ramificação for principal e um conjunto diferente de comandos se o nome da ramificação for dev.

frontend:
  phases:
    build:
      commands:
        - if [ "${AWS_BRANCH}" = "main" ]; then echo "main branch"; fi
        - if [ "${AWS_BRANCH}" = "dev" ]; then echo "dev branch"; fi

Navegar para uma subpasta

Para monorepos, os usuários desejam poder fazer cd em uma pasta para executar a compilação. Depois de executar o comando cd, ele será aplicado a todos os estágios da compilação. Assim, não será necessário repetir o comando em fases separadas.

version: 1
env:
  variables:
    key: value
frontend:
  phases:
    preBuild:
      commands:
        - cd react-app
        - npm ci
    build:
      commands:
        - npm run build

Implantando o back-end com o front-end para um aplicativo de primeira geração

nota

Esta seção se aplica somente aos aplicativos Amplify Gen 1. Um back-end de primeira geração é criado usando o Amplify Studio e a interface de linha de comando (CLI) do Amplify.

O comando amplifyPush é um script auxiliar que ajuda com as implantações de back-end. As configurações de compilação abaixo determinam automaticamente o ambiente de back-end correto a ser implantado para a ramificação atual.

version: 1
env:
  variables:
    key: value
backend:
  phases:
    build:
      commands:
        - amplifyPush --simple

Definir a pasta de saída

As configurações de criação a seguir definem o diretório de saída como a pasta pública.

frontend:
  phases:
    commands:
      build:
        - yarn run build
  artifacts:
    baseDirectory: public

Instalar pacotes como parte da compilação

É possível usar os comandos npm ou yarn para instalar pacotes durante a compilação.

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

Usar um registro privado de npm

É possível adicionar referências a um registro privado nas configurações de criação ou adicioná-lo como uma variável de ambiente.

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 [e-mail]
        - yarn install

Instalar pacotes do SO

A imagem AL2023 do Amplify executa seu código com um nome de usuário sem privilégios. amplify O Amplify concede a esse usuário privilégios para executar comandos do sistema operacional usando o comando Linux. sudo Se quiser instalar pacotes de sistema operacional para dependências ausentes, você pode usar comandos como yum e rpm withsudo.

O exemplo de seção de compilação a seguir demonstra a sintaxe para instalar um pacote de sistema operacional usando o sudo comando.

build:
  phases:
    preBuild:
      commands:
        - sudo yum install -y <package>

Armazenamento de chave-valor para cada compilação

O envCache fornece armazenamento de chave-valor no momento da compilação. Os valores armazenados no envCache só podem ser modificados durante uma compilação e podem ser reutilizados na próxima compilação. Com o envCache, é possível armazenar informações sobre o ambiente implantado e disponibilizá-lo para o contêiner de compilação em criações sucessivas. Ao contrário dos valores armazenados no envCache, as alterações nas variáveis do ambiente durante uma compilação não são mantidas para compilações futuras.

Exemplo de uso:

envCache --set <key> <value>
envCache --get <key>

Ignorar a compilação para um commit

Para pular uma compilação automática em um determinado commit, inclua o texto [skip-cd] no final da mensagem do commit.

Desativar compilações automáticas

É possível configurar o Amplify para desabilitar compilações automáticas em cada confirmação de código. Para configurar, escolha Configurações do aplicativo, Configurações de ramificação e, em seguida, localize a seção Ramificações que lista as ramificações conectadas. Selecione uma ramificação e, em seguida, escolha Ações, Desativar criação automática. Novos commits nessa ramificação não iniciarão mais uma nova compilação.

Ativar ou desativar a compilação e implantação de front-end com base em diff

É possível configurar o Amplify para usar compilações de front-end baseadas em diff. Se ativado, no início de cada compilação, o Amplify tenta executar um diff na sua pasta appRoot ou na pasta /src/ por padrão. Se o Amplify não encontrar nenhuma diferença, ele ignora as etapas de compilação, teste (se configurado) e implantação do front-end e não atualiza seu aplicativo hospedado.

Para configurar o front-end baseado em diff, criar e implantar

1. Faça login AWS Management Console e abra o console do Amplify.

2. Escolha o aplicativo para o qual configurar a compilação e implantação de front-end com base em diff.

3. No painel de navegação, escolha Hospedagem, Variáveis de ambiente.

4. Na seção Variáveis de ambiente, escolha Gerenciar variáveis.

5. O procedimento para configurar a variável de ambiente varia dependendo se você está habilitando ou desabilitando a compilação e implantação de front-end com base em diff.

   • Para habilitar a compilação e implantação de front-end baseado em diff

     1. Na seção Gerenciar variáveis, em Variável, insira AMPLIFY_DIFF_DEPLOY.

     2. Em Valor, insira true.

   • Para desabilitar a compilação e implantação de front-end baseado em diff

     1. Execute um destes procedimentos:

        • Na seção Gerenciar variáveis, localize AMPLIFY_DIFF_DEPLOY. Em Valor, insira false.

        • Remova a variável de ambiente AMPLIFY_DIFF_DEPLOY.

6. Escolha Salvar.

Opcionalmente, é possível definir a variável de ambiente AMPLIFY_DIFF_DEPLOY_ROOT para substituir o caminho padrão por um caminho relativo à raiz do seu repositório, como dist.

Ativar ou desativar compilações de back-end baseadas em diferenças para um aplicativo de primeira geração

nota

Esta seção se aplica somente aos aplicativos Amplify Gen 1. Um back-end de primeira geração é criado usando o Amplify Studio e a interface de linha de comando (CLI) do Amplify.

É possível configurar o Amplify Hosting para usar compilações de back-end baseadas em diff usando a variável de ambiente AMPLIFY_DIFF_BACKEND. Quando você habilita compilações de back-end baseadas em diff, no início de cada compilação, o Amplify tenta executar uma comparação na pasta em seu repositório amplify. Se o Amplify não encontrar nenhuma diferença, ele pula a etapa de compilação do back-end e não atualiza seus atributos de back-end. Se seu projeto não tiver uma pasta amplify no seu repositório, o Amplify ignorará o valor da variável de ambiente AMPLIFY_DIFF_BACKEND.

Se você atualmente tem comandos personalizados especificados nas configurações de compilação da sua fase de back-end, as compilações condicionais de back-end não funcionarão. Se quiser que esses comandos personalizados sejam executados, você deve movê-los para a fase de front-end das configurações de compilação no arquivo amplify.yml do seu aplicativo.

Para configurar compilações de back-end baseadas em diff

1. Faça login AWS Management Console e abra o console do Amplify.

2. Escolha o aplicativo para o qual configurar as compilações de back-end baseadas em diff.

3. No painel de navegação, escolha Hospedagem, Variáveis de ambiente.

4. Na seção Variáveis de ambiente, escolha Gerenciar variáveis.

5. O procedimento para configurar a variável de ambiente varia dependendo se você está habilitando ou desabilitando compilações de back-end baseadas em diff.

   • Para habilitar compilações de back-end baseadas em diff

     1. Na seção Gerenciar variáveis, em Variável, insira AMPLIFY_DIFF_BACKEND.

     2. Em Valor, insira true.

   • Para desativar as compilações de back-end baseadas em diff

     1. Execute um destes procedimentos:

        • Na seção Gerenciar variáveis, localize AMPLIFY_DIFF_BACKEND. Em Valor, insira false.

        • Remova a variável de ambiente AMPLIFY_DIFF_BACKEND.

6. Escolha Salvar.