Despliegue y Optimización en Astro

1. Cómo construir tu proyecto para producción #

Cuando desarrollas con Astro, estás trabajando en modo local con:

1npm run dev

Pero para subir tu web a internet, primero tienes que compilarla a HTML, CSS y JS optimizado:

1npm run build

En un proyecto estático genera dist/ con HTML, CSS y JavaScript. Si hay rutas bajo demanda, el adaptador genera además la salida de servidor correspondiente; no basta con subir archivos HTML.

mi-proyecto/
├── src/
├── public/
├── package.json
└── dist/    ← versión final optimizada

👉 Esa carpeta dist/ es la que se sube al servidor o a plataformas como Vercel, Netlify o GitHub Pages.

2. Previsualizar la build #

Antes de subirla, puedes probar cómo se verá tu web final con:

1npm run preview

Esto arranca una previsualización local (por defecto en http://localhost:4321). No la uses como servidor de producción. Con el adaptador Node standalone, prueba el backend compilado con node ./dist/server/entry.mjs; con otros destinos, utiliza sus herramientas de previsualización.
Si todo se ve bien aquí, estás listo para desplegar 🚀

3. Desplegar en Vercel #

Vercel permite desplegar sitios Astro estáticos y aplicaciones con SSR usando su adaptador.

Paso 1. Instala la CLI de Vercel (opcional) #

1npm install -g vercel

Paso 2. Sube tu proyecto #

En la raíz del proyecto:

1vercel

Para un sitio estático, Vercel detecta Astro. Si tienes Actions o endpoints dinámicos, ejecuta antes npx astro add vercel, conserva las integraciones del proyecto y comprueba el build con ese adaptador.
En segundos tendrás tu web online en una URL como:

https://mi-proyecto.vercel.app

💡 Luego podrás conectar tu dominio personalizado desde el panel web de Vercel.

4. Desplegar en Netlify #

Otra opción muy buena, especialmente para sitios estáticos.

1. Crea una cuenta en Netlify.

2. En el panel, haz clic en "Add new site" → "Import an existing project".

3. Conecta tu repositorio de GitHub.

4. En los campos:

   • Build command: npm run build
   • Publish directory: dist

Listo 🎉 Netlify construirá tu proyecto automáticamente en cada push.

5. Desplegar en GitHub Pages #

Astro puede publicarse en GitHub Pages como un sitio estático puro (SSG) de forma completamente nativa, sin necesidad de adaptadores externos.

Paso 1. Configura site y base en astro.config.mjs #

Si tu repositorio se llama mi-proyecto, añade tu URL y ruta base:

1import { defineConfig } from 'astro/config';
2
3export default defineConfig({
4  site: 'https://tuusuario.github.io',
5  base: '/mi-proyecto',
6});

(Si es un repositorio de usuario tipo tuusuario.github.io, no necesitas configurar base).

Paso 2. Automatizar el despliegue con GitHub Actions #

Crea el archivo .github/workflows/deploy.yml:

1name: Deploy to GitHub Pages
2
3on:
4  push:
5    branches: [main]
6
7permissions:
8  contents: read
9  pages: write
10  id-token: write
11
12jobs:
13  build:
14    runs-on: ubuntu-latest
15    steps:
16      - name: Checkout
17        uses: actions/checkout@v7
18      - name: Install, build and upload
19        uses: withastro/action@v6
20        with:
21          node-version: 24
22
23  deploy:
24    environment:
25      name: github-pages
26      url: ${{ steps.deployment.outputs.page_url }}
27    needs: build
28    runs-on: ubuntu-latest
29    steps:
30      - name: Deploy to GitHub Pages
31        id: deployment
32        uses: actions/deploy-pages@v4

Cuando uses base, construye los enlaces y rutas de recursos con import.meta.env.BASE_URL; las rutas absolutas /about apuntarían a la raíz del dominio y perderían el subdirectorio.

En los ajustes de tu repositorio (Settings → Pages), selecciona Source: GitHub Actions. ¡En cada git push tu web se compilará y publicará sola!

6. Adaptadores oficiales para SSR (Server-Side Rendering) #

Si tu proyecto utiliza SSR (output: 'server' o páginas híbridas bajo demanda), Astro requiere un adaptador oficial para el entorno de ejecución de destino:

• Vercel: npx astro add vercel (@astrojs/vercel)
• Netlify: npx astro add netlify (@astrojs/netlify)
• Cloudflare Workers: npx astro add cloudflare (@astrojs/cloudflare). El adaptador actual ya no despliega SSR en Cloudflare Pages.
• Node.js (Servidor propio / Docker): npx astro add node (@astrojs/node)

7. Archivos estáticos y optimización de imágenes #

Astro optimiza automáticamente imágenes cuando usas el componente oficial astro:assets.

Ejemplo:

1---
2import { Image } from "astro:assets";
3import foto from "../assets/foto.jpg";
4---
5
6<Image src={foto} alt="Foto optimizada" width={600} />

✅ Astro genera versiones comprimidas y adaptadas al tamaño.
✅ Mejora la velocidad de carga en móvil.

8. Optimización SEO (Search Engine Optimization) #

Astro, al generar HTML estático, ya es SEO-friendly, pero puedes mejorar más con algunos pasos:

Añadir etiquetas meta: #

1<head>
2  <title>Mi sitio con Astro</title>
3  <meta name="description" content="Aprende desarrollo web con Astro" />
4  <meta name="author" content="Ángel González" />
5  <meta name="keywords" content="astro, html, css, js, desarrollo web" />
6</head>

Añadir Open Graph (para redes sociales): #

1<meta property="og:title" content="Mi sitio con Astro" />
2<meta property="og:description" content="Crea webs rápidas y modernas" />
3<meta property="og:image" content="/banner.png" />
4<meta property="og:type" content="website" />

Añadir JSON-LD (estructura para Google): #

1<script type="application/ld+json">
2{
3  "@context": "https://schema.org",
4  "@type": "WebSite",
5  "name": "Mi sitio con Astro",
6  "url": "https://miweb.com"
7}
8</script>

9. Optimización de rendimiento #

Astro ya hace gran parte del trabajo por ti, pero puedes reforzarlo:

✅ Minimiza imágenes grandes.
✅ Usa el componente <Image /> de Astro.
✅ Divide el CSS por componente (Astro lo hace automáticamente).
✅ Usa <script> sin atributos para que Astro procese, empaquete y deduplique tus scripts. Los scripts que sirvas directamente desde public/ necesitan una estrategia de carga explícita.
✅ Activa client:idle o client:visible para cargar componentes solo cuando hagan falta.
✅ Usa un CDN (Vercel o Netlify ya lo incluyen).

10. Variables de entorno (ENV) #

Si tu sitio necesita claves o configuraciones secretas (por ejemplo, una API Key), usa .env:

Archivo .env:

API_KEY=123456

Para un valor conocido durante la compilación:

1---
2const apiKey = import.meta.env.API_KEY;
3---

import.meta.env se sustituye durante el build. No lo uses para prometer que un secreto cambiará en ejecución sin recompilar. Las variables con prefijo PUBLIC_ pueden llegar al navegador: no las utilices para claves privadas.

Para declarar una variable de servidor tipada, configura el esquema:

1import { defineConfig, envField } from 'astro/config';
2
3export default defineConfig({
4  env: {
5    schema: {
6      API_KEY: envField.string({ context: 'server', access: 'secret' }),
7    },
8  },
9});

Y léela únicamente desde código de servidor:

1import { API_KEY } from 'astro:env/server';

Combina este esquema con el adaptador y las demás opciones que ya tengas. Configura el secreto también en el panel de tu hosting; no subas .env a Git. La lectura de variables en ejecución depende del adaptador. Variables de entorno.

11. Fuentes y caché como ampliación #

La API de fuentes permite configurar proveedores y servir fuentes optimizadas. Define las familias y pesos necesarios, usa el componente Font del módulo astro:assets y aplica la variable CSS configurada. No cargues varias familias si no las necesitas. Fuentes.

La caché de rutas, estable en Astro 7, permite reutilizar respuestas de páginas bajo demanda según un proveedor y reglas de caducidad. No convierte una colección de compilación en una fuente en vivo. Empieza por contenido público; evita compartir en caché respuestas de cuentas o paneles privados. Caché de rutas.

12. Checklist antes de publicar #

• ✅ Ejecuta npm run build sin errores.
• ✅ Prueba con npm run preview.
• ✅ Revisa rutas (/es/, /en/, /blog/...).
• ✅ Comprime imágenes.
• ✅ Añade metaetiquetas SEO.
• ✅ Sube a Vercel, Netlify o GitHub Pages.
• ✅ Prueba desde el móvil.