Atualize para o Astro v3
Este guia vai te ajudar a migrar do Astro v2 para o Astro v3.
Precisa atualizar um projeto antigo para a v2? Veja nosso antigo guia de migração.
Atualize Astro
Seção intitulada Atualize AstroAtualize a versão do Astro de seu projeto para a versão mais recente utilizando seu gerenciador de pacotes. Se você está utilizando integrações Astro, por favor também as atualize para a versão mais recente.
Após atualizar Astro para a versão mais recente, você pode não precisar fazer quaisquer mudanças ao seu projeto afinal!
Porém, se você notar erros ou comportamentos inesperados, por favor veja abaixo o que mudou que pode precisar ser atualizado em seu projeto.
Flags Experimentais Removidas do Astro v3.0
Seção intitulada Flags Experimentais Removidas do Astro v3.0Remova as seguintes flags experimentais de astro.config.mjs
:
Essas funcionalidades agora estão disponíveis por padrão:
- Transições de Visualização para transições de página animadas e ilhas persistentes. Veja as mudanças radicais da API de transições de visualização e dicas para atualização se você estava utilizando essa flag experimental.
- Uma nova API de serviço de imagem
astro:assets
para utilizar imagens no Astro, incluindo um novo componente<Image />
e a funçãogetImage()
. Por favor leia as detalhadas dicas de atualização para imagens se você estava ou não utilizando essa flag experimental para ver como isso pode afetar seu projeto.
Leia mais sobre essas duas funcionalidades eletrizantes e mais na postagem do blog sobre a 3.0!
Mudanças Radicais do Astro v3.0
Seção intitulada Mudanças Radicais do Astro v3.0Astro v3.0 inclui algumas mudanças radicais, assim como a remoção de algumas funcionalidades anteriormente depreciadas. Se o seu projeto não funciona como esperado após atualizar para a v3.0, veja este guia para uma visão geral sobre todas as mudanças radicais e instruções em como atualizar sua base de código.
Veja o registro de mudanças para as notas completas do lançamento.
Removido: Suporte para o Node 16
Seção intitulada Removido: Suporte para o Node 16Node 16 está marcado para chegar seu Fim de Vida em setembro de 2023.
Astro v3.0 tira o suporte para Node 16 completamente para que todos os usuários do Astro se aproveitem das funcionalidades mais modernas do Node.
O que devo fazer?
Seção intitulada O que devo fazer?Verifique eu tanto seu ambiente de desenvolvimento quanto seu ambiente de deployment estão utilizando Node 18.14.1
ou superior.
-
Verifique sua versão local do Node utilizando:
-
Verifique a própria documentação do seu ambiente de deployment para verificar que ele suporta Node 18.
Você pode especificar Node
18.14.1
para seu projeto Astro tanto em uma opção da configuração do painel de controle ou em um arquivo.nvmrc
.
Removido: Suporte para TypeScript 4
Seção intitulada Removido: Suporte para TypeScript 4Na Astro v2.x, as predefinições de tsconfig.json
incluiam suporte para ambos TypeScript 4.x e 5.x.
Astro v3.0 atualiza as predefinições de tsconfig.json
para apenas suportar TypeScript 5.x. Astro agora assume que você utiliza TypeScript 5.0 (Março de 2023), ou que seu editor o inclui (e.x. VS Code 1.77).
O que devo fazer?
Seção intitulada O que devo fazer?Se você tem o TypeScript instalado localmente, atualize pelo menos para a v5.0.
Removido: @astrojs/image
Seção intitulada Removido: @astrojs/imageNo Astro v2.x, Astro oferecia uma integração de imagens oficial que incluia os componentes Astro <Image />
e <Picture />
.
Astro v3.0 remove essa integração da base de código completamente. A nova solução para imagens do Astro é uma API integrada de serviços de imagem: astro:assets
.
O que devo fazer?
Seção intitulada O que devo fazer?Remova a integração @astrojs/image
do seu projeto. Você irá precisar não só desinstalar a integração mas também atualizar ou remover quaisquer declarações de importação e quaisquer componentes <Image />
e <Picture />
existentes. Você também vai precisar configurar um serviço de processamento de imagem padrão de sua preferência.
Você irá encontrar instruções passo a passo completas para remover a integração de imagens antiga em nosso guia de Imagens.
Migrar para astro:assets
também irá trazer algumas novas opções de imagem e funcionalidades que você pode desejar utilizar agora. Por favor veja as dicas de atualização para imagens da v3.0 para mais detalhes!
Removido: Componente <Markdown />
Seção intitulada Removido: Componente <Markdown />No Astro v1.x, Astro depreciou o componente <Markdown />
e o moveu para um pacote externo.
Astro v3.0 remove completamente o pacote @astrojs/markdown-component
. O componente <Markdown />
do Astro não irá mais funcionar no seu projeto.
O que devo fazer?
Seção intitulada O que devo fazer?Remova todas as instâncias de @astrojs/markdown-component
.
Para continuar utilizando um componente <Markdown />
similar no seu código, considere utilizar integrações da comunidade assim como astro-remote
. Certifique-se de atualizar as importações e atributos do seu componente <Markdown />
conforme necessário, de acordo com a documentação da própria integração.
Como alternativa, delete todas as referências importando o componente <Markdown />
do Astro e o próprio componente em seus arquivos .astro
. Você vai precisar escrever novamente seu conteúdo como HTML diretamente ou importar Markdown de um arquivo .md
.
Removido: APIs depreciadas da 1.x
Seção intitulada Removido: APIs depreciadas da 1.xNo Astro v1.x, Astro depreciou nossas configurações originais assim como o suporte a <style global>
e <script hoist>
. Entretanto, esses ainda foram suportados por compatibilidade com versões anteriores.
Astro v3.0 remove essas APIs depreciadas completamente. As definições de configuração oficialmente suportadas e a sintaxe moderna <style is:global>
e <script>
devem ser usadas ao invés disso.
O que devo fazer?
Seção intitulada O que devo fazer?Se você continua utilizando APIs da v1.x, utilize as novas APIs para cada uma das funcionalidades no lugar:
- Opções depreciadas da configuração: Veja o guia de migração da 0.26 (EN)
- Tipos de atributo de script/style depreciados: Veja o guia de migração da 0.26 (EN)
Removido: Correções parciais para APIs da Web no código do servidor
Seção intitulada Removido: Correções parciais para APIs da Web no código do servidorNo Astro v2.x, Astro forneceu correções parciais para APIs da Web como document
ou localStorage
em código renderizado pelo servidor. Essas correções eram muitas vezes incompletas e não confiáveis.
Astro v3.0 remove essas correções parciais inteiramente. APIs da Web não estão mais disponíveis em código renderizado pelo servidor.
O que devo fazer?
Seção intitulada O que devo fazer?Se você está usando APIs da Web em componentes renderizados pelo servidor, você vai precisar de ou fazer uso dessas APIs condicionalmente ou usar a diretiva de cliente client:only
.
Removido: image
do astro:content
no esquema de coleções de conteúdo
Seção intitulada Removido: image do astro:content no esquema de coleções de conteúdoNo Astro v2.x, a API de coleções de conteúdo depreciou a exportação image
do astro:content
utilizada no esquema de suas coleções de conteúdo.
Astro v3.0 remove essa exportação completamente.
O que devo fazer?
Seção intitulada O que devo fazer?Se você está utilizando o image()
depreciado do astro:content
, o remova, já que ele não existe mais. Valide imagens através do utilitário image
de schema
no lugar:
Removido: nomes de temas do Shiki pré-0.14
Seção intitulada Removido: nomes de temas do Shiki pré-0.14No Astro v2.x, alguns nomes de tema do Shiki foram renomeados, mas os nomes originais foram mantidos por compatibilidade com versões anteriores.
Astro v3.0 remove os nomes originais em favor dos nomes de tema renomeados.
O que devo fazer?
Seção intitulada O que devo fazer?Se o seu projeto utiliza qualquer um dos temas abaixo, os renomeie para seu nome atualizado:
material-darker
->material-theme-darker
material-default
->material-theme
material-lighter
->material-theme-lighter
material-ocean
->material-theme-ocean
material-palenight
->material-theme-palenight
Removido: Funcionalidades do class:list
Seção intitulada Removido: Funcionalidades do class:listNo Astro v2.x, a diretiva class:list
utilizava uma implementação customizada, inspirada por clsx
com algumas funcionalidades extras como desduplicação e suporte para Set
.
Astro v3.0 agora utiliza clsx
diretamente para class:list
, que não suporta desduplicação ou valores Set
.
O que devo fazer?
Seção intitulada O que devo fazer?Substitua quaisquer elementos Set
passados para a diretiva class:list
com um Array
plano.
Removido: passar class:list
como uma prop
Seção intitulada Removido: passar class:list como uma propNo Astro v2.x, valores de class:list
eram passados para componentes através de Astro.props['class:list']
.
Astro v3.0 normaliza valores de class:list
em uma string antes de os enviar para componentes através de Astro.props['class']
O que devo fazer?
Seção intitulada O que devo fazer?Remova qualquer código que espera receber a prop class:list
.
Removido: transformação de variáveis CSS de camelCase para kebab-case
Seção intitulada Removido: transformação de variáveis CSS de camelCase para kebab-caseNo Astro v2.x, variáveis CSS camelCase passadoas para o atributo style
eram renderizadas tanto como camelCase (assim como foi escrito) como em kebab-case (mantido por compatibilidade com versões anteriores).
Astro v3.0 remove a transformação para kebab-case de nomes de variáveis CSS em camelCase, e apenas a variável CSS original em camelCase é renderizada.
O que devo fazer?
Seção intitulada O que devo fazer?Se você dependia no Astro para transformar em kebab-case em seus estilos, atualize seus estilos existentes para camelCase para prevenir estilos faltando. Por exemplo:
Removido: Planificação automática do valor de retorno de getStaticPaths()
Seção intitulada Removido: Planificação automática do valor de retorno de getStaticPaths()No Astro v2.x, o valor de retorno de getStaticPaths()
era automaticamente planificado para te permitir retornar um array sem nenhum erro.
Astro v3.0 remove a planificação automática do resultado de getStaticPaths()
.
O que devo fazer?
Seção intitulada O que devo fazer?Se você está retornando um array de arrays no lugar de um array de objetos (como é esperado), .flatMap
e .flat
agora devem ser usados para garantir que você está retornando um array plano.
Uma mensagem de erro indicando que o valor de retorno de getStaticPath()
deve ser um array de objetos será providenciado se você precisa atualizar seu código.
Movido: astro check
agora requer um pacote externo
Seção intitulada Movido: astro check agora requer um pacote externoNo Astro v2.x, astro check
era incluso com o Astro por padrão, e suas dependências eram embutidas no Astro. Isso significava em um pacote maior, independente se você usava ou não astro check
. Isso também te prevenia de ter controle sobre a versão do TypeScript e o Servidor de Linguagem do Astro a se utilizar.
Astro v3.0 move o comando astro check
para fora do núcleo do Astro e agora requer o pacote externo @astrojs/check
. Adicionalmente, você deve instalar typescript
em seu projeto para utilizar o comando astro check
.
O que devo fazer?
Seção intitulada O que devo fazer?Execute o comando astro check
após atualizar para o Astro v3.0 e siga as instruções para instalar as dependências necessárias, ou manualmente instale @astrojs/check
e typescript
em seu projeto.
Depreciado: build.excludeMiddleware
e build.split
Seção intitulada Depreciado: build.excludeMiddleware e build.splitNo Astro v2.x, build.excludeMiddleware
e build.split
eram utilizados para mudar como arquivos específicos eram emitidos ao utilizar um adaptador no modo SSR.
Astro v3.0 substitui essas opções de configuração da build com novas opções de configuração de adaptadores SSR para realizar as mesmas tarefas: edgeMiddleware
e functionPerRoute
.
O que devo fazer?
Seção intitulada O que devo fazer?Atualize o arquivo de configuração do Astro para agora utilizar as novas opções na configuração do adaptador diretamente.
Depreciado: markdown.drafts
Seção intitulada Depreciado: markdown.draftsNo Astro v2.x, a configuração markdown.drafts
te permitia ter páginas de rascunho que eram disponibilizadas ao executar o servidor de desenvolvimento, mas não na build para produção.
Astro v3.0 deprecia essa funcionalidade em favor do método de coleções de conteúdo de manipular páginas de rascunho filtrando manualmente no lugar, o que te dá mais controle sobre a funcionalidade.
O que devo fazer?
Seção intitulada O que devo fazer?Para continuar a marcar algumas páginas em seu projeto como rascunhos, migue para coleções de conteúdo e filtre páginas manualmente com a propriedade do frontmatter draft: true
no lugar.
Depreciado: retornar um objeto simples de endpoints
Seção intitulada Depreciado: retornar um objeto simples de endpointsNo Astro v2.x, endpoints podiam retornar um objeto simples, que seria convertido para uma resposta JSON.
Astro v3.0 deprecia esse comportamento em favor de retornar um objeto Response
diretamente.
O que devo fazer?
Seção intitulada O que devo fazer?Atualize seus endpoints para reotrnar um objeto Response
diretamente.
Se você realmente precisar manter o formato anterior, você pode utilizar o objeto ResponseWithEncoding
, mas isso será depreciado no futuro.
Padrão alterado: verbatimModuleSyntax
nas predefinições de tsconfig.json
Seção intitulada Padrão alterado: verbatimModuleSyntax nas predefinições de tsconfig.jsonNo Astro v2.x, a configuração verbatimModuleSyntax
era desativada por padrão, com seu equivalente importsNotUsedAsValues
do TypeScript 4.x sendo habilitado na predefinição strict
.
No Astro v3.0, verbatimModuleSyntax
está habilitado em todas as predefinições.
O que devo fazer?
Seção intitulada O que devo fazer?Esta opção requer que os tipos sejam importados usando a sintaxe import type
.
Enquanto nós recomendamos manter ele ativado e apropriadamente fazer suas importações de tipo com type
(como mostrado acima), você pode desativar ele definindo verbatimModuleSyntax: false
no seu arquivo tsconfig.json
se isso causa algum problema.
Padrão modificado: porta 3000
Seção intitulada Padrão modificado: porta 3000No Astro v2.x, Astro era executado na porta 3000
por padrão.
Astro v3.0 muda a porta padrão para 4321
. 🚀
O que devo fazer?
Seção intitulada O que devo fazer?Atualize quaisquer referências a localhost:3000
, por exemplo em testes ou em seu README
, para refletir a nova porta localhost:4321
.
Padrão modificado: import.meta.env.BASE_URL trailingSlash
Seção intitulada Padrão modificado: import.meta.env.BASE_URL trailingSlashNo Astro v2.x, import.meta.env.BASE_URL
anexava sua opção base
com trailingSlash
por padrão. trailingSlash: "ignore"
também anexava com uma barra final.
Astro v3.0 não mais anexa import.meta.env.BASE_URL
com uma barra final por padrão, nem quando trailingSlash: "ignore"
é definido. (O comportamento existente de base
em combinação com trailingSlash: "always"
ou trailingSlash: "never"
não mudou.)
O que devo fazer?
Seção intitulada O que devo fazer?Se sua base
já tem uma barra final, nenhuma mudança é necessária.
Se sua base
não tem uma barra final, adicione uma se você deseja preservar o comportamento padrão anterior (ou trailingSlash: "ignore"
):
Padrão modificado: compressHTML
Seção intitulada Padrão modificado: compressHTMLNo Astro v2.x, Astro apenas comprimia seu HTML emitido quando compressHTML
era explicitamente definido como true
. O valor padrão era false
.
Astro v3.0 agora comprime HTML emitido por padrão.
O que devo fazer?
Seção intitulada O que devo fazer?Agora você pode remover compressHTML: true
de sua configuração já que esse é o novo comportamento padrão.
Agora você deve definir compressHTML: false
para optar por sair da compressão de HTML.
Padrão modificado: scopedStyleStrategy
Seção intitulada Padrão modificado: scopedStyleStrategyNo Astro v2.x, o valor padrão de scopedStyleStrategy
era "where"
.
Astro v3.0 introduz um novo valor padrão: "attribute"
. Por padrão, estilos agora são aplicados utilizando atributos data-*
.
O que devo fazer?
Seção intitulada O que devo fazer?Para manter o escopo dos estilos, atualize o arquivo de configuração para o valor padrão anterior:
Padrão modificado: inlineStyleSheets
Seção intitulada Padrão modificado: inlineStyleSheetsNo Astro v2.x, todas as folhas de estilo foram enviadas como tags link por padrão. Você poderia optar por adicioná-las inline em tags <style>
toda vez com "always"
, ou adicionar inline apenas folhas de estilo abaixo de um certo tamanho com "auto"
definindo a configuração build.inlineStylesheets
. A opção padrão era "never"
.
Astro v3.0 modifica o valor padrão de inlineStylesheets
para "auto"
. Folhas de estilo menores que ViteConfig.build.assetsInlineLimit
(padrão: 4kb) são adicionadas inline por padrão. Caso contrário, estilos do projeto eram enviados como folhas de estilo externas.
O que devo fazer?
Seção intitulada O que devo fazer?Se você quer manter o comportamento atual do seu projeto, defina build.inlineStylesheets
para o padrão anterior, "never"
:
Padrão modificado: serviço de imagem
Seção intitulada Padrão modificado: serviço de imagemNo Astro v2.x, Squoosh era o serviço padrão de processamento de imagem.
Astro v3.0 agora inclui Sharp como o novo serviço de processamento de imagem padrão e fornece uma opção da configuração para utilizar Squoosh no lugar.
O que devo fazer?
Seção intitulada O que devo fazer?Ao usar um gerenciador de pacotes rigoroso como o pnpm
, talvez seja necessário instalar o Sharp manualmente o seu projeto, mesmo que seja uma dependência do Astro:
Se você preferir continuar a usar Squoosh para transformar suas imagens, atualize sua configuração com o seguinte:
Modificado: Capitalização dos métodos de requisição HTTP
Seção intitulada Modificado: Capitalização dos métodos de requisição HTTPNo Astro v2.x, métodos de requisição HTTP eram escritos usando nomes de função em letras minúsculas: get
, post
, put
, all
e del
.
Astro v3.0 utiliza nomes de função em letras maiúsculas, incluindo DELETE
ao invés de del
.
O que devo fazer?
Seção intitulada O que devo fazer?Renomeie todas as funções para seus equivalentes em letras maiúsculas:
get
paraGET
post
paraPOST
put
paraPUT
all
paraALL
del
paraDELETE
Modificado: Configuração de múltiplos frameworks JSX
Seção intitulada Modificado: Configuração de múltiplos frameworks JSXNo Astro v2.x, você poderia utilizar múltiplas integrações de frameworks JSX (React, Solid, Preact) no mesmo projeto sem precisar identificar quais arquivos pertenciam a qual framework.
Astro v3.0 agora requer que você especifique qual framework utilizar para seus arquivos com as novas opções include
e exclude
da configuração de integrações quando você tiver integrações de frameworks JSX instaladas. Isso permite Astro suportar melhor o uso de um único framework, assim como funcionalidades avançadas como Fast Refresh do React.
O que devo fazer?
Seção intitulada O que devo fazer?Se você estiver utilizando múltiplos frameworks JSX no mesmo projeto, defina include
(e opcionalmente exclude
) como um array de arquivos e/ou pastas. Coringas podem ser utilizados para incluir o caminho de múltiplos arquivos.
Nós recomendamos colocar componentes de frameworks em comum na mesma pasta (e.x. /components/react/
e /components/solid/
) para fazer especificar suas inclusões mais fácil, mas isso não é necessário:
Modificado: Astro.cookies.get(key)
pode retornar undefined
Seção intitulada Modificado: Astro.cookies.get(key) pode retornar undefinedNo Astro v2.x, Astro.cookies.get(key)
sempre retornaria um objeto AstroCookie
, mesmo se o cookie não existisse. Para verificar sua existência, você precisava utilizar Astro.cookies.has(key)
.
Astro v3.0 retorna undefined
em Astro.cookies.get(key)
se o cookie não existir.
O que devo fazer?
Seção intitulada O que devo fazer?Esta mudança não irá quebrar nenhum código que verifica pela existência do objeto Astro.cookie
antes de utilizar Astro.cookies.get(key)
, mas não é mais necessário.
Você pode com segurança remover qualquer código que utiliza has()
para verificar se o valor de Astro.cookies
é undefined
:
Modificado: executando a CLI do Astro programaticamente
Seção intitulada Modificado: executando a CLI do Astro programaticamenteNo Astro v2.x, o entrypoint do pacote "astro"
exportava e executava a CLI do Astro diretamente. Não é recomendado executar Astro dessa forma na prática.
Astro v3.0 remove a CLI do entrypoint, e exporta um novo conjunto de APIs experimentais JavaScript, incluindo dev()
, build()
, preview()
e sync()
.
O que devo fazer?
Seção intitulada O que devo fazer?Para executar a CLI do Astro programaticamente, utilize as novas APIs JavaScript experimentais:
Modificado: caminhos de exportação do entrypoint interno da API do Astro
Seção intitulada Modificado: caminhos de exportação do entrypoint interno da API do AstroNo Astro v2.x, você poderia importar APIs internas do Astro a partir de astro/internal/*
e astro/runtime/server/*
.
Astro v3.0 remove os dois entrypoints em favor do entrypoint existente astro/runtime/*
. Adicionalmente, uma nova exportação astro/compiler-runtime
foi adicionada para código em runtime específico do compilador.
O que devo fazer?
Seção intitulada O que devo fazer?Esses entrypoints são para APIs internas do Astro e não devem afetar seu projeto. Mas se você utiliza esses entrypoints, atualize como mostrado abaixo:
Recursos da Comunidade
Seção intitulada Recursos da ComunidadeConhece um bom recurso para Astro v3.0? Edite esta página e adicione um link abaixo!
Problemas Conhecidos
Seção intitulada Problemas ConhecidosAtualmente, não há problemas conhecidos.
Upgrade Guides