Atualize para o Astro v4

Este guia vai te ajudar a migrar do Astro v3 para o Astro v4.

Precisa atualizar um projeto antigo para a v3? Veja nosso antigo guia de migração.

Precisa ver a documentação da v3? Visite essa versão antiga do site de documentação (snapshot v3.6 não mantido).

Atualize o Astro

Atualize a versão do Astro e de todas as integrações oficiais em seu projeto para a versão mais recente utilizando seu gerenciador de pacotes.

# Atualiza o Astro e integrações oficiais juntos
npx @astrojs/upgrade

# Atualiza o Astro e integrações oficiais juntos
pnpm dlx @astrojs/upgrade

# Atualiza o Astro e integrações oficiais juntos
yarn dlx @astrojs/upgrade

Você também pode atualizar suas integrações do Astro manualmente se preferir, e você pode precisar atualizar outras dependências no seu projeto.

Astro v4.0 inclui mudanças potencialmente radicais, assim como remoção de funcionalidades anteriormente descontinuadas.

Se seu projeto não funcionar como o esperado após atualizar para a v4.0, veja esse guia para uma visão geral de todas as mudanças radicais e instruções sobre como atualizar sua base de código.

Veja o registro de mudanças para as notas completas do lançamento.

Flags Experimentais Removidas no Astro v4.0

Remova a flag experimental devOverlay e mova qualquer configuração i18n para o primeiro nível em astro.config.mjs:

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    devOverlay: true,
    i18n: {
      defaultLocale: "en",
      locales: ["en", "fr", "pt-br", "es"],
    }
  },
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
  },
})

Essas configurações, i18n e o renomeado devToolbar agora estão disponíveis no Astro v4.0.

Leia mais sobre essas excitantes nos funcionalidades no blog post v4.0!

Atualizações

Toda atualização major de dependências do Astro pode causar mudanças radicais em seu projeto.

Atualizado: Vite 5.0

No Astro v3.0, Vite 4 foi utilizado como o servidor de desenvolvimento e bundler de produção.

Astro v4.0 atualiza do Vite 4 para o Vite 5.

O que eu preciso fazer?

Se você estiver utilizando plugins, configurações, ou APIs específicos do Vite, veja o guia de migração do Vite para saber as mudanças radicais deles e atualize seu projeto conforme necessário. Não há mudanças radicais no próprio Astro.

Atualizado: dependências de unified, remark, e rehype

No Astro v3.0, unified v10 e seus pacotes remark/rehype compatíveis relacionados foram utilizados para procesar Markdown e MDX.

Astro v4.0 atualiza unified para v11 e os outros pacotes remark/rehype para a última versão.

O que eu preciso fazer?

Se você utiliza pacotes remark/rehype customizados, atualize todos eles para a última versão utilizando o seu gerenciador de pacotes para garantir que eles suportem unified v11. Os pacotes que você está usando podem ser encontrados em astro.config.mjs.

Não deve haver nenhuma mudança radical significativa se você estiver utilizando pacotes ativamente atualizados, mas alguns pacotes podem ainda não ser compatíveis com o unified v11. Inspecione visualmente suas páginas Markdown/MDX antes de fazer um deploy para garantir que seu site está funcionando como o planejado.

Mudanças radicais

As seguintes mudanças são consideradas mudanças radicais no Astro. Mudanças radicais podem manter temporariamente compatibilidade com versões anteriores ou não, e toda a documentação é atualizada para se referir exclusivamente ao código suportado atual.

Se você precisar consultar a documentação para um projeto v3.x, você pode acessar esse snapshot (não mantido) da docs de antes da v4.0 ser lançada.

Renomeado: `entrypoint` (API de Integrações)

No Astro v3.x, a propriedade da API de integrações injectRoute que especificava o ponto de entrada da rota foi nomeado entryPoint.

Astro v4.0 renomeia essa propriedade para entrypoint para ser consistente com outras APIs Astro. A propriedade entryPoint foi descontinuada, mas ainda continua a funcionar e emite um aviso requisitando que atualize seu código.

O que eu preciso fazer?

Se você tiver integrações que usem a API injectRoute, renomeie a propriedade entryPoint para entrypoint. Se você é autor de uma biblioteca que quer suportar tanto Astro 3 quanto 4, você pode especicar ambos entryPoint e entrypoint, nesse caso, nenhum aviso será emitido.

injectRoute({
  pattern: '/fancy-dashboard',
  entryPoint: '@fancy/dashboard/dashboard.astro'
  entrypoint: '@fancy/dashboard/dashboard.astro'
});

Alterado: assinatura de `app.render` na API de Integrações

No Astro v3.0, o método app.render() aceitava routeDate e locals como argumentos separados, ambos opcionais.

Astro v4.0 muda a assinatura de app.render(). Essas duas propriedades agora estão disponíveis em um único objeto. Tanto o objeto quanto essas duas propriedades ainda são opcionais.

O que eu preciso fazer?

Se você mantém um adaptador, a assinatura atual continuará funcionando até a próxima versão major. Para migrar para a nova assinatura, passe routeData e local como propriedades de um objeto ao invés de múltiplos argumentos independentos.

app.render(request, routeData, locals)
app.render(request, { routeData, locals })

Alterado: adaptadores agora devem especificar funcionalidades suportadas

No Astro v3.0, adaptadores não era obrigados a especificar as funcionalidades que suportavam.

Astro v4.0 requer que adaptadores passem a propriedade supportedAstroFeatures para especificar a lista de funcionalidades que suportam. Essa propriedade não é mais opcional.

O que eu preciso fazer?

Autores de adaptadores precisam passar a opção supportedAstroFeatures para especificar a lista de funcionalidades que suportam.

export default function createIntegration() {
  return {
    name: '@matthewp/meu-adaptador',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@matthewp/meu-adaptador',
          serverEntrypoint: '@matthewp/meu-adaptador/server.js',
          supportedAstroFeatures: {
              staticOutput: 'stable'
          }
        });
      },
    },
  };
}

Removido: propriedade `path` de linguagem do Shiki

No Astro v3.x, a linguagem do Shiki passada para markdown.shikiConfig.langs era automaticamente convertida para uma linguagem compatível com Shikiji. Shikiji é a ferramenta interna utilizada para syntax highlight pelo Astro.

Astro v4.0 remove o suporte à propriedade path de uma linguagem do Shiki, que era confusa de configurar. Ela foi substituída por um import que pode ser passado langs diretamente.

O que eu preciso fazer?

O arquivo JSON de linguagem deve ser importado e passado para a opção correta.

 import customLang from './custom.tmLanguage.json'

export default defineConfig({
  markdown: {
    shikiConfig: {
      langs: [
       { path: '../../custom.tmLanguage.json' },
       customLang,
      ],
    },
  },
})

Descontinuado

As seguntes funcionalidades descontinuadas não são mais suportadas nem documentadas. Por favor, atualize seu projeto conforme apropriado.

Algumas funcionalidades descontinuadas podem continuar funcionando temporariamente até serem completamente removidas. Outras podem silenciosamente não ter nenhum efeito, ou causar um erro requisitando que atualize seu código.

Descontinuado: `handleForms` para eventos `submit` em Transições de Visualização

No Astro v3.x, projetos utilizando o componente <ViewTransitions /> precisavam optar por tratar eventos submit para elementos form. Isso era feito passando a prop handleForms.

Astro v4.0 trata eventos submit para elementos form por padrão quando <ViewTransitions /> é utilizado. A prop handleForms foi descontinuada e não tem mais nenhum efeito.

O que eu devo fazer?

Remova a propriedade handleForms do seu componente <ViewTransitions />. Ela não é mais necessária.

---
import { ViewTransitions } from "astro:transitions";
---
<html>
  <head>
    <ViewTransitions handleForms />
  </head>
  <body>
    <!-- stuff here -->
  </body>
</html>

Para optar por não ter o tratamento dos eventos submit, adicione o atributo data-astro-reload nos elementos form relevantes.

<form action="/contact" data-astro-reload>
  <!-- -->
</form>

Funcionalidades previamente descontinuadas agora removidas

As seguintes funcionalidades descontinuadas foram agora inteiramente removidas da base de código enão podem mais ser usadas. Algumas dessas funcionalidades podem ter continuado a funcionar em seu projeto mesmo depois de serem descontinuadas. Outras podem ter silenciosamente ficado sem efeito.

Agora projetos contendo essas funcionalidades removidas ficaram impossibilitados de fazer o build, e não haverá mais qualquer documentação auxiliar pedindo-lhe para remover essas funcionalidades.

Removido: retornar objetos simples de endpoints

No Astro v3.x, retornar objetos simples de endpoints foi descontinuado, mas ainda era suportado para manter compatibilidade com Astro v2. O utilitário ResponseWithEncoding também foi disponibilizado para facilitar a migração.

Astro v4.0 remove o suporte a objetos simples e exige que endpoints sempre retornem uma resposta (Respons). O utilitário ResponseWithEncoding também foi removido em favor do tipo Response apropriado.

O que eu preciso fazer?

Atualize seus endpoints para retornarem um objeto Response diretamente.

export async function GET() {
  return { body: { "title": "Bob's blog" }};
  return new Response(JSON.stringify({ "title": "Bob's blog" }));
}

Para remover o uso de ResponseWithEncoding, refatore seu código para utilizar um ArrayBuffer no lugar:

export async function GET() {
  const file = await fs.readFile('./bob.png');
  return new ResponseWithEncoding(file.toString('binary'), undefined, 'binary');
  return new Response(file.buffer);
}

Removido: `build.split` e `build.excludeMiddleware`

No Astro v3.0, as opções da configuração de build build.split e build.excludeMiddleware foram descontinuadas e substituídas por opções de configuração de adaptadores que cumprem a mesma tarefa.

Astro v4.0 remove completamente essas propriedades.

O que eu preciso fazer?

Se você está utilizando as opções descontinuadas build.split ou build.excludeMiddleware, você deve agora removê-las visto que elas não existem mais.

Por favor veja o guia de migração v3 para substituir essas propriedades descontinuadas do middleware por configurações de adaptador.

Removido: `Astro.request.params`

No Astro v3.0, a API Astro.request.params foi descontinuada, mas preservada por compatibilidade com versões anteriores.

Astro v4.0 remove completamente essa opção.

O que eu preciso fazer?

Atualize todas as ocorrências para Astro.params, que é o substituto suportado.

const { id } = Astro.request.params;
const { id } = Astro.params;

Removido: `markdown.drafts`

No Astro v3.0, utilizar markdown.drafts para controlar o build de rascunhos foi descontinuado.

Astro v4.0 remove completamente essa opção.

O que eu preciso fazer?

Se você está utilizando a opção markdown.drafts descontinuada, você deve removê-la visto que ela não existe mais.

Para continue a marcar algumas páginas de seu projeto como rascunho, migre para coleções de conteúdo e filtre manualmente as páginas com a propriedade draft: true do frontmatter.

Removido: `getHeaders()`

No Astro v3.0, o export getHeaders() de Markdowns foi descontinuado e substituído por getHeadings().

Astro v4.0 remove completamente essa opção.

O que eu preciso fazer?

Se você está utilizando o getHeaders() descontinuado, você deve removê-lo visto que ele não existe mais. Substitua todas as ocorrências por getHeadings(), que é o substituto suportado.

const posts = await Astro.glob('../content/blog/*.mdx');
const firstPostHeadings = posts.at(0).getHeaders();
const firstPostHeadings = posts.at(0).getHeadings();

Removido: utilizar `rss` em `getStaticPaths()`

No Astro v3.0, utilizar o utilitário descontinuado rss em getStaticPaths() soltaria um erro.

Astro v4.0 remove completamente essa opção.

O que eu preciso fazer?

Se você está utilizando o método não suportado para gerar feeds RSS, você deve agora utilizar a integração @astrojs/rss para uma configuração RSS completa.

Removido: métodos HTTP em letras minúsculas

No Astro v3.0, utilizar métodos de chamada HTTP em letras minúsculas (get, post, put, all, del) foi descontinuado.

Astro v4.0 remove o suporte a métodos em letras minúsculas completamente. Todos os métodos de chamadas HTTML agora devem ser escritos com letras maiúsculas.

O que eu preciso fazer?

Se você está usando os nomes em letras minúsculas descontinuados, você deve substituí-los pelos equivalentes em letras maiúsculas.

Por favor veja o guia de migração v3 para orientações sobre o uso de métodos de chamada HTTP em letras maiúsculas.

Removido: redirecionamentos 301 na falta do prefixo `base`

No Astro v3.x, o servidor de pré-visualização do Astro retornava um redirectionamento 301 ao acessar recursos do diretório public sem um caminho base.

Astro v4.0 retorna um status 404 sem o prefixo do caminho base para recursos do diretório public quando o servidor de pré-visualização, replicando o comportamento do servidor de desenvolvimento.

O que eu preciso fazer?

Ao utilizar o servidor de pré-visualização do AStro, todos os imports e URLs de seus recursos estáticos do diretório public devem ter o valor base prefixado ao caminho.

// To access public/images/my-image.png:

<img src="/docs/images/my-image.png" alt="">

Removido: conversão automática de `astro/client-image`

No Astro v3.x, o tipo astro/client-image (utilizado para a descontinuada integração de imagem) foi removido, mas automaticamente convertido para o tipo astro/client padrão do Astro se encontrado em seu arquivo env.d.ts.

Astro v4.0 ignora astro/client-image e não vai mais atualizar env.d.ts automaticamente para você.

O que eu preciso fazer?

Se você tinha tipos configurados para @astrojs/image em src/env.d.ts e atualizar para v3.0 não converteu automaticamente o tipo para você, substitua o tipo astro/client-image manualmente por astro/client.

  /// <reference types="astro/client-image" />
  /// <reference types="astro/client" />

Recursos da comunidade

Conhece algum bom recurso para Astro v4.0? Edite essa página e adicione um link abaixo!

Problemas conhecidos

Por favor confira as issues do Astro no GitHub por problemas reportados, ou para reportar um problema você mesmo.

Contribua

Comunidade

Atualize para o Astro v4

Atualize o Astro

Flags Experimentais Removidas no Astro v4.0

Atualizações

Atualizado: Vite 5.0

O que eu preciso fazer?

Atualizado: dependências de unified, remark, e rehype

O que eu preciso fazer?

Mudanças radicais

Renomeado: entrypoint (API de Integrações)

O que eu preciso fazer?

Alterado: assinatura de app.render na API de Integrações

O que eu preciso fazer?

Alterado: adaptadores agora devem especificar funcionalidades suportadas

O que eu preciso fazer?

Removido: propriedade path de linguagem do Shiki

O que eu preciso fazer?

Descontinuado

Descontinuado: handleForms para eventos submit em Transições de Visualização

O que eu devo fazer?

Funcionalidades previamente descontinuadas agora removidas

Removido: retornar objetos simples de endpoints

O que eu preciso fazer?

Removido: build.split e build.excludeMiddleware

O que eu preciso fazer?

Removido: Astro.request.params

O que eu preciso fazer?

Removido: markdown.drafts

O que eu preciso fazer?

Removido: getHeaders()

O que eu preciso fazer?

Removido: utilizar rss em getStaticPaths()

O que eu preciso fazer?

Removido: métodos HTTP em letras minúsculas

O que eu preciso fazer?

Removido: redirecionamentos 301 na falta do prefixo base

O que eu preciso fazer?

Removido: conversão automática de astro/client-image

O que eu preciso fazer?

Recursos da comunidade

Problemas conhecidos

Renomeado: `entrypoint` (API de Integrações)

Alterado: assinatura de `app.render` na API de Integrações

Removido: propriedade `path` de linguagem do Shiki

Descontinuado: `handleForms` para eventos `submit` em Transições de Visualização

Removido: `build.split` e `build.excludeMiddleware`

Removido: `Astro.request.params`

Removido: `markdown.drafts`

Removido: `getHeaders()`

Removido: utilizar `rss` em `getStaticPaths()`

Removido: redirecionamentos 301 na falta do prefixo `base`

Removido: conversão automática de `astro/client-image`