Overrides de QA

Un tester necesita probar el build de una rama de una micro-app contra el shell real de staging. Sin overrides eso significa desplegar el shell, o clonar todo en local.

Con overrides es una cookie:

wu-override:cart=https://cart-pr-482.preview.example.com

El shell mantiene su configuración de producción. Solo esa sesión del navegador carga cart desde otro sitio. Nadie más se ve afectado.

Cómo funciona

Durante wu.init(), antes de registrar ninguna app, Wu recorre document.cookie buscando entradas wu-override:<appName>=<url>, valida cada una y reescribe en el sitio la url de la app correspondiente (guardando la original en _originalUrl). Todo lo que viene después —descarga del manifiesto, resolución del entry, sandbox— usa la URL sustituida.

await wu.init({
  apps: [{ name: 'cart', url: 'https://cart.example.com' }],
  overrides: {
    enabled: true,
    allowedDomains: ['*.example.com', 'localhost', '*.vercel.app'],
    showIndicator: true,
  },
});

Configuración

Opción	Por defecto	Significado
enabled	autodetectado	Si los overrides se respetan siquiera
allowedDomains	[]	Lista de hostnames permitidos; vacía significa permitir todo
showIndicator	true	Muestra el banner fijo mientras haya overrides activos

Autodetección de enabled

Si no pasas enabled, Wu decide a partir del hostname. Solo los hostnames locales cuentan como desarrollo:

localhost, 127.0.0.1, [::1], ::1, 0.0.0.0, *.local, *.localhost.

Cualquier otra cosa —incluidos los dominios de staging y los puertos no estándar— se trata como producción, y los overrides quedan apagados.

Nota

Antes un puerto no estándar contaba como “desarrollo”. Eso activaba automáticamente los overrides en cualquier sitio de producción servido detrás de un puerto como :8443, y como una lista vacía permite todos los dominios, un atacante capaz de escribir una cookie podía apuntar una app a JavaScript arbitrario. El puerto no dice nada sobre el entorno, así que la comprobación se eliminó.

allowedDomains

Hostnames exactos, o comodines *. que coinciden con el dominio y cualquier subdominio:

allowedDomains: [
  'localhost',
  '*.example.com',        // example.com y sub.example.com
  '*.vercel.app',
]

Una lista vacía permite todos los dominios. Eso es tolerable en localhost; no lo es en ningún sitio donde actives overrides deliberadamente. Si pones enabled: true en un entorno de staging, pon también allowedDomains: si no, has construido un cargador de scripts controlado por cookie.

Un override hacia un dominio no permitido se omite con un aviso que nombra la lista. Nunca se aplica en silencio.

El banner

Mientras haya algún override activo, una barra naranja fija se queda en la parte inferior del viewport listando cada override en forma nombre → url.

WU OVERRIDE ACTIVE: cart → https://cart-pr-482.preview.example.com

Haz clic para ocultarla (el override sigue activo); doble clic para limpiar todos los overrides.

Esto es anti-phishing, no decoración. Un override que nadie puede ver es un mecanismo para mostrarle a un usuario una página en la que un componente viene de otro sitio en silencio. Deja showIndicator encendido.

API programática

wu.override('cart', 'http://localhost:5173');
wu.override('cart', 'http://localhost:5173', { maxAge: 3600, path: '/' });

wu.removeOverride('cart');
wu.clearOverrides();
wu.getOverrides();          // { cart: 'http://localhost:5173' }

La cookie se escribe con SameSite=Lax y un max-age por defecto de 24 horas, así que un override caduca solo en vez de quedarse semanas.

wu.override() lanza un error en vez de fallar en silencio cuando:

• los overrides están desactivados en este entorno,
• la URL no es http://, https://, relativa al protocolo //, ni el atajo localhost[:port],
• el dominio no está en la lista de permitidos.

Los overrides se leen en el momento de init(). Establecer uno después no mueve una app ya registrada: recarga la página, o limpia el caché de manifiestos y vuelve a hacer init en un entorno de pruebas.

Poner una cookie a mano

// En DevTools, sobre el origen del shell
document.cookie = 'wu-override:cart=http://localhost:5173; path=/; max-age=86400';
location.reload();

O en Playwright / Cypress:

await context.addCookies([{
  name: 'wu-override:cart',
  value: 'http://localhost:5173',
  domain: 'staging.example.com',
  path: '/',
}]);

Eso convierte “ejecutar el shell completo de staging con una app tomada del build de CI” en una línea de preparación de tests.

Validación de URL

Formas aceptadas:

• https://host[...] y http://host[...]
• //host[...] (relativa al protocolo)
• localhost y localhost:PUERTO

El atajo localhost está anclado, así que localhost.evil.com/x no pasa como localhost. Cualquier otra cosa se rechaza como URL inválida.

Postura en producción

Recomendado:

await wu.init({
  apps: [...],
  overrides: { enabled: false },   // explícito le gana a autodetectado
});

Si de verdad necesitas overrides en un entorno compartido:

overrides: {
  enabled: true,
  allowedDomains: ['*.preview.example.com'],   // nunca dejes esto vacío
  showIndicator: true,                          // nunca apagues esto
}

Y ponle otra barrera: actívalo solo cuando haya una sesión de staff, para que una cookie por sí sola no alcance:

overrides: {
  enabled: currentUser?.isStaff === true,
  allowedDomains: ['*.preview.example.com'],
}

Inspección

wu.overrides.getStats();
// { enabled, activeOverrides, overrides, allowedDomains, showIndicator, environment }

wu.overrides.refresh();   // relee cookies cambiadas por DevTools u otra pestaña

environment informa qué concluyó la heurística del hostname, que es la forma más rápida de explicar por qué un override “no hizo nada” en una URL de staging.