Estructura de proyecto

Tu nuevo proyecto Astro generado a partir del asistente de instalación create astro incluye algunos archivos y carpetas por defecto. Otros, los crearás tú mismo y los agregarás a la estructura de archivos existente.

Así es como se organiza un proyecto de Astro y algunos archivos que encontrarás en tu nuevo proyecto.

Carpetas y archivos

Sección titulada Carpetas y archivos

Astro propone una estructura de carpetas opinionada para tu proyecto. La raíz de tu proyecto deberá incluir los siguientes archivos y carpetas:

• src/* - El código fuente de tu proyecto (componentes, páginas, estilos, etc.)
• public/* - Archivos sin código que no serán procesados (fuentes, íconos, etc.)
• package.json - El manifiesto de tu proyecto
• astro.config.mjs - El archivo de configuración de Astro (recomendado)
• tsconfig.json - El archivo de configuración de TypeScript (recomendado)

Ejemplo de árbol de proyecto

Sección titulada Ejemplo de árbol de proyecto

Un proyecto de Astro común debería verse así:

• Directorypublic/

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

  • Directorycomponents/

    • Header.astro
    • Button.jsx
  • Directorylayouts/

    • PostLayout.astro
  • Directorypages/

    • Directoryposts/

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

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

src/

Sección titulada src/

La carpeta src/ es donde se encuentra el código fuente de tu proyecto. Esto incluye:

• Páginas
• Plantillas
• Componentes de Astro
• Componentes de frameworks (React, etc.)
• Estilos (CSS, Sass)
• Markdown

Astro procesa, optimiza y empaqueta los archivos en src/ para crear la página web final que será desplegada al navegador. A diferencia de la carpeta estática public/, los archivos en src/ serán procesados por Astro.

Algunos archivos (como los componentes de Astro) no serán enviados al navegador como fueron escritos, sino que serán renderizados a HTML estático. Otros archivos (como CSS) serán enviados directamente al navegador, pero antes serán optimizados o empaquetados con otros archivos para un mejor rendimiento.

Consejo

Mientras esta guía describe algunas convenciones populares utilizadas en la comunidad de Astro, los únicos directorios reservados por Astro son src/pages/ y src/content/. Eres libre de cambiar el nombre y reorganizar cualquier otro directorio de la manera que mejor te convenga.

src/assets

Sección titulada src/assets

El directorio src/assets es la carpeta recomendada para almacenar activos (p. ej, imágenes) que son procesados por Astro. Esto no es obligatorio y no es una carpeta especial reservada.

src/components

Sección titulada src/components

Los componentes son unidades reutilizables de código para tus páginas HTML. Estos componentes pueden ser componentes de Astro o componentes de framework como React o Vue. Es común agrupar y organizar todos tus componentes en una sola carpeta.

Esta es la convención común en proyectos de Astro, pero no es necesaria. ¡Siéntete libre de organizar tus componentes a gusto!

src/content

Sección titulada src/content

El directorio src/content/ está reservado para almacenar colecciones de contenido y un archivo de configuración opcional para las colecciones. No se permiten otros archivos dentro de esta carpeta.

src/layouts

Sección titulada src/layouts

Plantillas son componentes de Astro que definen la estructura de la UI compartida por una o más páginas.

Así como src/components, esta carpeta es una convención común pero no es necesaria.

src/pages

Sección titulada src/pages

Páginas son componentes especiales usados para crear páginas en tu proyecto. Una página puede ser un componente de Astro o un archivo Markdown.

Precaución

¡src/pages es una carpeta necesaria en tu proyecto de Astro! ¡Sin ella, tu proyecto no tendrá páginas o rutas!

src/styles

Sección titulada src/styles

Es una convención común para guardar todos tus archivos CSS o Sass en una sola carpeta src/styles pero no es necesaria. Siempre y cuando tus estilos se encuentren dentro de la carpeta src/ y sean importados correctamente, Astro se encargará de optimizarlos.

public/

Sección titulada public/

La carpeta public/ es para archivos en tu proyecto que no necesiten ser procesados durante la compilación final de tu proyecto. Los archivos en esta carpeta serán copiados dentro de la carpeta build sin ser modificados y luego tu sitio será construido.

Este comportamiento hace que public/ sea ideal para activos comunes como imágenes y fuentes, o archivos especiales como robots.txt y manifest.webmanifest.

Puedes colocar CSS y JavaScript en tu carpeta public/, pero ten en cuenta que esos archivos no se empaquetarán ni optimizarán en la compilación final.

Consejo

Como regla general, cualquier archivo CSS o JavaScript que escribas debe estar en tu carpeta src/.

package.json

Sección titulada package.json

Es un archivo utilizado por los gestores de paquetes de JavaScript para administrar tus dependencias. También define los scripts que se usan comúnmente para ejecutar Astro (ex: npm start, npm run build).

Hay dos tipos de dependencias que puedes especificar en package.json: dependencies (dependencias) y devDependencies (dependencias de desarrollo). En la mayoría de los casos, estas funcionan de la misma manera: Astro necesita todas las dependencias al hacer build, y tu gestor de paquetes instalará ambos. Recomendamos poner todas tus dependencias en dependencies para comenzar, y solo usar devDependencies si encuentras la necesidad de hacerlo.

Para obtener ayuda sobre crear un nuevo archivo package.json para tu proyecto, consulta las instrucciones en instalación manual.

astro.config.mjs

Sección titulada astro.config.mjs

Este archivo es generado al crear tu proyecto en Astro e incluye la configuración de tu proyecto. Aquí puedes especificar las integraciones que desees utilizar, las opciones de compilación final, la configuración del servidor, y más.

Astro soporta varios formatos de archivo para su archivo de configuración JavaScript: astro.config.js, astro.config.mjs, astro.config.cjs y astro.config.ts. Recomendamos usar .mjs en la mayoría de los casos o .ts si deseas escribir TypeScript en tu archivo de configuración.

La carga del archivo de configuración de TypeScript se maneja utilizando tsm y respetará las opciones de tsconfig de tu proyecto.

Lee la Guía de Configuración de Astro para obtener detalles sobre las opciones de configuración.

tsconfig.json

Sección titulada tsconfig.json

Este archivo es generado en cada plantilla de inicio de Astro e incluye la configuración de las opciones de TypeScript para tu proyecto de Astro. Algunas características (como importaciones de paquetes de npm) no están soportadas completamente en tu editor sin un archivo tsconfig.json.

Lee la Guía de TypeScript para obtener detalles sobre las opciones de configuración.