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

Esto genera una carpeta dist/ con el sitio completamente estático.

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 un servidor local (por defecto en http://localhost:4321) que muestra el contenido optimizado. Si todo se ve bien aquí, estás listo para desplegar 🚀

3. Desplegar en Vercel #

Vercel es la opción más popular para proyectos Astro (creada por los mismos autores de Next.js).

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

1npm install -g vercel

Paso 2. Sube tu proyecto #

En la raíz del proyecto:

1vercel

Vercel detecta automáticamente que es un proyecto Astro y configura todo. 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@v4
18      - name: Setup Node
19        uses: actions/setup-node@v4
20        with:
21          node-version: 20
22      - name: Install dependencies
23        run: npm ci
24      - name: Build site
25        run: npm run build
26      - name: Upload artifact
27        uses: actions/upload-pages-artifact@v3
28        with:
29          path: ./dist
30
31  deploy:
32    environment:
33      name: github-pages
34      url: ${{ steps.deployment.outputs.page_url }}
35    needs: build
36    runs-on: ubuntu-latest
37    steps:
38      - name: Deploy to GitHub Pages
39        id: deployment
40        uses: actions/deploy-pages@v4

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: npx astro add cloudflare (@astrojs/cloudflare)
• 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 type="module" defer> para tus JS. ✅ 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

Y en tu código:

1const apiKey = import.meta.env.API_KEY;

💡 Nunca subas tus .env al repositorio.

11. 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.