Struttura del progetto

Il tuo nuovo progetto Astro generato dalla procedura guidata CLI create astro include già alcuni file e cartelle. Altri, li creerai tu stesso e li aggiungerai alla struttura di file esistente di Astro.

Ecco come è organizzato un progetto Astro e alcuni file che troverai nel tuo nuovo progetto.

Directory e file

Astro sfrutta un layout di cartelle supponente per il tuo progetto. Ogni root del progetto Astro dovrebbe includere le seguenti directory e file:

• src/* - Il codice sorgente del tuo progetto (componenti, pagine, stili, ecc.)
• public/* - Le tue risorse non codificate e non elaborate (caratteri, icone, ecc.)
• package.json - Un manifesto del progetto.
• astro.config.mjs - Un file di configurazione Astro. (consigliato)
• tsconfig.json - Un file di configurazione TypeScript. (consigliato)

Esempio di albero del progetto

Una directory di progetto Astro comune potrebbe assomigliare a questa:

• Cartellapublic/

  • robots.txt
  • favicon.svg
  • social-image.png
• Cartellasrc/

  • Cartellacomponents/

    • Header.astro
    • Button.jsx
  • Cartellalayouts/

    • PostLayout.astro
  • Cartellapages/

    • Cartellaposts/

      • post1.md
      • post2.md
      • post3.md
    • index.astro
  • Cartellastyles/

    • global.css
• astro.config.mjs
• package.json
• tsconfig.json

src/

La cartella src/ è dove risiede la maggior parte del codice sorgente del tuo progetto. Ciò comprende:

• Pagine
• Layout
• Componenti Astro
• Componenti del framework UI (React, ecc.)
• Stili (CSS, Sass) (EN)
• Markdown (EN)

Astro elabora, ottimizza e raggruppa i tuoi file src/ per creare il sito Web finale che viene inviato al browser. A differenza della directory statica public/, i tuoi file src/ sono creati e gestiti per te da Astro.

Alcuni file (come i componenti Astro) non vengono nemmeno inviati al browser come scritti ma vengono invece renderizzati in HTML statico. Altri file (come CSS) vengono inviati al browser ma possono essere ottimizzati o raggruppati con altri file CSS per migliorare le prestazioni.

Consiglio

Sebbene questa guida descriva alcune convenzioni popolari utilizzate nella comunità Astro, le uniche directory riservate da Astro sono src/pages/ e src/content/. Sei libero di rinominare e riorganizzare qualsiasi altra directory nel modo che funziona meglio per te.

src/components

I componenti sono unità di codice riutilizzabili per le tue pagine HTML. Questi potrebbero essere componenti Astro o componenti del framework UI come React o Vue. È prassi comune raggruppare e organizzare tutti i componenti del progetto in questa cartella.

Questa è una convenzione comune nei progetti Astro, ma non è richiesta. Sentiti libero di organizzare i tuoi componenti come preferisci!

src/content

La directory src/content/ è riservata per archiviare le raccolte di contenuti (EN) e un file di configurazione delle raccolte opzionale. Nessun altro file è consentito all’interno di questa cartella.

src/layouts

I layout sono componenti Astro che definiscono la struttura dell’interfaccia utente condivisa da una o più pagine.

Proprio come src/components, questa directory è una convenzione comune ma non obbligatoria.

src/pages

Le pagine sono un tipo speciale di componente utilizzato per creare nuove pagine sul tuo sito. Una pagina può essere un componente Astro o un file Markdown che rappresenta una pagina di contenuto per il tuo sito.

Attenzione

src/pages è una sottodirectory obbligatoria nel tuo progetto Astro. Senza di esso, il tuo sito non avrà pagine o percorsi!

src/styles

È una convenzione comune archiviare i file CSS o Sass in una directory src/styles, ma ciò non è obbligatorio. Finché i tuoi stili risiedono da qualche parte nella directory src/ e vengono importati correttamente, Astro li gestirà e li ottimizzerà.

public/

La directory public/ è riservata ai file e alle risorse che non necessitano di essere elaborati durante il processo di creazione di Astro. Questi file verranno copiati nella cartella di build senza essere toccati.

Questo comportamento rende public/ ideale per risorse comuni come immagini e caratteri o file speciali come robots.txt e manifest.webmanifest.

Puoi inserire CSS e JavaScript nella directory public/, ma tieni presente che tali file non verranno raggruppati o ottimizzati nella build finale.

Consiglio

Come regola generale, qualsiasi CSS o JavaScript che scrivi tu stesso dovrebbe risiedere nella tua directory src/.

package.json

Questo è un file utilizzato dai gestori di pacchetti JavaScript per gestire le tue dipendenze. Definisce inoltre gli script comunemente utilizzati per eseguire Astro (es: npm start, npm run build).

Esistono due tipi di dipendenze che puoi specificare in un package.json: dependencies e devDependencies. Nella maggior parte dei casi, funzionano allo stesso modo: Astro ha bisogno di tutte le dipendenze in fase di creazione e il tuo gestore pacchetti le installerà entrambe. Ti consigliamo di inserire tutte le tue dipendenze in dependencies per iniziare e di utilizzare devDependencies solo se trovi una necessità specifica per farlo.

Per assistenza nella creazione di un nuovo file package.json per il tuo progetto, consulta le istruzioni di configurazione manuale.

astro.config.mjs

Questo file viene generato in ogni modello iniziale e include le opzioni di configurazione per il tuo progetto Astro. Qui puoi specificare le integrazioni da utilizzare, le opzioni di build, le opzioni del server e altro ancora.

Consulta la guida alla configurazione di Astro (EN) per i dettagli sull’impostazione delle configurazioni.

tsconfig.json

Questo file viene generato in ogni modello iniziale e include le opzioni di configurazione TypeScript per il tuo progetto Astro. Alcune funzionalità (come le importazioni di pacchetti npm) non sono completamente supportate nell’editor senza un file tsconfig.json.

Consulta la guida a TypeScript (EN) per i dettagli sulle impostazioni delle configurazioni.