Pular para o conteúdo
Astro Astro

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

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

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!

Mudanças Radicais do Astro v3.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.

Removido: Suporte para o Node 16

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.

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.

  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

Removido: Suporte para TypeScript 4

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

O que devo fazer?

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

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

Removido: @astrojs/image

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.

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!

astro.config.mjs
import { defineConfig } from 'astro/config';
import image from '@astrojs/image';


export default defineConfig({
  integrations: [
    image(),
  ]
})

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?

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.

Removido: APIs depreciadas da 1.x

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.

O que devo fazer?

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

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.

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

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.

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:

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

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.

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

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.

O que devo fazer?

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

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

O que devo fazer?

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

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>

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:

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

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 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 (EN) será providenciado se você precisa atualizar seu código.

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.

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

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.

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.

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
     }),
});

Depreciado: markdown.drafts

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.

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

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.

O que devo fazer?

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

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.

O que devo fazer?

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

Padrão modificado: porta 3000

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

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

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

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

astro.config.mjs
import { defineConfig } from "astro/config";


export default defineConfig({
  base: 'minha-base',
  base: 'minha-base/',
});

Padrão modificado: compressHTML

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.

O que devo fazer?

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

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

O que devo fazer?

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

Padrão modificado: inlineStyleSheets

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.

O que devo fazer?

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

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.

O que devo fazer?

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

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.

O que devo fazer?

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

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.

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:

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

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.

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:

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

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

O que devo fazer?

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

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.

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:

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',
  // ...
});

Recursos da Comunidade

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

Problemas Conhecidos

Atualmente, não há problemas conhecidos.