Pular para o conteúdo

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

Terminal window
# Atualize para Astro v3.x
npm install astro@latest
# Exemplo: atualize as integrações React e Tailwind
npm install @astrojs/react@latest @astrojs/tailwind@latest

Flags Experimentais Removidas do Astro v3.0

Seção intitulada Flags Experimentais Removidas do Astro v3.0

Remova as seguintes flags experimentais de astro.config.mjs:

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
assets: true,
viewTransitions: true,
},
})

Essas funcionalidades agora estão disponíveis por padrão:

Leia mais sobre essas duas funcionalidades eletrizantes e mais na postagem do blog sobre a 3.0!

Astro 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.

Node 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.

Verifique eu tanto seu ambiente de desenvolvimento quanto seu ambiente de deployment estão utilizando Node 18.14.1 ou superior.

  1. Verifique sua versão local do Node utilizando:

    Terminal window
    node -v
  2. 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.

    .nvmrc
    18.14.1

Na 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).

Se você tem o TypeScript instalado localmente, atualize pelo menos para a v5.0.

Terminal window
npm install typescript@latest --save-dev

No 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.

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!

astro.config.mjs
import { defineConfig } from 'astro/config';
import image from '@astrojs/image';
export default defineConfig({
integrations: [
image(),
]
})

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.

Remova todas as instâncias de @astrojs/markdown-component.

src/components/MeuComponenteAstro.astro
---
import Markdown from '@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.

No 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.

Se você continua utilizando APIs da v1.x, utilize as novas APIs para cada uma das funcionalidades no lugar:

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 servidor

No 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.

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údo

No 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.

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:

src/content/config.ts
import { defineCollection, z, image } from "astro:content";
import { defineCollection, z } from "astro:content";
defineCollection({
schema: ({ image }) =>
z.object({
image: image(),
}),
});

Removido: nomes de temas do Shiki pré-0.14

Seção intitulada Removido: nomes de temas do Shiki pré-0.14

No 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.

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:list

No 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.

Substitua quaisquer elementos Set passados para a diretiva class:list com um Array plano.

src/components/MeuComponenteAstro.astro
<Componente class:list={[
'a',
'b',
new Set(['c', 'd'])
['c', 'd']
]} />

Removido: passar class:list como uma prop

Seção intitulada Removido: passar class:list como uma prop

No 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']

Remova qualquer código que espera receber a prop class:list.

src/components/MeuComponenteAstro.astro
---
import { clsx } from 'clsx';
const { class: className, 'class:list': classList } = Astro.props;
const { class: className } = Astro.props;
---
<div
class:list={[className, classList]}
class:list={[className]}
/>

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

No 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.

src/components/MeuComponenteAstro.astro
---
const meuValor = "red"
---
<!-- input -->
<div style={{ "--meuValor": meuValor }}></div>
<!-- resultado (Astro 2.x) -->
<div style="--meu-valor:var(--meuValor);--meuValor:red"></div>
<!-- resultado (Astro 3.0) -->
<div style="--meuValor:red"></div>

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:

src/components/MeuComponenteAstro.astro
<style>
div {
color: var(--meu-valor);
color: var(--meuValor);
}
</style>

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().

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 externo

No 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.

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.split

No 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.

Atualize o arquivo de configuração do Astro para agora utilizar as novas opções na configuração do adaptador diretamente.

astro.config.mjs
import { defineConfig } from "astro/config";
import vercel from "@astrojs/vercel/serverless";
export default defineConfig({
build: {
excludeMiddleware: true
},
adapter: vercel({
edgeMiddleware: true
}),
});
astro.config.mjs
import { defineConfig } from "astro/config";
import netlify from "@astrojs/netlify/functions";
export default defineConfig({
build: {
split: true
},
adapter: netlify({
functionPerRoute: true
}),
});

No 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.

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 endpoints

No 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.

Atualize seus endpoints para reotrnar um objeto Response diretamente.

endpoint.json.ts
export async function GET() {
return { body: { "titulo": "Blog do Bob" }};
return new Response(JSON.stringify({ "titulo": "Blog do Bob" }));
}

Se você realmente precisar manter o formato anterior, você pode utilizar o objeto ResponseWithEncoding, mas isso será depreciado no futuro.

endpoint.json.ts
export async function GET() {
return { body: { "titulo": "Blog do Bob" } };
return new ResponseWithEncoding({ body: { "titulo": "Blog do Bob" }});
}

Padrão alterado: verbatimModuleSyntax nas predefinições de tsconfig.json

Seção intitulada Padrão alterado: verbatimModuleSyntax nas predefinições de tsconfig.json

No 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.

Esta opção requer que os tipos sejam importados usando a sintaxe import type.

src/components/MeuComponenteAstro.astro
---
import { type CollectionEntry, getEntry } from "astro:content";
---

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.

tsconfig.json
{
"compilerOptions": {
"verbatimModuleSyntax": false
}
}

No Astro v2.x, Astro era executado na porta 3000 por padrão.

Astro v3.0 muda a porta padrão para 4321. 🚀

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 trailingSlash

No 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.)

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"):

astro.config.mjs
import { defineConfig } from "astro/config";
export default defineConfig({
base: 'minha-base',
base: 'minha-base/',
});

No 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.

Agora você pode remover compressHTML: true de sua configuração já que esse é o novo comportamento padrão.

astro.config.mjs
import { defineConfig } from "astro/config";
export default defineConfig({
compressHTML: true
})

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: scopedStyleStrategy

No 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-*.

Para manter o escopo dos estilos, atualize o arquivo de configuração para o valor padrão anterior:

astro.config.mjs
import { defineConfig } from "astro/config";
export default defineConfig({
scopedStyleStrategy: "where"
})

No 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.

Se você quer manter o comportamento atual do seu projeto, defina build.inlineStylesheets para o padrão anterior, "never":

astro.config.mjs
import { defineConfig } from "astro/config";
export default defineConfig({
build: {
inlineStylesheets: "never"
}
})

Padrão modificado: serviço de imagem

Seção intitulada Padrão modificado: serviço de imagem

No 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.

Se você preferir continuar a usar Squoosh para transformar suas imagens, atualize sua configuração com o seguinte:

astro.config.mjs
import { defineConfig, squooshImageService } from "astro/config";
export default defineConfig({
image: {
service: squooshImageService(),
}
})

Modificado: Capitalização dos métodos de requisição HTTP

Seção intitulada Modificado: Capitalização dos métodos de requisição HTTP

No 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.

Renomeie todas as funções para seus equivalentes em letras maiúsculas:

  • get para GET
  • post para POST
  • put para PUT
  • all para ALL
  • del para DELETE
endpoint.ts
export function get() {
export function GET() {
return new Response(JSON.stringify({ "titulo": "Blog do Bob" }));
}

Modificado: Configuração de múltiplos frameworks JSX

Seção intitulada Modificado: Configuração de múltiplos frameworks JSX

No 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.

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:

import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';
import solid from '@astrojs/solid-js';
export default defineConfig({
// Habilite múltiplos frameworks a suportarem todos os tipos de componentes.
// Nenhum `include` é necessário se você está usando apenas um único framework!
integrations: [
preact({
include: ['**/preact/*']
}),
react({
include: ['**/react/*']
}),
solid({
include: ['**/solid/*'],
}),
]
});

Modificado: Astro.cookies.get(key) pode retornar undefined

Seção intitulada Modificado: Astro.cookies.get(key) pode retornar undefined

No 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.

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:

if (Astro.cookies.has(id)) {
const id = Astro.cookies.get(id)!;
}
const id = Astro.cookies.get(id);
if (id) {
}

Modificado: executando a CLI do Astro programaticamente

Seção intitulada Modificado: executando a CLI do Astro programaticamente

No 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().

Para executar a CLI do Astro programaticamente, utilize as novas APIs JavaScript experimentais:

import { dev, build } from "astro";
// Inicie o servidor de desenvolvimento do Astro
const devServer = await dev();
await devServer.stop();
// Faça a build do seu projeto Astro
await build();

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 Astro

No 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.

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:

import 'astro/internal/index.js';
import 'astro/runtime/server/index.js';
import 'astro/server/index.js';
import 'astro/runtime/server/index.js';
import { transform } from '@astrojs/compiler';
const resultado = await transform(source, {
internalURL: 'astro/runtime/server/index.js',
internalURL: 'astro/compiler-runtime',
// ...
});

Conhece um bom recurso para Astro v3.0? Edite esta página e adicione um link abaixo!

Atualmente, não há problemas conhecidos.