Aggiorna alla v2 di Astro
Questa guida ti aiuterà a passare da Astro v1 ad Astro v2.
Hai bisogno di aggiornare un vecchio progetto a v1? Vedi la nostra vecchia guida alla migrazione (EN).
Aggiorna Astro
Sezione intitolata Aggiorna AstroAggiorna Astro all’ultima versione usando il tuo package manager. Se stai usando le integrazioni di Astro, aggiorna anche queste ultime alla versione più recente.
Astro v2.0 Cambiamenti principali
Sezione intitolata Astro v2.0 Cambiamenti principaliAstro v2.0 include alcuni cambiamenti importanti, come anche la rimozione di funzionalità obsolete. Se il tuo progetto non funziona come dovrebbe dopo l’aggiornamento alla v2.0, consulta questa guida per una panoramica di tutti i cambiamenti e le istruzioni su come aggiornare il tuo codice.
Vedi il registro delle modifiche per le note di rilascio complete.
Rimosso: Supporto di Node 14
Sezione intitolata Rimosso: Supporto di Node 14È previsto che nell’Aprile 2023 Node 14 concluderà il suo ciclo di vita.
Astro v2.0 non supporterà più Node 14, in modo che gli utenti di Astro possano trarre vantaggio dalle funzionalità più moderne di Node.
Cosa devo fare?
Sezione intitolata Cosa devo fare?Controlla che sia l’ambiente di sviluppo che l’ambiente di distribuzione stiano usando **Node 16.12.0
o versioni successive **.
-
Controlla la tua versione locale di Node usando:
Se il tuo ambiente di sviluppo locale ha bisogno di un aggiornamento, installa Node.
-
Controlla la documentazione del tuo ambiente di distribuzione (EN) per verificare che supporti Node 16.
Puoi specificare Node
16.12.0
per il tuo progetto Astro sia in un’impostazione della configurazione del pannello di controllo che in un file.nvmrc
.
Riservato: src/content/
Sezione intitolata Riservato: src/content/Astro v2.0 ora include l’API delle Collezioni per organizzare i tuoi file Markdown e MDX in raccolte di contenuti (EN). Questa API riserva src/content/
come cartella speciale.
Cosa devo fare?
Sezione intitolata Cosa devo fare?Cambia il nome alla cartella esistente src/content/
per evitare conflitti. Questa cartella, se esiste, ora può essere utilizzata solo per raccolte di contenuti (EN).
Cambiato: Astro.site
barra finale
Sezione intitolata Cambiato: Astro.site barra finaleNella versione 1.x, Astro assicurava che l’URL impostato come site
in astro.config.mjs
avesse sempre una barra finale quando si accedeva tramite Astro.site
.
Astro v2.0 non modifica più il valore di site
. Astro.site
utilizzerà il valore esatto che è stato definito e, se lo si desidera, la barra finale deve essere specificata.
Cosa devo fare?
Sezione intitolata Cosa devo fare?In astro.config.mjs
, aggiungi una barra finale all’URL impostato in site
.
Cambiato: Cartella _astro/
per asset della build
Sezione intitolata Cambiato: Cartella _astro/ per asset della buildNella v1.x, gli asset venivano creati in varie posizioni, tra cui assets/
, chunks/
e nella radice dell’output della build.
Astro v2.0 sposta e unisce la posizione di tutti gli assets in una nuova cartella _astro/
.
Directorydist/
Directory_astro
- client.9218e799.js
- index.df3f880e0.css
Puoi controllare questa posizione con la nuova opzione di configurazione build.assets
(EN).
Cosa devo fare?
Sezione intitolata Cosa devo fare?Aggiorna la configurazione della tua piattaforma di distribuzione se quest’ultima si basa sulla posizione degli assets.
Cambiato: Configurazione dei plugin di markdown
Sezione intitolata Cambiato: Configurazione dei plugin di markdownRimosso: extendDefaultPlugins
Sezione intitolata Rimosso: extendDefaultPluginsNella v1.x, Astro usava markdown.extendDefaultPlugins
per riattivare i plugin predefiniti di Astro quando venivano aggiunti dei propri plugin di Markdown.
Astro v2.0 rimuove questa opzione completamente perchè questo comportamento ora è predefinito.
L’applicazione di plug-in remark e rehype nella configurazione di Markdown non disabilita più i plug-in predefiniti di Astro. GitHub-Flavored Markdown e Smartypants ora vengono applicati indipendentemente dalla configurazione di remarkPlugins
o rehypePlugins
personalizzati.
Cosa devo fare?
Sezione intitolata Cosa devo fare?Rimuovi extendDefaultPlugins
nella tua configurazione. Ora questo è il comportamento predefinito di Astro nella v2.0, e puoi eliminare questa riga senza nessuna sostituzione.
Aggiunto: gfm
e smartypants
Sezione intitolata Aggiunto: gfm e smartypantsNella v1.x, potevi scegliere se disabilitare entrambi i plugin di Markdown di Astro predefiniti (GitHub-Flavored Markdown e SmartyPants) impostando markdown.extendDefaultPlugins: false
.
Astro v2.0 sostituisce markdown.extendDefaultPlugins: false
con delle opzioni booleane separate per controllare indipendentemente ognuno dei plugin Markdown di Astro. Questi sono abilitati di default e possono essere impostati su false
in modo indipendente.
Cosa devo fare?
Sezione intitolata Cosa devo fare?Rimuovi extendDefaultPlugins: false
e aggiungi dei flag per disabilitare ciascun plugin indipendentemente.
markdown.gfm: false
disabilita GitHub-Flavored Markdownmarkdown.smartypants: false
disabilita SmartyPants
Cambiato: Configurazione del plugin MDX
Sezione intitolata Cambiato: Configurazione del plugin MDXSostituito: extendPlugins
cambiato con extendMarkdownConfig
Sezione intitolata Sostituito: extendPlugins cambiato con extendMarkdownConfigNella v1.x, l’opzione extendPlugins
dell’integrazione MDX gestiva come i tuoi file MDX dovevano ereditare le configurazioni di Markdown: tutte le tue configurazioni di Markdown (markdown
), o solamente i plugin predefiniti di Astro (default
).
Astro v2.0 sostituisce questo comportamento controllato da mdx.extendPlugins
con tre nuove opzioni, configurabili indipendentemente, che sono impostate a true
:
mdx.extendMarkdownConfig
(EN) per ereditare tutte, o nessuna, le tue configurazioni di Markdownmdx.gfm
per abilitare e disabilitare GitHub-Flavored Markdown nei file MDXmdx.smartypants
per abilitare o disabilitare SmartyPants nei file MDX
Cosa devo fare?
Sezione intitolata Cosa devo fare?Elimina extendPlugins: 'markdown'
nella tua configurazione. Ora questo comportamento è predefinito.
Sostituisci extendPlugins: 'defaults'
con extendMarkdownConfig: false
e aggiungi le opzioni separate per GitHub-Flavored Markdown e SmartyPants per abilitare indipendentemente questi plugin predefiniti in MDX.
Aggiunto: Maggiori opzioni di configurazione di MDX per stare al passo con Markdown
Sezione intitolata Aggiunto: Maggiori opzioni di configurazione di MDX per stare al passo con MarkdownAstro v2.0 ti permette ora di impostare individualmente ogni possibile opzione di configurazione di Markdown (EN) (eccetto drafts
) separatamente nella configurazione della tua integrazione MDX.
Cosa devo fare?
Sezione intitolata Cosa devo fare?Rivedi le configurazioni di Markdown e MDX e confronta la tua configurazione con le nuove opzioni disponibili.
Cambiato: Accesso dei plugn all’avantesto
Sezione intitolata Cambiato: Accesso dei plugn all’avantestoNella v1.x, i plugin remark e rehype non avevano accesso all’avantesto dell’utente. Astro ha unito l’avantesto del plugin con l’avantesto del tuo file, senza dover passare l’avantesto del file ai tuoi plugin.
Astro v2.0 consente ai plugin remark e rehype l’accesso all’avantesto degli utenti tramite l’inserimento di avantesto. Ciò consente agli autori di plug-in di modificare l’avantesto esistente di un utente o di calcolare nuove proprietà basate su altre proprietà.
Cosa devo fare?
Sezione intitolata Cosa devo fare?Controlla qualsiasi plugin remark e rehype che hai scritto per vedere se il loro comportamento sia cambiato. Nota che data.astro.frontmatter
è adesso l’intero avantesto del documento Markdown o MDX, piuttosto che un oggetto vuoto.
Cambiato: Configurazione di RSS
Sezione intitolata Cambiato: Configurazione di RSSNella v1.x, il pacchetto RSS di Astro permetteva di usare items: import.meta.glob(...)
per generare un elenco di elementi del feed RSS. Questo utilizzo è ora obsoleto e sarà rimosso in futuro.
Astro v2.0 introduce un pagesGlobToRssItems()
wrapper alla proprietà items
.
Cosa devo fare?
Sezione intitolata Cosa devo fare?Importa la funzione helper pagesGlobToRssItems()
, dopodiché passa la funzione esistente che utilizza import.meta.glob()
come argomento all’helper stesso.
Cambiato: Supporto di Svelte per l’IDE
Sezione intitolata Cambiato: Supporto di Svelte per l’IDESe stai usando l’integrazione @astrojs/svelte
(EN) devi includere il file svelte.config.js
nel tuo progetto . Ciò è necessario per fornire il completamento automatico dell’IDE.
Cosa devo fare?
Sezione intitolata Cosa devo fare?Aggiungi il file svelte.config.js
alla radice del tuo progetto:
Per i nuovi utenti, questo file sarà aggiunto automaticamente con l’esecuzione di astro add svelte
.
Rimosso: legacy.astroFlavoredMarkdown
Sezione intitolata Rimosso: legacy.astroFlavoredMarkdownGià nella v1.0, Astro aveva dichiarato come deprecato il vecchio Astro-Flavored Markdown (conosciuto anche come Components in Markdown).
Astro v2.0 rimuove l’opzione legacy.astroFlavoredMarkdown
completamente. Importare e usare componenti nei file .md
non funzionerà più.
Cosa devo fare?
Sezione intitolata Cosa devo fare?Rimuovi questo flag. Non è più disponibile in Astro.
Se stavi usando questa funzionalità nella v1.x, suggeriamo di usare l’integrazione di MDX (EN) che ti permette di combinare componenti ed espressioni JSX con la sintassi di Markdown.
Rimosso: Astro.resolve()
Sezione intitolata Rimosso: Astro.resolve()Nella v0.24, Astro ha deprecato Astro.resolve()
per ottenere gli URL determinati delle risorse a cui potresti voler fare riferimento nel browser.
Astro v2.0 rimuove questa opzione completamente. L’utilizzo di Astro.resolve()
nel tuo codice provocherà un errore.
Cosa devo fare?
Sezione intitolata Cosa devo fare?Determina i percorsi delle risorse utilizzando invece import
. Per esempio:
Rimosso: Astro.fetchContent()
Sezione intitolata Rimosso: Astro.fetchContent()Nella v0.26, Astro ha deprecato Astro.fetchContent()
per il recupero dei dati dai file Markdown locali.
Astro v2.0 rimuove questa opzione completamente. L’utilizzo di Astro.fetchContent()
nel tuo codice provocherà un errore.
Cosa devo fare?
Sezione intitolata Cosa devo fare?Usa Astro.glob()
(EN) per recuperare i file di Markdown, oppure passa alla funzionalità Collezione di Contenuti (EN).
Rimosso: Astro.canonicalURL
Sezione intitolata Rimosso: Astro.canonicalURLNella v1.0, Astro ha deprecato Astro.canonicalURL
per costruire un URL canonico.
Astro v2.0 rimuove questa opzione completamente. L’utilizzo di Astro.canonicalURL
nel tuo codice provocherà un errore.
Cosa devo fare?
Sezione intitolata Cosa devo fare?Usa Astro.url
per costruire un URL canonico.
Aggiornato: Vite 4
Sezione intitolata Aggiornato: Vite 4Astro v2.0 passa da Vite 3 a Vite 4, rilasciato a Dicembre 2022.
Cosa devo fare?
Sezione intitolata Cosa devo fare?Non dovrebbero essere necessarie modifiche al codice! Abbiamo gestito al tuo posto la maggior parte dell’aggiornamento all’interno di Astro; tuttavia, alcuni sottili comportamenti di Vite possono ancora cambiare tra le versioni.
Fai riferimento alla Guida ufficiale per la Migrazione di Vite se dovessi incontrare dei problemi.
Flag Sperimentali rimossi in Astro v2.0
Sezione intitolata Flag Sperimentali rimossi in Astro v2.0Rimuovi i seguenti flag da astro.config.mjs
:
Queste funzionalità sono ora disponibili di default:
- Collezioni di Contenuti (EN) come un modo per gestire i tuoi file Markdown e MDX con la sicurezza dei tipi di dati.
- Prerendering delle pagine individuali in HTML statico (EN) quando si utilizza SSR (rendering lato server) per migliorare la velocità e il caching.
- Un overlay dei messaggi di errore riprogettato.
Problemi conosciuti
Sezione intitolata Problemi conosciutiAttualmente non ci sono problemi conosciuti.
Upgrade Guides