El pipeline: de la fuente al módulo

Un componente .astro no llega nunca al navegador; llega al motor de render de Astro convertido en un módulo de JavaScript que exporta una función. Entre tu archivo y ese módulo hay una tubería de tres tramos —parsear, transformar, generar— que el compilador recorre para cada componente del proyecto. Verla por dentro desmitifica todo lo demás: las islas, el scope de estilos y los source maps de las próximas lecciones son consecuencias de decisiones que se toman en estos tres pasos. Y como el compilador se publica en @astrojs/compiler, esa tubería no es una caja negra: se puede invocar a mano.

Tres tramos: parsear, transformar, generar

El compilador no salta de tu texto al código final de un brinco; encadena tres transformaciones bien separadas. Primero parsea: lee la fuente carácter a carácter y construye un árbol de sintaxis abstracta, un AST, donde cada nodo es una pieza del componente —el frontmatter, un elemento, un atributo, una expresión, un bloque de estilo—. Después transforma ese árbol: reescribe selectores para el scope, marca las islas, iza los estilos, resuelve las directivas. Por último genera: recorre el árbol ya transformado y emite texto de JavaScript, el módulo que Astro importará.

flowchart LR
SRC[fuente punto astro] --> P[parsear]
P --> AST[arbol de sintaxis]
AST --> T[transformar]
T --> AST2[arbol anotado]
AST2 --> G[generar]
G --> MOD[modulo javascript y metadatos]

Cada tramo tiene una entrada y una salida bien definidas, y nombrarlas ayuda a razonar sobre dónde ocurre cada cosa:

• Parsear toma texto y devuelve un árbol. La entrada es tu .astro como cadena; la salida, un AST con un nodo por cada pieza del componente.
• Transformar toma un árbol y devuelve otro árbol anotado. Reescribe selectores, marca islas, iza estilos; no toca todavía una sola letra de JavaScript.
• Generar toma el árbol anotado y devuelve texto. La salida es el módulo de JavaScript, más el informe de metadatos recolectado por el camino.

La separación importa por una razón práctica: como cada tramo tiene fronteras claras, se pueden estudiar y depurar por partes. Un fallo de sintaxis es un problema del parseo; un estilo que no se aísla es un problema de la transformación; un HTML raro en la salida es un problema de la generación. Pensar en estos tres compartimentos convierte cualquier rareza del compilador en una pregunta con una dirección concreta donde buscar.

La forma del módulo emitido

El texto que sale del último tramo tiene una estructura reconocible, y merece la pena leerla una vez para no temerla nunca más. El frontmatter se convierte en el cuerpo de una función de render asíncrona; el marcado se convierte en una plantilla de cadena etiquetada con una función render que interpola las expresiones; y todo se envuelve en una llamada a createComponent, el envoltorio del runtime de Astro que produce el componente final.

// forma simplificada de lo que emite el compilador
import {
  createComponent, render, renderComponent,
  maybeRenderHead, createAstro
} from 'astro/runtime/server/index.js';

const $$Astro = createAstro();

const $$Pagina = createComponent(async ($$result, $$props, $$slots) => {
  const $$Astro = $$result.createAstro($$Astro, $$props, $$slots);
  const usuario = await fetch('/api/yo').then((r) => r.json());
  return render`${maybeRenderHead()}<h1>Hola, ${usuario.nombre}</h1>`;
});

export default $$Pagina;

Cada pieza tiene su papel. El parámetro $$result es el acumulador del render: lleva la cuenta de los estilos, los scripts y las islas que se van encontrando mientras se pinta la página, y por eso lo recibe cada componente. $$props y $$slots son las props y los slots recibidos. La función render etiquetada es la que convierte las interpolaciones en HTML seguro, y maybeRenderHead inyecta en el momento justo los estilos y scripts que el $$result ha ido recolectando. Los prefijos $$ no son casuales: marcan lo generado por la máquina para que no choque con tus nombres.

Observa además cómo el frontmatter aparece casi textual dentro de la función: el await fetch(...) que escribiste sigue ahí, con la misma forma, solo que ahora vive en el cuerpo de createComponent. Esa fidelidad no es accidental; es lo que permite que los source maps de la última lección puedan trazar cada línea generada de vuelta a la tuya. El compilador transforma la estructura del componente, pero preserva la letra de tu código de servidor tanto como puede.

parse: el árbol antes de tocarlo

El paquete @astrojs/compiler publica la tubería como dos funciones. La primera, parse, se detiene en el primer tramo: recibe la fuente y devuelve el AST sin transformarlo ni generar nada. Es la puerta para inspeccionar un componente —lo que hacen las herramientas de formato, los linters o los plugins que analizan tu código— sin producir salida.

import { parse } from '@astrojs/compiler';

const fuente = `---\nconst n = 1;\n---\n<h1>Hola {n}</h1>`;
const { ast, diagnostics } = await parse(fuente);

// ast.type === 'root'; sus children son frontmatter, elementos, texto...
console.log(ast.children.map((nodo) => nodo.type));

El resultado trae el ast —un árbol cuyo nodo raíz es de tipo root— y una lista de diagnostics con los avisos y errores que el parseo haya encontrado. Los tipos de nodo son pocos y describen todo lo que un .astro puede contener:

• frontmatter: el bloque entre vallas, con el código de servidor como su valor.
• element y component: una etiqueta HTML o un componente importado, con sus atributos.
• expression: una interpolación {...} de la plantilla.
• text: el texto literal entre nodos.

Recorrer ese árbol es la forma de razonar sobre la estructura de un componente sin importar cómo se compile: dos archivos con el mismo AST significan lo mismo, aunque difieran en espacios o comentarios. Esa es la propiedad que explotan los formateadores —normalizan el texto sin cambiar el árbol— y los linters —inspeccionan el árbol sin generar código—.

transform: el código y sus metadatos

La segunda función, transform, recorre la tubería entera y devuelve el resultado final: el módulo de JavaScript ya generado y, con él, todo el informe de metadatos que el compilador extrajo por el camino.

import { transform } from '@astrojs/compiler';

const { code, map, styles, scripts, hydratedComponents, diagnostics } =
  await transform(fuente, {
    filename: 'src/pages/index.astro',
    sourcemap: 'external',
  });

console.log(code);              // el modulo JS emitido
console.log(hydratedComponents); // islas detectadas para hidratar

En ese objeto está condensado todo lo que el resto del framework necesita. Vale la pena verlo como el contrato de salida del compilador, campo por campo:

• code: el módulo de JavaScript, el único trozo destinado a ejecutarse.
• map: el source map que devuelve cada línea generada a tu .astro, tema de la última lección.
• styles y scripts: los bloques <style> y <script> izados del componente para procesarse aparte.
• hydratedComponents y clientOnlyComponents: las islas detectadas, con y sin render de servidor.
• diagnostics: los avisos y errores que la compilación encontró.

Astro no usa nada más para montar la página: llama a transform por cada .astro, guarda el code como módulo y reparte los metadatos entre sus subsistemas —el empaquetado de estilos, el registro de islas, el canal de errores—. Entender esa única llamada, con su entrada de texto y su salida de código más informe, es entender el corazón del build.