Configuración de un Proyecto en AstroJS

Comprender la estructura de archivos de un proyecto en Astro es fundamental para construir sitios web rápidos y bien organizados. Desde las carpetas principales hasta la forma en que se crean rutas y se comparten estilos, cada pieza cumple un rol específico que determina cómo se compila y se entrega tu aplicación al usuario final.

¿Qué archivos componen la raíz de un proyecto en Astro?

Al abrir tu proyecto por primera vez, lo primero recomendado es instalar la extensión de Astro en tu editor de código [00:17]. Esta extensión da soporte a los archivos con extensión .astro, resaltando la sintaxis y permitiendo trabajar con componentes, páginas y layouts de forma eficiente.

Si ya tienes experiencia con proyectos basados en NPM, reconocerás elementos familiares como la carpeta node_modules, la carpeta src y el archivo package.json [01:07]. Este último es el punto de partida cuando analizas cualquier proyecto: contiene el nombre, los scripts disponibles y las dependencias instaladas.

Los scripts más relevantes que encontrarás son:

• dev: levanta el entorno de desarrollo local.
• build: compila el proyecto para producción.
• preview: muestra una vista previa de lo compilado.
• astro: comando principal que ofrece una suite de utilidades como agregar integraciones [01:47].

Otro archivo clave es astro.config.mjs, donde se añaden configuraciones, plugins y recursos a medida que el proyecto crece [02:05]. También está el archivo de configuración de TypeScript, que inicialmente viene con una configuración mínima pero resulta útil para validar código.

¿Qué carpetas no se envían al repositorio?

La carpeta .astro y node_modules aparecen en tono gris en la interfaz porque no se envían al repositorio ni al servidor [02:24]. Son archivos temporales o de configuración local que se generan automáticamente durante la compilación. Si usas Visual Studio Code, también verás la carpeta .vscode, que almacena configuraciones compartibles entre desarrolladores del mismo proyecto, como extensiones recomendadas [02:52].

¿Cómo funcionan las carpetas public y src?

Estas dos carpetas son las más importantes del proyecto [03:21].

Public contiene todos los archivos que serán trasladados a la raíz del sitio cuando se compile: fuentes, imágenes, audio, video y archivos relevantes para SEO.

Src es donde vive la lógica principal. Dentro encontrarás tres subcarpetas esenciales:

• Components: la pieza mínima reutilizable, como un botón o una sección específica.
• Layouts: bloques de código que encapsulan componentes y definen la estructura visual de cada vista.
• Pages: cada archivo o carpeta aquí dentro se convierte en una ruta de tu sitio web [03:52].

El concepto de enrutamiento basado en archivos es central en Astro. El archivo index.astro dentro de pages representa la raíz del sitio. Para crear una nueva ruta basta con agregar un archivo como about.astro, lo que genera automáticamente la ruta /about [04:28].

¿Cuándo usar carpetas en vez de archivos para las rutas?

Si necesitas rutas dinámicas o anidadas, conviene crear una carpeta con su propio index.astro [04:52]. Por ejemplo, una carpeta contact con su índice permite después generar subrutas como contact/mexico o contact/colombia, útiles cuando hay múltiples puntos de contacto por país [05:19]. Al compilarse, todo se transforma en recursos estáticos: HTML, CSS y el mínimo JavaScript necesario.

Para compartir estilos entre todas las páginas, puedes crear una carpeta styles dentro de src con un archivo global.css [05:55]. Sin embargo, estos estilos globales solo se aplican correctamente cuando las páginas utilizan un layout.

¿Qué estructura tiene un archivo .astro y cómo funciona el layout?

Un archivo .astro se divide en bloques bien diferenciados [07:02]. En la parte superior, delimitada por tres guiones (---), se escribe JavaScript que no llega al cliente. Ahí se importan componentes, se definen props y se usa TypeScript para tipar interfaces.

Debajo viene el bloque de template, que es HTML estándar enriquecido con elementos como el slot [07:30]. El slot es el punto exacto donde se renderiza el contenido de las páginas que utilizan ese layout. Esto explica por qué una página sin layout asignado no hereda los estilos globales ni la estructura base del sitio.

Los estilos dentro de un archivo .astro pueden marcarse con el atributo is:global para que se compartan entre todos los elementos [07:46]. Y si incluyes una etiqueta <script>, ese código JavaScript sí llegará al navegador del usuario, a diferencia del código entre los guiones que solo se ejecuta en tiempo de compilación [08:05].

html

<script> console.log("Hola, mundo Astro"); </script>

Este bloque se optimiza y se entrega como el único recurso JavaScript que recibe el cliente, manteniendo la filosofía de Astro de enviar la menor cantidad posible de código al navegador [08:30].

Si encuentras el tema oficial creado por el instructor en la página de temas de Astro, comparte un screenshot en los comentarios.