Saltearse al contenido

Instala y configura Astro

El comando CLI create astro es la forma más rápida de crear un nuevo proyecto de Astro desde cero. Te guiará a través de cada paso de la configuración de tu nuevo proyecto de Astro y te permitirá elegir entre diferentes plantillas de inicio oficiales.

O, puedes empezar tu proyecto utilizando un tema existente o una plantilla de inicio.

Para instalar Astro manualmente, consulta nuestra guía de instalación manual paso a paso.

  • Node.js - v18.17.1, v20.3.0 o superior. ( v19 no es soportada.)
  • Editor de código - Recomendamos VS Code con nuestra extensión oficial de Astro.
  • Terminal - Astro es usado a través de la interfaz de línea de comandos (CLI).
  1. Ejecuta el siguiente comando en tu terminal para iniciar el asistente de instalación:

    Ventana de terminal
    # crea un nuevo proyecto con npm
    npm create astro@latest

    Puedes ejecutar create astro desde cualquier lugar de tu máquina, así que no es necesario crear una nueva carpeta vacía para tu proyecto antes de comenzar. Si aún no tienes una carpeta vacía para tu nuevo proyecto, el asistente te ayudará a crear una automáticamente.

    Si todo va bien, verás un mensaje de éxito seguido de siguientes pasos recomendados. Ahora que tu proyecto ha sido creado, puedes navegar utilizando cd a tu nueva carpeta para comenzar a usar Astro.

  2. Si saltaste el paso npm install durante el asistente CLI, asegúrate de instalar tus dependencias antes de continuar.

  3. Ahora puedes iniciar el servidor de desarrollo de Astro y ¡ver una vista previa en vivo de tu proyecto mientras lo construyes!

Usa un tema o una plantilla de inicio

Sección titulada Usa un tema o una plantilla de inicio

También puedes empezar un nuevo proyecto de Astro basado en un ejemplo oficial o en la rama main de cualquier repositorio de GitHub pasando un argumento --template al comando create astro.

  1. Explora nuestro escaparate de temas y plantillas de inicio donde puedes navegar por temas para blogs, portafolios, sitios de documentación, páginas landing y más. O, busca en GitHub para encontrar aún más proyectos de inicio.

  2. Ejecuta el siguiente comando en tu terminal, sustituyendo el nombre de la plantilla de inicio oficial de Astro, o el nombre de usuario de GitHub y el repositorio del tema que quieras usar:

    Ventana de terminal
    # crea un nuevo proyecto con un ejemplo oficial
    npm create astro@latest -- --template <example-name>
    # crea un nuevo proyecto basado en la rama principal de un repositorio de GitHub
    npm create astro@latest -- --template <github-username>/<github-repo>

    Por defecto, este comando usará la rama main del repositorio de la plantilla. Para usar un nombre de rama diferente, pásalo como parte del argumento --template: <github-username>/<github-repo>#<branch>.

  3. Responde las preguntas y sigue las instrucciones del asistente CLI.

  4. Ahora puedes iniciar el servidor de desarrollo de Astro y ¡ver una vista previa en vivo de tu proyecto mientras lo construyes!

Esta guía te guiará a través de los pasos para instalar y configurar manualmente un nuevo proyecto de Astro.

Si prefieres no utilizar nuestra herramienta automática CLI create astro, puedes configurar tu proyecto siguiendo la guía que se detalla a continuación.

  1. Crea una carpeta

    Crea una carpeta vacía con el nombre de tu proyecto y navega hacia ella.

    Ventana de terminal
    mkdir my-astro-project
    cd my-astro-project

    Ya en la carpeta, crea un archivo package.json para tu proyecto. Esto te ayudará a gestionar las dependencias del proyecto, incluyendo Astro. Si no estás familiarizado con este formato de archivo, ejecuta el siguiente comando para crear uno.

    Ventana de terminal
    npm init --yes
  2. Instala Astro

    Primero, instala Astro dentro de tu proyecto.

    Ventana de terminal
    npm install astro

    A continuación, reemplaza los scripts creados por defecto en el package.json por los siguientes:

    package.json
    "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
    },

    Los scripts serán usados más adelante en la guía para iniciar y ejecutar diferentes comandos en Astro.

  3. Crea tu primera página

    En tu editor de código, crea un nuevo archivo en el directorio src/pages/index.astro. Esta será tu primera página de Astro en el proyecto.

    Copia y pega el siguiente fragmento de código (incluyendo --- guiones) en tu nuevo archivo:

    src/pages/index.astro
    ---
    // ¡Bienvenido a Astro! Todo entre los guiones triples son los
    // "metadatos de tu componente". Nunca se ejecuta en el navegador.
    console.log('¡Esto se ejecuta en tu terminal y no en el navegador!');
    ---
    <!-- El código de abajo es "la plantilla de su componente". Es solo HTML
    con un poco de magia que te ayudará a crear la plantilla del componente. -->
    <html>
    <body>
    <h1>¡Hola Mundo!</h1>
    </body>
    </html>
    <style>
    h1 {
    color: orange;
    }
    </style>
  4. Crea tu primer archivo estático

    Crea una carpeta public en la raíz de tu proyecto para almacenar todos los archivos estáticos. Astro incluirá estos archivos en la compilación final, así podrán ser referenciados de forma segura desde tus componentes.

    Crea un nuevo archivo en el directorio public/robots.txt. robots.txt es un archivo que informa a los robots de búsqueda, como Google, sobre cómo indexar tu página web.

    Copia y pega el siguiente fragmento de código:

    public/robots.txt
    # Example: Permitir a todos los bots de búsqueda escanear e indexar el sitio web.
    # Full syntax: https://developers.google.com/search/docs/advanced/robots/create-robots-txt
    User-agent: *
    Allow: /
  5. Crea astro.config.mjs

    Astro es configurado usando el archivo astro.config.mjs. Este archivo es opcional si no necesitas configurar Astro, pero recomendamos crear uno ahora.

    Crea un archivo astro.config.mjs en la raíz del proyecto y copia el siguiente código dentro de él:

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    // https://astro.build/config
    export default defineConfig({});

    Si deseas incluir componentes de frameworks como React, Svelte, etc.; o usar otras herramientas de desarrollo como Tailwind o Partytown en tu proyecto, lee nuestra guía de integraciones.

    Lee nuestra guía de configuración de API para más información.

  6. Agrega soporte para TypeScript

    TypeScript es configurado usando tsconfig.json. Aun si tú no escribes código en TypeScript, este archivo es importante para que herramientas como Astro y VS Code sepan cómo comprender tu proyecto. Algunas características (como importaciones de paquetes npm) no tienen un soporte completo en el editor sin el archivo tsconfig.json.

    Si pretendes escribir código en TypeScript, recomendamos usar las plantillas de Astro strict o strictest. Puedes ver y comparar las tres configuraciones de las plantillas en astro/tsconfigs/.

    Crea un archivo tsconfig.json en la raíz del proyecto y copia el siguiente código dentro de él. (Puedes usar base, strict o strictest para tu maquetado de TypeScript):

    tsconfig.json
    {
    "extends": "astro/tsconfigs/base"
    }

    Finalmente, crea un archivo src/env.d.ts para que TypeScript infiera los tipos disponibles en un proyecto de Astro.

    src/env.d.ts
    /// <reference types="astro/client" />

    Lee nuestra guía para configurar TypeScript para más información.

  7. Siguientes pasos

    Si has seguido las instrucciones anteriores, el proyecto debe lucir así:

    • Directorynode_modules/
    • Directorypublic/
      • robots.txt
    • Directorysrc/
      • Directorypages/
        • index.astro
      • env.d.ts
    • astro.config.mjs
    • package-lock.json o yarn.lock, pnpm-lock.yaml, etc.
    • package.json
    • tsconfig.json
  8. Ahora puedes iniciar el servidor de desarrollo de Astro y ¡ver una vista previa en vivo de tu proyecto mientras lo construyes!

Iniciar el servidor de desarrollo de Astro

Sección titulada Iniciar el servidor de desarrollo de Astro

Astro posee un servidor de desarrollo que tiene todo lo que necesitas para desarrollar tu proyecto. El comando astro dev iniciará el servidor de desarrollo local para que veas tu nuevo proyecto en acción por primera vez.

Cada plantilla de inicio posee un script preconfigurado que ejecutará astro dev por ti. Utiliza tu gestor de paquetes favorito para ejecutar este comando e iniciar el servidor de desarrollo de Astro.

Ventana de terminal
npm run dev

Si todo va bien, Astro servirá tu proyecto en http://localhost:4321. ¡Visita ese enlace en tu navegador y verás tu nuevo sitio!

Astro escuchará cualquier cambio en la carpeta src/ y actualizará automáticamente tu proyecto. De esta forma, no será necesario reiniciar el servidor local durante el desarrollo. Siempre verás la versión más reciente de tu proyecto en tu navegador mientras el servidor de desarrollo esté en ejecución.

Cuando visualices tu sitio en el navegador, tendrás acceso a la barra de herramientas de desarrollo de Astro. A medida que construyas, te ayudará a inspeccionar tus islas, detectar problemas de accesibilidad y mucho más.

Si no es posible abrir el proyecto en el navegador, regresa a la terminal donde has ejecutado el comando dev y chequea si ha ocurrido algún error o si tu proyecto está siendo servido en una URL diferente a la mencionada anteriormente. Deberías ver un mensaje si ha ocurrido algún error, o si tu proyecto está siendo servido en una URL diferente a http://localhost:4321/.

Para comprobar la versión de tu sitio que será creada en tiempo de compilación, detén el servidor de desarrollo (Ctrl + C) y ejecuta el comando de construcción apropiado para tu gestor de paquetes en la terminal:

Ventana de terminal
npm run build

Astro creará una versión de tu sitio lista para ser desplegada en una carpeta separada (dist/ por defecto) y visualizará el progreso en la terminal. Esto te alertará de cualquier error de compilación en tu proyecto antes de desplegarlo en producción. Si TypeScript está configurado en strict o strictest, el script build también comprobará tu proyecto en busca de errores de tipado.

Cuando la construcción finalice, ejecuta el comando preview (por ejemplo, npm run preview) en tu terminal y podrás ver la versión construida de tu sitio en el navegador.

Ten en cuenta que esta previsualización de tu código es como existía cuando se ejecutó por última vez el comando de construcción. Esto está pensado para darte una vista previa de cómo se verá tu sitio cuando sea desplegado en la web. Cualquier cambio posterior que realices en tu código después de la construcción no se reflejará mientras previsualices tu sitio hasta que vuelvas a ejecutar el comando de construcción.

Utiliza (Ctrl + C) para salir de la previsualización y ejecutar otro comando en la terminal, como reiniciar el servidor de desarrollo para volver a trabajar en modo desarrollo que se actualiza a medida que editas para mostrar una vista previa en vivo de tus cambios de código.

Lee más acerca del CLI de Astro y los comandos de terminal que usarás mientras desarrollas con Astro.

Puede que quieras desplegar tu nuevo sitio inmediatamente, antes de comenzar a añadir o cambiar mucho código. Esto es útil para publicar una versión mínima y funcional de tu sitio que puede ahorrarte tiempo y esfuerzo extra al solucionar problemas con tu despliegue más adelante.

¡Genial! ¡Ahora estás listo para empezar a construir con Astro! 🥳

Aquí te dejamos algunas sugerencias para explorar a continuación. Puedes leerlas en cualquier orden, ¡incluso puedes dejar de lado la documentación por un momento y comenzar a experimentar con el código base de tu nuevo proyecto de Astro! Siempre puedes volver aquí cuando tengas dudas o necesites ayuda.

Explora las funcionalidades de Astro

Sección titulada Explora las funcionalidades de Astro
Contribuir

¿Qué tienes en mente?

Comunidad