08. Reference rapida, errori comuni e migrazione

← 07 - Immagini, font, SEO, performance e deploy · Indice

8.1 Cheatsheet

CLI

npm create astro@latest          # nuovo progetto
astro dev                        # dev server (--background, --ignore-lock)
astro build                      # build (--force svuota la cache dei contenuti)
astro preview                    # serve dist/
astro check                      # type-check dei .astro
astro sync                       # rigenera i tipi
astro add <integrazione>         # installa e configura
astro info                       # dump ambiente
astro create-key                 # chiave per le server island
npx @astrojs/upgrade             # aggiorna Astro e le integrazioni

Import che userai ogni giorno

import { getCollection, getEntry, getEntries, render, reference } from 'astro:content';
import { Image, Picture, Font, getImage } from 'astro:assets';
import { Code } from 'astro:components';
import { ClientRouter } from 'astro:transitions';
import { navigate } from 'astro:transitions/client';
import { defineMiddleware, sequence } from 'astro:middleware';
import { actions, isInputError, ActionError } from 'astro:actions';
import { getRelativeLocaleUrl } from 'astro:i18n';
import { z } from 'astro/zod';
import { glob, file } from 'astro/loaders';
import { defineConfig, envField, fontProviders, sessionDrivers } from 'astro/config';

Direttive

Direttiva	Dove	Cosa fa
client:load|idle|visible|media|only	componenti framework	idratazione
server:defer	componenti .astro	server island
transition:name|animate|persist	qualsiasi elemento	view transitions
is:global	<style>	disattiva lo scoping
is:inline	<script>/<style>	niente processing né bundling
is:raw	qualsiasi elemento	i figli sono testo, {} non interpretato
set:html / set:text	qualsiasi elemento	inietta HTML (non escapato) / testo
define:vars	<style>/<script>	passa variabili (su script implica is:inline)
class:list	qualsiasi elemento	array/oggetto → stringa di classi

Configurazione minima sensata

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import sitemap from '@astrojs/sitemap';
 
export default defineConfig({
  site: 'https://esempio.it',
  integrations: [mdx(), sitemap()],
  markdown: {
    shikiConfig: { themes: { light: 'github-light', dark: 'github-dark' } },
  },
  image: { layout: 'constrained', responsiveStyles: true },
  prefetch: true,
});

8.2 Errori comuni, in ordine di frequenza

1. entry.render() non è una funzione API di Astro 4. Oggi: import { render } from 'astro:content' e await render(entry).

2. Le pagine annidate della collection non vengono generate La rotta è [id].astro: gli id con / non matchano. Serve [...id].astro.

3. Il CSS non colpisce il contenuto Markdown Gli stili sono scoped e l’HTML generato dal Markdown non ha l’attributo di scope. Usa :global(...) oppure uno <style is:global>.

4. Astro.site è undefined Manca site in astro.config.mjs. Rompe sitemap, RSS e canonical, in silenzio.

5. Il testo tra due elementi inline si è “attaccato” dopo l’aggiornamento a 7 compressHTML è passato da true a 'jsx': gli a-capo tra elementi inline non producono più uno spazio. Metti lo spazio esplicito, {' '}, oppure torna a compressHTML: true.

6. La build fallisce dopo l’aggiornamento a 7, con errori sui plugin markdown @astrojs/markdown-remark non è più installato di default. O lo installi e usi processor: unified(), o porti i plugin sull’API Sätteri.

7. client:load su un componente .astro Errore, non svista tollerata: i .astro non hanno runtime client. Usa <script>.

8. Lo script smette di funzionare dopo aver aggiunto <ClientRouter /> Gli script bundlati girano una volta sola. Registra dentro astro:page-load.

9. import ViewTransitions from 'astro:transitions' Rimosso in Astro 6. Si chiama ClientRouter.

10. Immagini enormi in produzione Sono in public/, dove non vengono ottimizzate. Spostale in src/ e usa <Image />.

11. Il frontmatter ha un typo e nessuno se ne accorge Stai usando src/pages/*.md invece delle collection. Vedi il modulo 4.

12. La build dice “unclosed tag” su codice che prima funzionava Il compilatore Rust di Astro 7 non corregge più l’HTML malformato. Chiudi il tag.

8.3 Differenze rispetto ad Astro 4 (per leggere i tutorial vecchi)

Argomento	Astro 4	Astro 7
Config collection	src/content/config.ts	src/content.config.ts
Definizione	defineCollection({ type, schema })	defineCollection({ loader, schema })
Posizione contenuti	obbligatoria in src/content/	ovunque, decide il loader
Identificatore	entry.slug	entry.id
Rendering	await entry.render()	await render(entry)
Lookup	getEntryBySlug()	getEntry(collection, id)
File _bozza.md	esclusi per convenzione	serve pattern: '**/[^_]*.md'
output	static | hybrid | server	static | server (hybrid rimosso)
prerender dinamico	supportato	solo true/false letterali
Glob dei contenuti	Astro.glob()	import.meta.glob() (Astro.glob rimosso)
View transitions	<ViewTransitions />	<ClientRouter />
Tailwind	@astrojs/tailwind	@tailwindcss/vite (astro add tailwind)
Motore Markdown	remark/rehype	Sätteri (Rust); remark opzionale
Plugin markdown	remarkPlugins/rehypePlugins	mdastPlugins/hastPlugins
ID degli heading	plugin rehype-slug	nativi
Compilatore .astro	Go, tollerante	Rust, severo
compressHTML	true	'jsx'
Node	18.17+	22.12+
Zod	v3 (z.string().email())	v4 (z.email()), da astro/zod
Session driver	driver: 'redis'	driver: sessionDrivers.redis({...})

Guida ufficiale all’aggiornamento (leggila prima di migrare un progetto reale): 📖 Upgrade to v5 · v6 · v7

8.4 Cosa c’è di nuovo in Astro 7 (in due minuti)

• Vite 8 + Rolldown e compilatore Rust: build dichiarate 15-61% più veloci.
• Sätteri: pipeline Markdown nativa in Rust, con GFM, ID degli heading, math e wikilink inclusi.
• Route caching stabile: cache + routeRules in configurazione, Astro.cache a runtime.
• Advanced routing stabile: src/fetch.ts per controllare l’intera pipeline (e astro/hono se preferisci Hono).
• Logger strutturato e --json.
• astro dev --background con status/stop/logs.
• Rimosso @astrojs/db; rimossi gli internals di astro:transitions.
• 7.1: URL di paginazione personalizzabili, CSP più granulare, dev server multipli.
• 7.2: build statiche incrementali (sperimentali), session: false, astro preview --background.

8.5 Dove continuare

• Tutorial ufficiale “Build a blog”: se non l’hai fatto, fallo.
• Docs: reference quotidiana.
• Blog ufficiale: i “What’s new in Astro” mensili.
• Starlight: per documentazione strutturata.
• Astro Tips: ricette avanzate della community.
• Themes: template da leggere, più che da usare: è il modo più veloce per vedere come sono organizzati progetti reali.
• Discord ufficiale: la community è attiva e risponde.

8.6 Nota di manutenzione di queste note

Materiale scritto il 19 agosto 2026 su Astro 7.2.3. Gli snippet marcati ✅ sono stati eseguiti in un progetto reale con build completata; gli altri provengono dalla documentazione ufficiale.

Astro rilascia una major all’anno circa e minor frequenti. Quando aggiorni, controlla la guida di upgrade e correggi qui quello che cambia: una nota tecnica sbagliata è peggio di una nota assente, perché ti fidi.

Punti su cui questa raccolta è deliberatamente cauta perché la documentazione non era univoca al momento della scrittura:

• la propagazione di paginate({ format }) sui link prev/next;
• la compatibilità dichiarata di astro-expressive-code con Astro 7;
• lo stato (stabile o sperimentale) delle live collections;
• l’elenco completo dei sessionDrivers disponibili.