Middleware, endpoints y plugins de Vite en una integración

Una integración madura rara vez se limita a tocar la configuración: quiere correr lógica en cada petición, servir sus propias páginas y endpoints, y a veces bajar hasta el bundler para transformar módulos o inventarlos de la nada. Astro expone justo esas tres capas —el middleware, el enrutado y Vite— a través de utilidades que ya conoces de otros niveles, ahora accionadas desde dentro de una integración. Y corona el conjunto con uno de los patrones más elegantes del ecosistema: los módulos virtuales, ficheros que no existen en disco pero que tu código importa como si existieran.

addMiddleware: correr lógica en cada petición

Ya sabes que src/middleware.ts intercepta toda petición del sitio. Una integración puede aportar su propio middleware sin que el usuario cree ese fichero, usando addMiddleware dentro de astro:config:setup. Le das un entrypoint —un módulo que exporta un onRequest— y un order que decide si tu middleware corre antes o después del que el usuario haya escrito.

'astro:config:setup': ({ addMiddleware }) => {
  addMiddleware({
    order: 'pre',
    entrypoint: 'mi-integracion/middleware.js',
  });
},

El order tiene dos valores y la elección importa. Con 'pre', tu middleware corre antes que el del usuario, útil para preparar locals o cabeceras que sus rutas darán por sentadas. Con 'post', corre después, útil para rematar la respuesta ya construida. Varias integraciones pueden inyectar middleware a la vez; todos se encadenan con el del usuario en una sola tubería, exactamente como los sequence que estudiaste en el nivel de middleware.

Endpoints y páginas dentro del paquete

injectRoute no sirve solo para páginas: su entrypoint puede ser un endpoint —un módulo que exporta GET, POST y demás verbos— y así tu integración expone una API sin que el usuario escriba un fichero en src/pages. Es el mecanismo con el que una integración regala un webhook, un endpoint de estado o un feed.

// mi-integracion/endpoints/salud.ts  (dentro del paquete)
import type { APIRoute } from 'astro';

export const GET: APIRoute = () =>
  Response.json({ estado: 'ok', hora: Date.now() });

'astro:config:setup': ({ injectRoute }) => {
  injectRoute({
    pattern: '/api/salud',
    entrypoint: 'mi-integracion/endpoints/salud.ts',
    prerender: false,
  });
},

La ruta inyectada es indistinguible de una escrita a mano: participa del enrutado, del middleware y del render como cualquier otra. La diferencia es de procedencia —vive en tu paquete, viaja con él y aparece en cada proyecto que instale la integración— sin pedirle nada al usuario más que enrolarla.

Plugins de Vite desde la integración

Cuando necesitas transformar módulos, resolver imports especiales o participar del empaquetado, la herramienta es un plugin de Vite, y lo enchufas fundiéndolo en la configuración con updateConfig. Como Astro corre sobre Vite, todo el poder del bundler queda a tu alcance desde la integración.

'astro:config:setup': ({ updateConfig }) => {
  updateConfig({
    vite: {
      plugins: [
        {
          name: 'mi-plugin-vite',
          transform(code, id) {
            // transforma modulos que coincidan con un criterio
            return null;
          },
        },
      ],
    },
  });
},

Como updateConfig funde en profundidad, añadir tu plugin no borra los que el usuario u otras integraciones ya pusieron: se suma al array. Esta es la puerta trasera controlada por la que una integración accede al pipeline de compilación —la misma capa que en su día tocaste a mano en la clave vite de la configuración, ahora accionada por código—.

Módulos virtuales: importar lo que no existe

El patrón que corona esta lección resuelve un problema recurrente: quieres que el código del usuario importe datos que tu integración genera —opciones resueltas, una lista construida en el build—, pero esos datos no viven en ningún fichero. La solución es un módulo virtual: un plugin de Vite intercepta un especificador imaginario y devuelve su contenido al vuelo.

function moduloVirtual(saludo: string) {
  const id = 'virtual:mi-integracion';
  const resuelto = '\0' + id;
  return {
    name: 'mi-integracion:virtual',
    resolveId(spec: string) {
      if (spec === id) return resuelto;
    },
    load(spec: string) {
      if (spec === resuelto) return `export const saludo = ${JSON.stringify(saludo)};`;
    },
  };
}

El convenio tiene dos mitades. El especificador público lleva el prefijo virtual:, la señal idiomática de que no es un fichero real. Y el identificador interno que devuelve resolveId lleva por delante un byte nulo —el prefijo que le dice a Vite y a Rollup que no busquen eso en disco porque es suyo—. La función load reconoce ese identificador interno y devuelve el código como una cadena. A partir de ahí, el usuario escribe import { saludo } from 'virtual:mi-integracion' y recibe tus datos como si viniesen de un fichero.

flowchart TD
INT[integracion] --> MW[addMiddleware onRequest en cada peticion]
INT --> RT[injectRoute endpoints y paginas del paquete]
INT --> VP[updateConfig con vite plugins]
VP --> RES[resolveId reconoce el especificador virtual]
RES --> LOAD[load devuelve el codigo al vuelo]
LOAD --> IMP[el usuario importa el modulo virtual]
style INT fill:#89b4fa,color:#11111b
style IMP fill:#a6e3a1,color:#11111b