Módulos virtuales y el prefijo nulo

No todo lo que importas tiene por qué existir como archivo. Un módulo virtual es código que un plugin genera al vuelo y sirve como si fuera un módulo normal, pero que nunca toca el disco. Detrás de import.meta.glob, de virtual:pwa-register, de los iconos que importas por nombre o de la configuración que llega como módulo, hay siempre el mismo patrón mínimo: un resolveId que reconoce un id inventado y un load que fabrica su contenido. La pieza que hace que todo encaje limpiamente es una convención discreta pero fundamental: el prefijo de byte nulo.

Un módulo sin archivo

La idea es tan simple como potente: en vez de escribir un archivo, generar su contenido en el momento del build. Si necesitas exponer datos que solo se conocen al compilar —el hash del commit, la fecha de build, la lista de rutas de tu app, un catálogo de iconos— tienes dos caminos. Uno es escribir un archivo generado en disco con un script previo, con todos los problemas de sincronización que eso arrastra: queda obsoleto, se versiona por error, se olvida de regenerar. El otro es un módulo virtual: el import existe en tu código, pero su contenido lo produce un plugin cada vez, siempre fresco, sin ensuciar el árbol de archivos.

import infoBuild from 'virtual:build-info'
console.log(infoBuild.commit, infoBuild.fecha)

Ese import es real y funciona, pero no hay ningún virtual:build-info en el disco. Cuando el bundler intente resolverlo, un plugin lo interceptará, le dará una identidad y le fabricará el código. El usuario del plugin escribe un import idiomático; el plugin hace la magia por detrás. Esa separación —una interfaz de import limpia sobre generación dinámica— es lo que hace tan agradables de consumir a los buenos plugins de Vite.

El patrón: resolveId más load

Un módulo virtual se implementa siempre con el mismo par de hooks que ya conoces. resolveId reconoce el especificador público y devuelve el id interno; load reconoce ese id interno y devuelve el código generado. Entre ambos media la convención del prefijo nulo, que veremos en un momento.

export function pluginBuildInfo(): Plugin {
  const idPublico = 'virtual:build-info'
  const idResuelto = '\0' + idPublico

  return {
    name: 'build-info',
    resolveId(source) {
      if (source === idPublico) return idResuelto
      return null
    },
    load(id) {
      if (id === idResuelto) {
        const datos = {
          commit: obtenerCommit(),
          fecha: new Date().toISOString(),
        }
        return `export default ${JSON.stringify(datos)}`
      }
      return null
    },
  }
}

Fíjate en la estructura. El id público, virtual:build-info, es el que escribe el usuario en su import. El id resuelto, el mismo pero con un byte nulo delante, es el que circula por dentro del bundler. resolveId traduce del uno al otro y load responde solo al segundo. Los dos hooks devuelven null para todo lo demás, respetando su naturaleza de primero que gana y cediendo el turno cuando el especificador no les incumbe.

Por qué el byte nulo

El prefijo \0 no es decorativo: es una señal que Rollup y todo su ecosistema entienden. Un id que empieza por byte nulo significa “esto no es un archivo del sistema”. Esa marca tiene varias consecuencias concretas, y cada una resuelve un problema real.

Sin esta convención, los módulos virtuales serían frágiles. Imagina que devuelves virtual:datos tal cual desde resolveId, sin la marca: el sistema de sourcemaps intentaría localizar un archivo con ese nombre, otros plugins de load podrían reclamarlo, y en algún punto alguien haría un readFile que reventaría. El byte nulo es un carácter que no puede aparecer en una ruta de archivo real de ningún sistema operativo, lo que lo convierte en el marcador perfecto: inequívoco y universal. Es una de esas convenciones humildes que sostienen silenciosamente todo un ecosistema.

flowchart LR
I[import de virtual dos puntos build-info] --> R[resolveId reconoce el id publico]
R --> V[id interno con prefijo nulo]
V --> L[load fabrica el codigo]
L --> C[export default con los datos]
C --> G[entra en el grafo como un modulo mas]

Casos de uso y reactividad

El patrón aparece en todas partes una vez que sabes verlo. import.meta.glob de Vite agrega bajo el capó un conjunto de imports en un módulo generado. Los plugins de iconos que te dejan escribir import Flecha from '~icons/mdi/arrow' fabrican cada componente como módulo virtual. La configuración de un framework, las rutas basadas en el sistema de archivos, un manifest de assets, un registro de plugins de tu propia app: todos son módulos virtuales que convierten información dispersa en un import único y tipado.

Ahora bien, un módulo virtual que depende de archivos externos necesita un cuidado extra para el desarrollo: reactividad. Si tu load lee un YAML de datos para generar el módulo, el dev server no sabe que ese YAML influye en nada, porque no es un módulo del grafo. La solución combina dos herramientas ya vistas. En load, declaras la dependencia con this.addWatchFile(rutaDelYaml). Y cuando el archivo cambie, invalidas el módulo virtual para forzar su regeneración, buscándolo en el grafo por su id resuelto y llamando a server.moduleGraph.invalidateModule.

handleHotUpdate({ file, server }) {
  if (file.endsWith('.datos.yaml')) {
    const mod = server.moduleGraph.getModuleById('\0virtual:build-info')
    if (mod) server.moduleGraph.invalidateModule(mod)
    server.ws.send({ type: 'full-reload' })
    return []
  }
}