astro.config.mjs a fondo

astro.config.mjs es el panel de control del proyecto: un único fichero donde declaras cómo se renderiza el sitio, qué integraciones lo extienden, dónde se despliega y cómo se procesa el Markdown. No es una lista opaca de opciones, sino un objeto tipado que tu editor entiende. Conocerlo a fondo es conocer las palancas que gobiernan todo lo demás.

defineConfig: configuración tipada

El fichero exporta por defecto un objeto de configuración, pero no lo escribes crudo: lo envuelves en defineConfig, una función que importas de astro/config. En tiempo de ejecución defineConfig no hace nada —devuelve el objeto tal cual—; su valor es puramente de tipos. Al envolver la config, tu editor conoce cada clave válida, su tipo y su documentación, y te avisa si escribes algo inexistente.

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://midominio.com',
  output: 'static',
  integrations: [],
});

Dos claves globales conviene fijar pronto. site declara la URL canónica de producción —la usan el sitemap, las URLs absolutas y las etiquetas canónicas— y base define un subdirectorio si el sitio no cuelga de la raíz del dominio. Ambas son metadatos que muchas integraciones dan por supuestos.

El objeto admite muchas más claves de las que tocarás a diario, y conocerlas de nombre te ahorra reinventarlas:

• redirects declara redirecciones sin escribir código.
• server fija el host y el port por defecto del desarrollo.
• image configura el servicio de optimización de imágenes.
• env define un esquema tipado de variables de entorno.
• i18n activa el enrutado y las utilidades multiidioma.

No necesitas ninguna para arrancar, pero saber que existen convierte la documentación en un menú y no en un laberinto.

output y adapter: estático o bajo demanda

La decisión más estructural del fichero es output. Controla si tu sitio se genera por completo en el build o si algunas rutas se renderizan bajo demanda en cada petición.

En cuanto una sola ruta necesita renderizado bajo demanda, Astro exige un adapter: el paquete que traduce tu sitio al runtime de destino —Node, Vercel, Cloudflare, Netlify—. Sin adapter no hay servidor que ejecute esas rutas. El adapter se instala y registra, casi siempre, con astro add, que verás en la próxima lección.

import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
});

integrations: extender Astro

El array integrations es donde el framework crece. Cada integración es un paquete que engancha en los hooks del ciclo de vida de Astro para añadir capacidades: renderizar componentes de un framework de UI, soportar MDX, generar un sitemap, procesar estilos. Se importan y se invocan como funciones dentro del array.

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import sitemap from '@astrojs/sitemap';
import react from '@astrojs/react';

export default defineConfig({
  site: 'https://midominio.com',
  integrations: [mdx(), sitemap(), react()],
});

El orden puede importar: algunas integraciones dependen de que otra se registre antes. Como cada una es una llamada a función, admite opciones propias —sitemap({ changefreq: 'weekly' }), por ejemplo—. No edites este array a mano si puedes evitarlo: astro add lo hace por ti sin errores de sintaxis.

flowchart TD
CFG[astro.config.mjs] --> OUT[output y adapter]
CFG --> INT[integrations]
CFG --> VITE[vite]
CFG --> MD[markdown]
OUT --> R[modo de renderizado]
INT --> R
VITE --> B[pipeline de build]
MD --> B
R --> SITE[sitio final]
B --> SITE
style CFG fill:#89b4fa,color:#11111b
style SITE fill:#a6e3a1,color:#11111b

vite y markdown: bajar al pipeline

Astro se construye sobre Vite —en Astro 7, Vite 8 con el bundler Rolldown—, y la clave vite es una puerta directa a esa configuración subyacente. Todo lo que aceptaría un vite.config cabe aquí: plugins, alias de resolución, ajustes de ssr u optimizeDeps. Es la válvula de escape para cuando necesitas algo que la config de Astro no expone.

export default defineConfig({
  markdown: {
    syntaxHighlight: 'shiki',
    shikiConfig: { theme: 'catppuccin-mocha' },
  },
  vite: {
    resolve: {
      alias: { '@lib': '/src/lib' },
    },
  },
});

La clave markdown gobierna cómo se transforma tu Markdown y MDX: el motor de resaltado —Shiki por defecto y su tema—, y los remarkPlugins y rehypePlugins que inyectas en la cadena de transformación para modificar el árbol del documento. Con ellos añades desde tablas de contenido automáticas hasta enlaces de encabezado, sin salir de la configuración.

Esa cadena de remark y rehype es el mismo ecosistema de plugins que usa buena parte del mundo Markdown en JavaScript, así que rara vez tendrás que escribir uno: casi siempre existe ya el que necesitas. Astro se limita a exponerte los puntos de enganche.