Pular para o conteúdo

Atualize para o Astro v2

Este guia irá ajudá-lo a migrar seu projeto do Astro v1 para Astro v2.

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

Atualize a versão do Astro do seu projeto para a mais recente utilizando seu gerenciador de pacotes. Se você estiver utilizando integrações Astro, por favor também as atualize para a versão mais recente.

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

Astro v2.0 contém algumas mudanças radicais, assim como a remoção de algumas funcionalidades previamente descontinuadas. Se o seu projeto não funciona como esperado após atualizar para a v2.0, veja este guia para uma visão geral de todas as mudanças radicais e instruções em como atualizar sua base de código.

Veja o histórico de mudanças para notas completas dos lançamentos.

Node 14 está agendado para alcançar o seu End of Life (em português, “Fim de Vida”) em Abril de 2023.

Astro v2.0 remove suporte para Node 14 completamente, para que todos os usuários do Astro possam tirar vantagem das funcionalidades mais modernas do Node.

Verifique seu ambos seu ambiente de desenvolvimento e de deploy estão utilizando Node 16.12.0 ou posterior.

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

    Terminal window
    node -v

    Se o seu ambiente de desenvolvimento local precisa ser atualizado, instale o Node.

  2. Verifique a própria documentação do seu ambiente de deploy para verificar que eles suportam Node 16.

    Você pode especificar Node 16.12.0 para o seu projeto Astro tanto em uma opção da configuração do painel de controle, ou em um arquivo .nvmrc.

Astro v2.0 agora inclui a API de Coleções para organizar seus arquivos Markdown e MDX em coleções de conteúdo. Esta API reserva src/content/ como uma pasta especial.

Renomeie uma pasta src/content/ existente para evitar conflitos. Esta pasta, se ela existir, agora pode apenas ser utilizada para coleções de conteúdo.

Na v1.x, Astro garantia que a URL que você definia como site em astro.config.mjs sempre tivesse uma barra final quando acessado utilizando Astro.site.

Astro v2.0 não mais modifica o valor de site. Astro.site irá utilizar o valor exatamente definido e a barra final deve ser especificada se desejada.

Em astro.config.mjs, adicione uma barra final a URL definida em site.

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
site: 'https://exemplo.com',
site: 'https://exemplo.com/',
});

Modificado: pasta _astro/ para assets da build

Seção intitulada Modificado: pasta _astro/ para assets da build

Na v1.x, assets eram construídos em várias localizações, incluindo assets/, chunks/ e na raiz do resultado da build.

Astro v2.0 move e unifica a localização de todos os assets resultantes da build para a nova pasta _astro/.

  • Diretóriodist/
    • Diretório_astro
      • client.9218e799.js
      • index.df3f880e0.css

Você pode controlar essa localização com a nova opção build.assets da configuração.

Atualize a configuração da sua plataforma de deploy se ela depende da localização desses assets.

Modificado: configuração de plugins Markdown

Seção intitulada Modificado: configuração de plugins Markdown

Na v1.x, Astro utilizava markdown.extendDefaultPlugins para reabilitar os plugins padrões do Astro quando se adiciona seus próprios plugins Markdown.

Astro v2.0 remove essa opção da configuração completamente pois seu comportamento agora é o padrão.

Aplicar plugins remark e rehype em sua configuração de Markdown não mais desabilita os plugins padrões do Astro. GitHub-Flavored Markdown e Smartypants agora são aplicados independente de plugins remarkPlugins ou rehypePlugins customizados serem configurados.

Remova extendDefaultPlugins da sua configuração. Agora este é o comportamento padrão do Astro na v2.0 e você pode deletar essa linha sem nenhuma substituição.

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
markdown: {
extendDefaultPlugins,
}
});

Na v1.x, você poderia escolher em desabilitar ambos os plugins Markdown padrões do Astro (GitHub-Flavored Markdown e SmartyPants) ao definir markdown.extendDefaultPlugins: false.

Astro v2.0 modifica markdown.extendDefaultPlugins: false com opções Boolean separadas para individualmente controlar cada um dos plugins Markdown padrões do Astro. Eles são habilitados por padrão e podem ser definidos como false independentemente.

Remova extendDefaultPlugins: false e adicione as flags para desabilitar cada plugin individualmente no lugar.

  • markdown.gfm: false desabilita GitHub-Flavored Markdown
  • markdown.smartypants: false desabilita SmartyPants
astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
markdown: {
extendDefaultPlugins: false,
smartypants: false,
gfm: false,
}
});

Modificado: configurações de plugins MDX

Seção intitulada Modificado: configurações de plugins MDX

Substituído: extendPlugins modificado para extendMarkdownConfig

Seção intitulada Substituído: extendPlugins modificado para extendMarkdownConfig

Na v1.x, a opção extendPlugins da integração MDX gerenciava como seus arquivos MDX deviam herdar sua configuração Markdown: toda sua configuração Markdown (markdown) ou apenas plugins padrões do Astro (default).

Astro v2.0 substitui o comportamento controlado por mdx.extendPlugins com três novas opções independentemente configuráveis que são true por padrão:

  • mdx.extendMarkdownConfig para herdar tudo ou nada da sua configuração Markdown
  • mdx.gfm para habilitar ou desabilitar GitHub-Flavored Markdown no MDX
  • mdx.smartypants para habilitar ou desabilitar SmartyPants no MDX

Delete extendPlugins: 'markdown' na sua configuração. Este é o novo comportamento padrão.

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

Substitua extendPlugins: 'defaults' com extendMarkdownConfig: false e adicione as opções separadas para GitHub-Flavored Markdown e SmartyPants para habilitar esses plugins padrões individualmente no MDX.

astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
integrations: [
mdx({
extendPlugins: 'defaults',
extendMarkdownConfig: false,
smartypants: true,
gfm: true,
}),
],
});

Adicionado: Mais opções de configuração MDX para se igualar ao Markdown

Seção intitulada Adicionado: Mais opções de configuração MDX para se igualar ao Markdown

Astro v2.0 permite que você agora defina individualmente cada opção da configuração Markdown disponível (exceto drafts) separadamente na sua configuração da integração MDX.

astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
markdown: {
remarkPlugins: [remarkPlugin1],
gfm: true,
},
integrations: [
mdx({
remarkPlugins: [remarkPlugin2],
gfm: false,
})
]
});

Revisite a sua configuração Markdown e MDX e compare sua configuração existente com as novas opções disponíveis.

Modificado: Acesso de plugins ao frontmatter

Seção intitulada Modificado: Acesso de plugins ao frontmatter

Na v1.x, plugins remark e rehype não haviam acesso ao frontmatter do usuário. Astro juntava o frontmatter de plugins com o frontmatter de seu arquivo, sem passar o frontmatter do arquivo para seus plugins.

Astro v2.0 dá acesso para plugins rehype e remark ao frontmatter do usuário através de injeção de frontmatter. Isso permite autores de plugins modificarem o frontmatter existente de um usuário ou computar novas propriedades com base em outras propriedades.

Verifique quaisquer plugins remark e rehype que você escreveu para ver se seus comportamentos foram modificados. Note que data.astro.frontmatter agora é o frontmatter completo do documento Markdown ou MDX, ao invés de ser um objeto vazio.

Na v1.x, o pacote de RSS do Astro permitia que você utilizasse items: import.meta.glob(...) para gerar uma lista de itens de feed RSS. Esse uso agora foi descontinuado e será eventualmente removido.

Astro v2.0 introduz a função pagesGlobToRssItems() que envolve a propriedade items.

Importe e então envolva sua função existente contendo import.meta.glob() com o utilitário pagesGlobToRssItems().

src/pages/rss.xml.js
import rss, {
pagesGlobToRssItems
} from '@astrojs/rss';
export async function get(context) {
return rss({
items: await pagesGlobToRssItems(
import.meta.glob('./blog/*.{md,mdx}'),
),
});
}

Modificado: Suporte em IDE para Svelte

Seção intitulada Modificado: Suporte em IDE para Svelte

Astro v2.0 requer um arquivo svelte.config.js em seu projeto se você estiver utilizando a integração @astrojs/svelte. Isso é necessário para fornecer preenchimento automático na IDE.

Adicione um arquivo svelte.config.js a raiz do seu projeto:

svelte.config.js
import { vitePreprocess } from '@astrojs/svelte';
export default {
preprocess: vitePreprocess(),
};

Para novos usuários, esse arquivo será adicionado automaticamente ao executar astro add svelte.

Removido: legacy.astroFlavoredMarkdown

Seção intitulada Removido: legacy.astroFlavoredMarkdown

Na v1.0, Astro moveu o antigo Markdown Estilo-Astro (também conhecido como Componentes em Markdown) para uma funcionalidade legado.

Astro v2.0 remove a opção legacy.astroFlavoredMarkdown completamente. Importar e utilizar componentes em arquivos .md não irá mais funcionar.

Remova essa flag legado. Ela não está mais disponível no Astro.

astro.config.mjs
export default defineConfig({
legacy: {
astroFlavoredMarkdown: true,
},
})

Se você esteve utilizando essa funcionalidade na v1.x, nós recomendamos utilizar a integração MDX que permite que você combine componentes e expressões JSX com a sintaxe do Markdown.

Na v0.24, Astro descontinuou Astro.resolve() para conseguir URLs resolvidas de assets que você gostaria de referenciar no navegador.

Astro v2.0 remove esta opção completamente. Astro.resolve() no seu código irá causar um erro.

Resolva caminhos de assets utilizando import no lugar. Por exemplo:

src/pages/index.astro
---
import 'estilo.css';
import urlImagem from './imagem.png';
---
<img src={urlImagem} />

Na v0.26, Astro descontinuou Astro.fetchContent() para buscar dados de seus arquivos Markdown locais.

Astro v2.0 remove esta opção completamente. Astro.fetchContent() no seu código irá causar um erro.

Use Astro.glob() para buscar arquivos Markdown ou converta para a funcionalidade Coleções de Conteúdo.

src/pages/index.astro
---
const todasPostagens = await Astro.glob('./postagens/*.md');
---

Na v1.0, Astro descontinuou Astro.canonicalURL para construir uma URL canônica.

Astro v2.0 remove esta opção completamente. Astro.canonicalURL no seu código irá causar um erro.

Use Astro.url para construir uma URL canônica.

src/pages/index.astro
---
const urlCanonica = new URL(Astro.url.pathname, Astro.site);
---

Astro v2.0 atualiza do Vite 3 para Vite 4, lançado em Dezembro de 2022.

Não deve haver mudanças necessárias no seu código! Nós lidamos com a maioria da atualização para você dentro do Astro; porém, alguns comportamentos sutis do Vite ainda podem mudar entre versões.

Recorra ao oficial Guia de Migração do Vite se você tiver algum problema.

Flags Experimentais do Astro v2.0 Removidas

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

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

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

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

Atualmente, não há problemas conhecidos.