As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Suporte do Amplify para Next.js O Amplify oferece suporte à implantação e à hospedagem de aplicações da Web renderizadas do lado do servidor (SSR) criadas usando o Next.js. Next.js é uma estrutura React para desenvolvimento SPAs com JavaScript. É possível implantar aplicações criadas com versões do Next.js até o Next.js 15, com atributos como otimização de imagens e middleware. Os desenvolvedores podem usar o Next.js para combinar geração estática de sites (SSG) e SSR em um único projeto. As páginas SSG são pré-renderizadas no momento da compilação e as páginas SSR são pré-renderizadas no momento da solicitação. A pré-renderização pode melhorar o desempenho e a otimização de mecanismos de pesquisa. Como o Next.js pré-renderiza todas as páginas no servidor, o conteúdo HTML de cada página está pronto quando chega ao navegador do cliente. Esse conteúdo também pode ser carregado mais rápido. Tempos de carregamento mais rápidos melhoram a experiência do usuário final com um site e impactam positivamente a classificação de SEO do site. A pré-renderização também melhora a SEO, permitindo que os bots dos mecanismos de pesquisa encontrem e rastreiem facilmente o conteúdo HTML de um site. O Next.js fornece suporte analítico integrado para medir várias métricas de desempenho, como Tempo até o primeiro byte (TTFB) e Primeira pintura com conteúdo (FCP). Para obter mais informações sobre o Next.js, consulte [Introdução](https://nextjs.org/docs/getting-started) no site do Next.js. ## Suporte ao atributo Next.js A computação do Amplify Hosting gerencia integralmente a renderização do lado do servidor (SSR) para aplicações criadas com versões do Next.js de 12 a 15. Se você implantou uma aplicação de Next.js no Amplify antes do lançamento da computação do Amplify Hosting em novembro de 2022, sua aplicação está usando o provedor de SSR anterior do Amplify, o Classic (somente Next.js 11). A computação do Amplify Hosting não é compatível com aplicativos criados usando o Next.js versão 11 ou anterior. É altamente recomendável que você migre seus aplicativos Next.js 11 para o provedor de SSR gerenciado por computação do Amplify Hosting. A lista a seguir descreve os atributos específicos que o provedor de SSR de computação do Amplify Hosting suporta. **Atributos compatíveis** + Páginas renderizadas do lado do servidor (SSR) + Páginas estáticas + Rotas de API + Rotas dinâmicas + Detecção de todas as rotas + SSG (geração estática) + Regeneração estática incremental (ISR) + Roteamento de subcaminhos internacionalizado (i18n) + Roteamento de domínio internacionalizado (i18n) + Detecção automática de localidade internacionalizada (i18n) + Middleware + Variáveis de ambiente + Otimização de imagem + Diretório de aplicativos Next.js 13 **Atributos não compatíveis** + Rotas de API do Edge (*o middleware Edge não é suportado*) + Regeneração estática incremental (ISR) *sob demanda* + Streaming do Next.js + Execução de middleware em ativos estáticos e imagens otimizadas + Execução de código após uma resposta com `unstable_after` (recurso experimental lançado com o Next.js 15) ### Imagens do Next.js O tamanho máximo de saída de uma imagem não pode exceder 4,3 MB. É possível ter um arquivo de imagem maior armazenado em algum lugar e usar o componente de imagem do Next.js para redimensioná-lo e otimizá-lo em um formato Webp ou AVIF e, em seguida, fornecê-lo como um tamanho menor. Observe que a documentação do Next.js recomenda que você instale o módulo Sharp de processamento de imagem para habilitar o funcionamento correto da otimização de imagem em produção. Porém, isso não é necessário para implantações do Amplify. O Amplify implanta automaticamente o Sharp para você. # Implantação de uma aplicação SSR do Next.js no Amplify Por padrão, o Amplify implanta novas aplicações de SSR usando o serviço de computação do Amplify Hosting com suporte para versões do Next.js de 12 a 15. A computação do Amplify Hosting gerencia integralmente os recursos necessários para implantar uma aplicação de SSR. Os aplicativos SSR em sua conta do Amplify que você implantou antes de 17 de novembro de 2022 estão usando o provedor SSR Classic (somente Next.js 11). É altamente recomendável que você migre aplicativos usando o SSR Classic (somente Next.js 11) para o provedor de SSR de computação do Amplify Hosting. O Amplify não realiza migrações automáticas para você. É necessário migrar manualmente seu aplicativo e, em seguida, iniciar uma nova compilação para concluir a atualização. Para instruções, consulte [Migrando um aplicativo SSR Next.js 11 para a computação do Amplify Hosting](update-app-nextjs-version.md). Use as instruções a seguir para implantar uma nova aplicação SSR. **Para implantar um aplicativo SSR no Amplify usando o provedor de SSR de computação do Amplify Hosting** 1. Faça login no Console de gerenciamento da AWS e abra o console do [Amplify](https://console.aws.amazon.com/amplify/). 1. Na página **Todas as aplicações**, escolha **Criar nova aplicação**. 1. Na página **Comece a desenvolver com o Amplify**, escolha seu provedor de repositório Git e escolha **Avançar**. 1. Na página **Adicionar ramificação do repositório**, faça o seguinte: 1. Na lista **Repositórios atualizados recentemente**, selecione o nome do repositório a ser conectado. 1. Na lista **Ramificação**, selecione o nome da ramificação do repositório a ser conectada. 1. Escolha **Próximo**. 1. O aplicativo requer um perfil de serviço IAM que o Amplify assume ao chamar outros serviços em seu nome. É possível permitir que a computação do Amplify Hosting crie automaticamente um perfil de serviço ou especificar um perfil que criou. + Para permitir que o Amplify crie automaticamente um perfil e o anexe à sua aplicação: 1. Escolha **Criar e usar um novo perfil de serviço**. + Para anexar um perfil de serviço que você criou anteriormente: 1. Selecione **Usar um perfil de serviço existente**. 1. Selecione o perfil a ser usado na lista. 1. Escolha **Próximo**. 1. Na página **Revisar**, escolha **Salvar e implantar**. ## Configurações do arquivo Package.json Quando você implanta uma aplicação Next.js, o Amplify inspeciona o script de compilação da aplicação no arquivo `package.json` para detectar se a aplicação é SSR ou SSG. Veja a seguir um exemplo do script de compilação de uma aplicação do Next.js. O script de compilação `"next build"` indica que o aplicativo é compatível com páginas SSG e SSR. Esse script de construção também é usado para aplicações somente SSG do Next.js 14 ou versões posteriores. ``` "scripts": { "dev": "next dev", "build": "next build", "start": "next start" }, ``` Veja a seguir um exemplo do script de compilação de uma aplicação SSG do Next.js 13 ou anterior. O script de compilação `"next build && next export"` indica que o aplicativo é compatível somente com páginas SSG. ``` "scripts": { "dev": "next dev", "build": "next build && next export", "start": "next start" }, ``` ## Configurações de compilação do Amplify para uma aplicação SSR do Next.js Depois de inspecionar o arquivo `package.json` da sua aplicação, o Amplify verifica as configurações da compilação da aplicação. É possível salvar as configurações da compilação no console do Amplify ou em um arquivo `amplify.yml` na raiz do seu repositório. Para obter mais informações, consulte [Definição das configurações de compilação de uma aplicação do Amplify](build-settings.md). Se o Amplify detectar que você está implantando um aplicativo SSR Next.js e nenhum arquivo `amplify.yml` estiver presente, ele gerará uma especificação de compilação para o aplicativo e definirá `baseDirectory` como `.next`. Se você estiver implantando um aplicativo em que um arquivo `amplify.yml` esteja presente, as configurações da compilação no arquivo substituirão todas as configurações da compilação no console. Portanto, é necessário definir manualmente o valor `baseDirectory` para `.next` no arquivo. Veja a seguir um exemplo das configurações da compilação de um aplicativo em que `baseDirectory` está definido como `.next`. Isso indica que os artefatos de compilação são de um aplicativo Next.js compatível com páginas SSG e SSR. ``` version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: .next files: - '**/*' cache: paths: - node_modules/**/* ``` ## Configurações de compilação do Amplify para uma aplicação SSR do Next.js 13 ou anterior Se o Amplify detectar que você está implantando uma aplicação Next.js 13 ou anterior, ele gerará uma especificação de compilação para a aplicação e definirá `baseDirectory` como `out`. Se você estiver implantando um aplicativo em que um arquivo `amplify.yml` está presente, deverá definir manualmente o valor `baseDirectory` para `out` no arquivo. O diretório `out` é a pasta padrão que o Next.js cria para armazenar ativos estáticos exportados. Ao definir as configurações de especificação de compilação da sua aplicação, altere o nome da pasta `baseDirectory` para corresponder à configuração da sua aplicação. Veja a seguir um exemplo das configurações da compilação de uma aplicação em que `baseDirectory` está definido como `out` para indicar que os artefatos de compilação são de uma aplicação Next.js 13 ou anterior que oferece suporte somente a páginas SSG. ``` version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: out files: - '**/*' cache: paths: - node_modules/**/* ``` ## Configurações de compilação do Amplify para uma aplicação de SSR do Next.js 14 ou posteriores Na versão 14 do Next.js, o comando `next export` foi descontinuado e substituído por `output: 'export'` no arquivo `next.config.js` para habilitar exportações estáticas. Se estiver implantando uma aplicação SSG do Next.js 14 no console, o Amplify gerará uma especificação de compilação para a aplicação e definirá `baseDirectory` como `.next`. Se você estiver implantando um aplicativo em que um arquivo `amplify.yml` está presente, deverá definir manualmente o valor `baseDirectory` para `.next` no arquivo. Essa é a mesma configuração `baseDirectory` que o Amplify usa para aplicações `WEB_COMPUTE` de Next.js que oferecem suporte a páginas SSG e SSR. Veja a seguir um exemplo das configurações da compilação de uma aplicação SSG do Next.js 14 com o `baseDirectory` definido como `.next`. ``` version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: .next files: - '**/*' cache: paths: - node_modules/**/* ``` # Migrando um aplicativo SSR Next.js 11 para a computação do Amplify Hosting Quando você implanta um novo aplicativo Next.js, por padrão, o Amplify usa a versão mais recente compatível do Next.js. Atualmente, o provedor SSR de computação Amplify Hosting oferece suporte ao Next.js versão 15. O console do Amplify detecta aplicações em sua conta que foram implantadas antes do lançamento, em novembro de 2022, do serviço de computação do Amplify Hosting totalmente compatível com as versões do Next.js de 12 a 15. O console exibe um banner de informações identificando aplicativos com ramificações que são implantadas usando o provedor SSR anterior do Amplify, o Classic (somente Next.js 11). É altamente recomendável que você migre seus aplicativos para o provedor de SSR de computação do Amplify Hosting. Se você estiver atualizando sua aplicação Next.js 11 hospedada para Next.js 12 ou posterior, será possível receber um erro `"target" property is no longer supported` quando uma implantação for acionada. Nesse caso, será necessário migrar para a computação do Amplify Hosting. É necessário migrar manualmente o aplicativo e todas as suas ramificações de produção ao mesmo tempo. Uma aplicação não pode conter as ramificações Classic (somente Next.js 11) e Next.js 12 ou posterior. Use as instruções a seguir para migrar um aplicativo para o provedor de SSR de computação do Amplify Hosting. **Para migrar um aplicativo para o provedor de SSR de computação do Amplify Hosting** 1. Faça login no Console de gerenciamento da AWS e abra o console do [Amplify](https://console.aws.amazon.com/amplify/). 1. Escolha o aplicativo Next.js que você deseja migrar. **nota** Antes de migrar um aplicativo no console do Amplify, é necessário primeiro atualizar o arquivo package.json do aplicativo para usar o Next.js versão 12 ou posterior. 1. No painel de navegação, em **Configurações do aplicativo**, selecione **Geral**. 1. Na página inicial do aplicativo, o console exibirá um banner se o aplicativo tiver ramificações implantadas usando o *provedor SSR* **Classic (somente Next.js 11)**. No banner, escolha **Migrar.** 1. Na janela de confirmação da migração, selecione as três instruções e escolha **Migrar**. 1. O Amplify criará e reimplantará seu aplicativo para concluir a migração. ## Revertendo uma migração de SSR Quando você implanta um aplicativo Next.js, o Amplify Hosting detecta as configurações em seu aplicativo e define o valor interno da plataforma para o aplicativo. Há três valores válidos de plataforma. Um aplicativo SSG é definido com o valor `WEB` da plataforma. Um aplicativo SSR usando o Next.js versão 11 é definido com o valor `WEB_DYNAMIC` da plataforma. Um aplicativo SSR Next.js 12 ou posterior é definido com o valor `WEB_COMPUTE` da plataforma. Quando você migra um aplicativo usando as instruções na seção anterior, o Amplify altera o valor da plataforma do seu aplicativo de `WEB_DYNAMIC` para `WEB_COMPUTE`. Após a conclusão da migração para a computação do Amplify Hosting, você não pode reverter a migração no console. Para reverter a migração, é necessário usar o AWS Command Line Interface para alterar a plataforma do aplicativo de volta para o `WEB_DYNAMIC`. Abra uma janela do terminal e digite o comando a seguir, atualizando o ID do aplicativo e a região com suas informações exclusivas. ``` aws amplify update-app --app-id abcd1234 --platform WEB_DYNAMIC --region us-west-2 ``` # Adicionando a funcionalidade SSR a um aplicativo Next.js estático É possível adicionar a funcionalidade SSR a um aplicativo Next.js estático (SSG) existente implantado com o Amplify. Antes de iniciar o processo de conversão do aplicativo SSG em SSR, atualize o aplicativo para usar o Next.js versão 12 ou posterior e adicione a funcionalidade SSR. Em seguida, você precisará executar as etapas a seguir. 1. Use o AWS Command Line Interface para alterar o tipo de plataforma do aplicativo. 1. Adicione um perfil de serviço ao aplicativo. 1. Atualize o diretório de saída nas configurações da compilação do aplicativo. 1. Atualize o `package.json` arquivo do aplicativo para indicar que o aplicativo usa SSR. ## Atualização da plataforma Há três valores válidos de plataforma. Um aplicativo SSG está configurado para o tipo de plataforma `WEB`. Um aplicativo SSR usando o Next.js versão 11 está configurado para o tipo de plataforma `WEB_DYNAMIC`. Para aplicações implantadas no Next.js 12 ou posterior usando SSR gerenciado pela computação do Amplify Hosting, o tipo de plataforma está definido como `WEB_COMPUTE`. Quando você implantou seu aplicativo como um aplicativo SSG, o Amplify definiu o tipo de plataforma como `WEB`. Use o AWS CLI para alterar a plataforma do seu aplicativo para`WEB_COMPUTE`. Abra uma janela de terminal e digite o comando a seguir, atualizando o texto em vermelho com seu ID de aplicativo e região exclusivos. ``` aws amplify update-app --app-id abcd1234 --platform WEB_COMPUTE --region us-west-2 ``` ## Adicionar um perfil de serviço Uma função de serviço é a função AWS Identity and Access Management (IAM) que o Amplify assume ao ligar para outros serviços em seu nome. Siga estas etapas para adicionar um perfil de serviço a um aplicativo SSG que já está implantado com o Amplify. **Para criar um perfil de serviço** 1. Faça login no Console de gerenciamento da AWS e abra o console do [Amplify](https://console.aws.amazon.com/amplify/). 1. Se você ainda não criou um perfil de serviço em sua conta do Amplify, consulte [Adicionar um perfil de serviço](amplify-service-role.md) para concluir esta etapa de pré-requisito. 1. Escolha o aplicativo estático do Next.js ao qual você deseja adicionar um perfil de serviço. 1. No painel de navegação, em **Configurações do aplicativo**, selecione **Geral**. 1. Na página **Detalhes do aplicativo**, selecione **Editar** 1. Em **Perfil de serviço**, escolha o nome de um perfil de serviço existente ou o nome do perfil de serviço que você criou na etapa 2. 1. Escolha **Salvar**. ## Atualização das configurações de compilação Antes de reimplantar seu aplicativo com a funcionalidade SSR, é necessário atualizar as configurações da compilação do aplicativo para definir o diretório de saída como `.next`. É possível editar as configurações da compilação no console do Amplify ou em um arquivo `amplify.yml` armazenado em seu repositório. Para obter mais informações, consulte [Definição das configurações de compilação de uma aplicação do Amplify](build-settings.md). Veja a seguir um exemplo das configurações da compilação de um aplicativo em que `baseDirectory` está definido como `.next`. ``` version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: .next files: - '**/*' cache: paths: - node_modules/**/* ``` ## Atualização do arquivo package.json Depois de adicionar um perfil de serviço e atualizar as configurações da compilação, atualize o arquivo `package.json` do aplicativo. Como no exemplo a seguir, defina o script de compilação para `"next build"` indicar que o aplicativo Next.js é compatível com páginas SSG e SSR. ``` "scripts": { "dev": "next dev", "build": "next build", "start": "next start" }, ``` O Amplify detecta a alteração no arquivo `package.json` em seu repositório e reimplanta o aplicativo com a funcionalidade SSR. # Tornando as variáveis de ambiente acessíveis aos runtimes do lado do servidor O Amplify Hosting suporta a adição de variáveis de ambiente às compilações do seu aplicativo, definindo-as na configuração do projeto no console do Amplify. No entanto, um componente do servidor Next.js não tem acesso a essas variáveis de ambiente por padrão. Esse comportamento é intencional para proteger todos os segredos armazenados nas variáveis de ambiente que seu aplicativo usa durante a fase de compilação. Para tornar variáveis de ambiente específicas acessíveis ao Next.js, é possível modificar o arquivo de especificação de compilação do Amplify para defini-las nos arquivos de ambiente que o Next.js reconhece. Isso permite que o Amplify carregue essas variáveis de ambiente antes de compilar o aplicativo. **Importante** É altamente recomendável que você não armazene credenciais, segredos ou informações confidenciais em suas variáveis de ambiente, pois qualquer usuário com acesso aos artefatos de implantação poderá lê-las. Para dar à sua função de computação SSR acesso aos AWS recursos, recomendamos o [uso de funções do IAM](amplify-SSR-compute-role.md). O exemplo de especificação de compilação a seguir demonstra como adicionar variáveis de ambiente na seção de comandos de compilação. ``` version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - env | grep -e API_BASE_URL >> .env.production - env | grep -e NEXT_PUBLIC_ >> .env.production - npm run build artifacts: baseDirectory: .next files: - '**/*' cache: paths: - node_modules/**/* - .next/cache/**/* ``` Neste exemplo, a seção de comandos de compilação inclui dois comandos que gravam variáveis de ambiente no arquivo `.env.production` antes da execução da compilação do aplicativo. O Amplify Hosting permite que seu aplicativo acesse essas variáveis quando o aplicativo recebe tráfego. A linha a seguir da seção de comandos de compilação no exemplo anterior demonstra como pegar uma variável específica do ambiente de compilação e adicioná-la ao arquivo `.env.production`. ``` - env | grep -e API_BASE_URL -e APP_ENV >> .env.production ``` Se as variáveis existirem em seu ambiente de compilação, o arquivo `.env.production` conterá as seguintes variáveis de ambiente. ``` API_BASE_URL=localhost APP_ENV=dev ``` A linha a seguir da seção de comandos de compilação no exemplo anterior demonstra como adicionar uma variável de ambiente com um prefixo específico ao arquivo `.env.production`. Neste exemplo, todas as variáveis com o prefixo `NEXT_PUBLIC_` são adicionadas. ``` - env | grep -e NEXT_PUBLIC_ >> .env.production ``` Se existirem várias variáveis com o prefixo `NEXT_PUBLIC_` no ambiente de compilação, o `.env.production` arquivo terá uma aparência semelhante à seguinte. ``` NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk NEXT_PUBLIC_GRAPHQL_ENDPOINT=uowelalsmlsadf NEXT_PUBLIC_FEATURE_FLAG=true ``` ## Variáveis de ambiente do SSR para monorepos Se estiver implantando uma aplicação SSR em um monorepo e quiser tornar variáveis de ambiente específicas acessíveis ao Next.js, é necessário prefixar o arquivo `.env.production` com a raiz da sua aplicação. O exemplo a seguir de especificação de compilação para uma aplicação Next.js com um monorepo Nx demonstra como adicionar variáveis de ambiente na seção de comandos de compilação. ``` version: 1 applications: - frontend: phases: preBuild: commands: - npm ci build: commands: - env | grep -e API_BASE_URL -e APP_ENV >> apps/app/.env.production - env | grep -e NEXT_PUBLIC_ >> apps/app/.env.production - npx nx build app artifacts: baseDirectory: dist/apps/app/.next files: - '**/*' cache: paths: - node_modules/**/* buildPath: / appRoot: apps/app ``` As linhas a seguir da seção de comandos de compilação no exemplo anterior demonstram como pegar variáveis específicas do ambiente de compilação e adicioná-la ao arquivo `.env.production` para uma aplicação em um monorepo com a raiz `apps/app` da aplicação. ``` - env | grep -e API_BASE_URL -e APP_ENV >> apps/app/.env.production - env | grep -e NEXT_PUBLIC_ >> apps/app/.env.production ``` # Implantando um aplicativo Next.js em um monorepo O Amplify suporta aplicativos em monorepos genéricos, bem como aplicativos em monorepos criados usando npm workspace, pnpm workspace, Yarn workspace, Nx e Turborepo. Quando você implanta seu aplicativo, o Amplify detecta automaticamente a estrutura de compilação monorepo que você está usando. O Amplify aplica automaticamente as configurações da compilação para aplicativos em um espaço de trabalho npm, espaço de trabalho Yarn ou Nx. Os aplicativos Turborepo e pnpm requerem configuração adicional. Para obter mais informações, consulte [Definição de configurações de compilação monorepo](monorepo-configuration.md). Para ver um exemplo detalhado do Nx, consulte a postagem do blog [Compartilhar código entre aplicativos Next.js com o Nx no AWS Amplify Hosting](https://aws.amazon.com/blogs/mobile/share-code-between-next-js-apps-with-nx-on-aws-amplify-hosting/).