
Temporal API vs Date: el servidor sigue creyendo que ya es mañana
En octubre conté aquí un error #418 de React que solo aparecía después de las 21 h: el servidor, en UTC, ya estaba en el día siguiente y escribía en el HTML una fecha que el navegador no reconocía. La corrección fue un hook con useSyncExternalStore que devuelve null en el servidor.
Temporal llegó a Node 26, activado por defecto, y es tentador leer aquel bug como un defecto más de Date. Lo probé. El 2 de noviembre, a las 21:45 en Brasilia, ejecuté el mismo cálculo de "hoy" en Node 26.13.0 con el proceso en dos zonas horarias (las etiquetas del script están en portugués; el código es el que se ejecutó):
// TZ=UTC node now-system-tz.mjs y TZ=America/Sao_Paulo node now-system-tz.mjs
function getCurrentDate() {
// la función del post del #418: el día local de quien la ejecuta
const now = new Date();
return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
}
console.log("TZ do processo: ", Temporal.Now.timeZoneId());
console.log("instante: ", Temporal.Now.instant().toString({ smallestUnit: "second" }));
console.log("getCurrentDate() (Date): ", getCurrentDate());
console.log("Temporal.Now.plainDateISO():", Temporal.Now.plainDateISO().toString());
console.log("plainDateISO('America/Sao_Paulo'):", Temporal.Now.plainDateISO("America/Sao_Paulo").toString());
### node 26.13.0, TZ=UTC
TZ do processo: UTC
instante: 2026-11-03T00:45:44Z
getCurrentDate() (Date): 2026-11-03
Temporal.Now.plainDateISO(): 2026-11-03
plainDateISO('America/Sao_Paulo'): 2026-11-02
### node 26.13.0, TZ=America/Sao_Paulo
TZ do processo: America/Sao_Paulo
instante: 2026-11-03T00:45:45Z
getCurrentDate() (Date): 2026-11-02
Temporal.Now.plainDateISO(): 2026-11-02
plainDateISO('America/Sao_Paulo'): 2026-11-02
Con el proceso en UTC, Temporal.Now.plainDateISO() respondió 3 de noviembre, igual que Date. Es el mismo error con una API nueva, y la documentación de Temporal no lo esconde: sin el argumento, usa la zona horaria del sistema. Ninguna API que corre en el servidor sabe qué día es para quien está del otro lado de la pantalla.
Para el #418, cambiar de API no cambia nada. Cambia el lugar donde aparece la zona horaria. En Date, está escondida en el nombre de cada método (getDate() es local, getUTCDate() es UTC, toISOString() es UTC). En Temporal, está en el tipo, y eso es lo que quita del camino los otros bugs de fechas de este post.
Los tipos de Temporal y la zona horaria
Temporal separa en tipos lo que Date mezcla en un número de milisegundos:
| Tipo | Representa | Ejemplo |
|---|---|---|
Temporal.Instant | un punto en la línea del tiempo, sin calendario ni zona | 2026-09-26T00:50:00Z |
Temporal.ZonedDateTime | un instante visto en una zona con nombre | 2026-09-25T21:50:00-03:00[America/Sao_Paulo] |
Temporal.PlainDate | un día del calendario, sin hora ni zona | 2026-09-25 |
Temporal.PlainDateTime | fecha y hora de reloj de pared, sin zona | 2026-09-25T21:50:00 |
Y las llamadas de Date que más aparecen, con el equivalente que ejecuté en Node 26 (ms es un número de milisegundos, zdt un ZonedDateTime):
Con Date | Con Temporal |
|---|---|
new Date() | Temporal.Now.instant() |
el día de hoy con getFullYear(), getMonth(), getDate() | Temporal.Now.plainDateISO(timeZone) |
date.getDate() | zdt.day (el día en la zona del zdt, no en la del proceso) |
date.toISOString() | instant.toString() |
date.getTime() / new Date(ms) | instant.epochMilliseconds / Temporal.Instant.fromEpochMilliseconds(ms) |
new Date("2026-09-25") | Temporal.PlainDate.from("2026-09-25") |
d.setDate(d.getDate() + 1) | zdt.add({ days: 1 }) |
d.setMonth(d.getMonth() + 1) | plainDate.add({ months: 1 }) |
a.getTime() === b.getTime() | a.equals(b) |
dates.sort((a, b) => a - b) | dates.sort(Temporal.PlainDate.compare) |
date.toLocaleDateString("es") | plainDate.toLocaleString("es") |
de Date a Temporal | date.toTemporalInstant() |
de Temporal a Date | new Date(instant.epochMilliseconds) |
En el #418, el campo del cajón de gastos es, en el fondo, un PlainDate. "Qué día es hoy" es la conversión de un Instant (ahora) a un PlainDate, y esa conversión solo existe con una zona horaria. Temporal deja que la zona aparezca en la llamada, Temporal.Now.plainDateISO("America/Sao_Paulo"), pero no elige la zona correcta por ti. Fijar Brasilia en el servidor es la misma corrección tentadora que el post de octubre descartó: falla para todos los que no están en Brasilia. La diferencia es que, escrito así, el error queda en una línea que alguien lee en el pull request, en vez de vivir en el TZ de la máquina.
Las trampas de Date que Temporal resuelve
Todo lo de abajo se ejecutó en Node 26.13.0. Ejecuté los mismos scripts en Node 24.19.0 con temporal-polyfill y los valores fueron los mismos; solo cambia el texto de los mensajes de error.
"2026-09-25" es medianoche en UTC
// TZ=America/Sao_Paulo node date-only.mjs
const d = new Date("2026-09-25"); // solo fecha: JavaScript la lee como medianoche en UTC
console.log(d.toISOString());
console.log(d.toLocaleDateString("pt-BR"));
const local = new Date("2026-09-25T00:00"); // fecha y hora sin offset: esa sí es hora local
console.log(local.toISOString());
const day = Temporal.PlainDate.from("2026-09-25"); // un día del calendario, sin hora ni zona
console.log(day.toString(), day.toLocaleString("pt-BR"));
2026-09-25T00:00:00.000Z
24/09/2026
2026-09-25T03:00:00.000Z
2026-09-25 25/09/2026
La regla está en la especificación: sin offset, la forma solo con fecha se lee como UTC, y la forma con fecha y hora se lee como hora local. En Brasilia, la medianoche UTC del 25 de septiembre son las 21 h del 24, y es el 24 lo que aparece en pantalla. El valor de un <input type="date"> tiene exactamente ese formato; pasado por new Date(), se convierte en el día anterior en cualquier zona con offset negativo, es decir, en toda América.
Sumar un día no es sumar 24 horas
El domingo 1 de noviembre de 2026, Nueva York atrasó el reloj una hora: ese día tuvo 25 horas. Un servidor que agenda "a la misma hora mañana" para alguien de allí:
// TZ=UTC node dst.mjs y TZ=America/New_York node dst.mjs
// Sábado 31/10/2026, 9 h en Nueva York. "A la misma hora mañana" cae el 01/11, el día en que el reloj se atrasa una hora.
const d = new Date("2026-10-31T09:00:00-04:00");
d.setDate(d.getDate() + 1);
console.log("Date.setDate(+1): ", d.toLocaleString("en-US", { timeZone: "America/New_York" }));
const meeting = Temporal.ZonedDateTime.from("2026-10-31T09:00[America/New_York]");
console.log("add({ days: 1 }): ", meeting.add({ days: 1 }).toString());
console.log("add({ hours: 24 }):", meeting.add({ hours: 24 }).toString());
console.log("horas em 01/11: ", meeting.add({ days: 1 }).hoursInDay);
### dst, TZ=UTC
Date.setDate(+1): 11/1/2026, 8:00:00 AM
add({ days: 1 }): 2026-11-01T09:00:00-05:00[America/New_York]
add({ hours: 24 }): 2026-11-01T08:00:00-05:00[America/New_York]
horas em 01/11: 25
### dst, TZ=America/New_York
Date.setDate(+1): 11/1/2026, 9:00:00 AM
add({ days: 1 }): 2026-11-01T09:00:00-05:00[America/New_York]
add({ hours: 24 }): 2026-11-01T08:00:00-05:00[America/New_York]
horas em 01/11: 25
setDate suma un día en la zona del proceso. Con el servidor en Nueva York, la reunión sigue a las 9 h; con el servidor en UTC (o en São Paulo, que dio las mismas 8 h), se corre a las 8 h. El mismo código da dos respuestas, y cuál sale depende de dónde corre. En un ZonedDateTime, la zona viaja con el valor: add({ days: 1 }) es la misma hora del día siguiente, add({ hours: 24 }) es exactamente 24 horas después, y las dos operaciones tienen nombres distintos.
El ejemplo es en Nueva York porque Brasil no tiene horario de verano desde el Decreto 9.772/2019. El tzdata que trae Node 26.13.0 confirma que no hay ninguna transición en São Paulo después de febrero de 2019:
// La última transición de America/Sao_Paulo en el tzdata de Node
const before = Temporal.ZonedDateTime.from("2019-01-01T12:00[America/Sao_Paulo]");
console.log(process.versions.tz, before.getTimeZoneTransition("next")?.toString());
console.log(process.versions.tz, before.add({ months: 3 }).getTimeZoneTransition("next"));
2026e 2019-02-16T23:00:00-03:00[America/Sao_Paulo]
2026e null
De ahí sale una regla que vale con o sin Temporal: guarda el nombre de la zona (America/Sao_Paulo), no el offset (-03:00). Si el horario de verano vuelve, el tzdata cambia y el nombre lo acompaña; un offset guardado en la base de datos queda mal sin que nadie lo note.
31 de enero más un mes
// node month-end.mjs
const d = new Date(2026, 0, 31);
d.setMonth(d.getMonth() + 1);
console.log("Date: ", d.toDateString());
const jan31 = Temporal.PlainDate.from("2026-01-31");
console.log("constrain:", jan31.add({ months: 1 }).toString());
console.log("ida/volta:", jan31.add({ months: 1 }).subtract({ months: 1 }).toString());
try {
jan31.add({ months: 1 }, { overflow: "reject" });
} catch (e) {
console.log("reject: ", `${e.name}: ${e.message}`);
}
Date: Tue Mar 03 2026
constrain: 2026-02-28
ida/volta: 2026-01-28
reject: RangeError: Temporal error: not a valid ISO date.
Date acepta el 31 de febrero y se desborda al 3 de marzo sin avisar. Temporal, por defecto (overflow: "constrain"), se detiene en el último día del mes; con overflow: "reject", lanza un error. La línea del medio (ida/volta, ida y vuelta) es la que atrapa a quien calcula vencimientos: sumar y restar un mes no regresa al punto de partida, porque el 31 se volvió 28 en el camino. En el polyfill, el mensaje del RangeError es otro ("Invalid day: 31; must be between 1-28"), así que no pruebes por el texto.
Comparar y ordenar
Aquí Temporal cambia menos. === sigue comparando referencias en los dos: dos PlainDate iguales dan false, sin error. La diferencia está en < y >: en Date funcionan por coerción numérica; en Temporal lanzan TypeError, y la comparación tiene que ser explícita, con equals y compare (que también sirve como función para el sort):
// node compare.mjs
console.log(new Date(0) === new Date(0), new Date(0) < new Date(1));
const a = Temporal.PlainDate.from("2026-09-25");
const b = Temporal.PlainDate.from("2026-09-25");
console.log(a === b, a.equals(b), Temporal.PlainDate.compare(a, b));
try {
a < b;
} catch (e) {
console.log(`${e.name}: ${e.message}`);
}
const dates = ["2026-10-02", "2026-09-25", "2026-09-18"].map((s) => Temporal.PlainDate.from(s));
console.log(dates.sort(Temporal.PlainDate.compare).join(" "));
const ny = Temporal.ZonedDateTime.from("2026-11-01T09:00[America/New_York]");
const sp = ny.withTimeZone("America/Sao_Paulo");
console.log(ny.equals(sp), Temporal.ZonedDateTime.compare(ny, sp), ny.toInstant().equals(sp.toInstant()));
false true
false true 0
TypeError: Do not use Temporal.PlainDate.prototype.valueOf; use Temporal.PlainDate.prototype.compare for comparison.
2026-09-18 2026-09-25 2026-10-02
false 0 true
La última línea tiene un detalle: dos ZonedDateTime en el mismo instante, en zonas distintas, no son equals (la zona es parte del valor), pero compare devuelve 0. Si lo que te interesa es el instante, compara los Instant.
JSON de ida y vuelta
Cada tipo se convierte en la cadena ISO que lo representa, lo que ya es mejor que Date, que transforma un día de calendario en un instante en UTC. La vuelta sigue igual: JSON.parse devuelve cadenas, y el tipo se pierde en la red.
// node json.mjs
const json = JSON.stringify({
day: Temporal.PlainDate.from("2026-09-25"),
at: Temporal.Instant.from("2026-09-26T00:50:00Z"),
meeting: Temporal.ZonedDateTime.from("2026-11-01T09:00[America/New_York]"),
legacy: new Date("2026-09-26T00:50:00Z"),
});
console.log(json);
const back = JSON.parse(json);
console.log(typeof back.day, typeof back.legacy);
console.log(new Date(back.meeting).getTime()); // Date no entiende el [America/New_York]
console.log(Temporal.ZonedDateTime.from(back.meeting).toString());
const revived = JSON.parse(json, (key, value) => (key === "day" ? Temporal.PlainDate.from(value) : value));
console.log(revived.day instanceof Temporal.PlainDate);
{"day":"2026-09-25","at":"2026-09-26T00:50:00Z","meeting":"2026-11-01T09:00:00-05:00[America/New_York]","legacy":"2026-09-26T00:50:00.000Z"}
string string
NaN
2026-11-01T09:00:00-05:00[America/New_York]
true
La reconstrucción queda en la llegada, con un reviver o con el schema que valida el payload. Y el sufijo [America/New_York] del ZonedDateTime es desconocido para quien no habla Temporal: new Date() devuelve una fecha inválida, y Postgres lo rechaza (está en la sección de la base de datos). Para una API que consumen otros sistemas, yo mandaría el Instant y el nombre de la zona en campos separados.
Date e Intl en la frontera
Las bibliotecas que devuelven Date van a seguir existiendo. La conversión es directa, y la ejecuté con el proceso en São Paulo para ver qué hace cada lado con la zona horaria:
// TZ=America/Sao_Paulo node interop.mjs
const legacy = new Date("2026-09-26T00:50:00Z"); // lo que llega de una biblioteca antigua
const instant = legacy.toTemporalInstant();
const inSaoPaulo = instant.toZonedDateTimeISO("America/Sao_Paulo");
console.log(instant.toString(), inSaoPaulo.toPlainDate().toString());
console.log(new Date(inSaoPaulo.epochMilliseconds).toISOString()); // y de vuelta a Date
const long = new Intl.DateTimeFormat("pt-BR", { dateStyle: "long" });
console.log("Date: ", long.format(new Date("2026-09-25")));
console.log("PlainDate:", long.format(Temporal.PlainDate.from("2026-09-25")));
console.log(inSaoPaulo.toLocaleString("pt-BR", { dateStyle: "short", timeStyle: "short" }));
for (const [label, fn] of [
["format(ZonedDateTime)", () => long.format(inSaoPaulo)],
["timeStyle com PlainDate", () => new Intl.DateTimeFormat("pt-BR", { timeStyle: "short" }).format(inSaoPaulo.toPlainDate())],
]) {
try {
console.log(label, fn());
} catch (e) {
console.log(`${label}: ${e.name}: ${e.message}`);
}
}
2026-09-26T00:50:00Z 2026-09-25
2026-09-26T00:50:00.000Z
Date: 24 de setembro de 2026
PlainDate: 25 de setembro de 2026
25/09/2026, 21:50
format(ZonedDateTime): TypeError: Invalid argument for Temporal [object Temporal.ZonedDateTime]
timeStyle com PlainDate: TypeError: Invalid argument for Temporal [object Temporal.PlainDate]
El mismo formateador, en el mismo proceso en São Paulo, muestra 24 de septiembre para el Date y 25 para el PlainDate: Intl.DateTimeFormat aplica la zona a un Date y no aplica ninguna a un PlainDate (en America/Los_Angeles la salida fue la misma). Rechaza un ZonedDateTime; para ese, usa toLocaleString, que formatea en la zona del propio valor. Y un formateador con timeStyle rechaza un PlainDate, porque no hay hora que mostrar. Date.prototype.toTemporalInstant() existe en Node 26 y en los tres navegadores que probé.
Postgres: date, timestamp y timestamptz
La otra frontera es la base de datos. En un PostgreSQL 18.6 local, grabé una fila con las tres columnas de fecha:
create table if not exists eventos (dia date, sem_fuso timestamp, com_fuso timestamptz);
insert into eventos values ('2026-09-25', '2026-09-25 21:50:00', '2026-09-25 21:50:00-03:00');
Y leí la misma fila con tres drivers, cambiando solo el TZ del proceso de Node:
TZ do processo Node: UTC
postgres 4.0.0 date=2026-09-25T00:00:00.000Z timestamp=2026-09-25T21:50:00.000Z timestamptz=2026-09-26T00:50:00.000Z
postgres 3.4.9 date=2026-09-25T00:00:00.000Z timestamp=2026-09-25T21:50:00.000Z timestamptz=2026-09-26T00:50:00.000Z
pg 8.23.1 date=2026-09-25T00:00:00.000Z timestamp=2026-09-25T21:50:00.000Z timestamptz=2026-09-26T00:50:00.000Z
TZ do processo Node: America/Sao_Paulo
postgres 4.0.0 date=2026-09-25T00:00:00.000Z timestamp=2026-09-25T21:50:00.000Z timestamptz=2026-09-26T00:50:00.000Z
postgres 3.4.9 date=2026-09-25T00:00:00.000Z timestamp=2026-09-26T00:50:00.000Z timestamptz=2026-09-26T00:50:00.000Z
pg 8.23.1 date=2026-09-25T03:00:00.000Z timestamp=2026-09-26T00:50:00.000Z timestamptz=2026-09-26T00:50:00.000Z
Solo timestamptz es el mismo instante en todas las líneas, porque solo él es un instante. timestamp no tiene zona, y el driver elige una al convertirlo en Date: postgres 4.0.0, publicado el 29 de octubre, lo lee como UTC (su README nuevo lo dice); 3.4.9 y pg lo leen en la zona del proceso, y en São Paulo el mismo valor se convierte en un instante tres horas después. La columna date se convierte en medianoche UTC en postgres (el mismo 24/09 de la sección de "2026-09-25", mostrado en Brasilia) y en medianoche local en pg. Actualizar el driver, o cambiar el TZ del contenedor, cambia lo que el código lee de la misma base de datos.
Con Temporal, cada columna se convierte en el tipo que es. En pg, el mapeo es por OID y vale para todas las conexiones del proceso (fragmento):
pg.types.setTypeParser(1082, (x) => Temporal.PlainDate.from(x)); // date
pg.types.setTypeParser(1114, (x) => Temporal.PlainDateTime.from(x)); // timestamp
pg.types.setTypeParser(1184, (x) => Temporal.Instant.from(x)); // timestamptz
En postgres, con la opción types, registrando solo el parse (fragmento):
const typed = postgres(url, {
types: {
date: { from: [1082], parse: (x) => Temporal.PlainDate.from(x) },
timestamp: { from: [1114], parse: (x) => Temporal.PlainDateTime.from(x) },
timestamptz: { from: [1184], parse: (x) => Temporal.Instant.from(x) },
},
});
Registrar también to y serialize para el OID 1184 cambiaría la forma en que el driver envía cualquier Date como parámetro, por eso dejé solo la lectura. En postgres 4.0.0 y en pg, con el proceso en UTC y en São Paulo, la salida fue la misma: PlainDate 2026-09-25, PlainDateTime 2026-09-25T21:50:00, Instant 2026-09-26T00:50:00Z. Temporal.Instant.from acepta el formato de texto de Postgres (2026-09-26 00:50:00+00, con espacio y offset corto) sin ajustes.
A la ida, el cuidado es otro. Mandé tres versiones de la reunión de Nueva York (9 h del 1 de noviembre), convertidas con toString(), como parámetro de un select $1::timestamptz:
Instant ok 2026-11-01T14:00:00Z
PlainDateTime ok 2026-11-01T09:00:00Z
ZonedDateTime erro: invalid input syntax for type timestamp with time zone: "2026-11-01T09:00:00-05:00[America/New_York]"
El Instant llegó bien. El PlainDateTime fue aceptado y se convirtió en 9 h UTC, cinco horas antes de la reunión: sin zona en el valor, Postgres usó el TimeZone de la sesión. El ZonedDateTime fue rechazado por el sufijo con el nombre de la zona. Para una columna timestamptz, manda siempre un Instant: zdt.toInstant() para un ZonedDateTime, y pdt.toZonedDateTime(timeZone).toInstant() para un PlainDateTime, que necesita recibir la zona antes (con "America/New_York", dio 2026-11-01T14:00:00Z).
Dónde ya existe Temporal (2 de noviembre de 2026)
Temporal llegó a la etapa 4 en TC39 en marzo de 2026 y está previsto para ES2027. El soporte:
| Entorno | Temporal | Fuente |
|---|---|---|
| Node 24.19.0 | no; --harmony-temporal activa una versión antigua | probado |
| Node 26 | sí, desde 26.0.0 (5 de mayo); 26.13.0 es LTS desde el 28 de octubre | notas de 26.0.0 y probado en 26.13.0 |
| Chrome y Edge | 144 en adelante | notas de Chrome 144, datos de MDN |
| Firefox | 139 en adelante | notas de Firefox 139 |
| Safari 27.2 (macOS e iOS) | no | notas de Safari 27.2, caniuse |
| Safari Technology Preview | sí, desde la 249 | notas de la STP 249 |
En Node 24, el flag de V8 existe y typeof Temporal pasa a ser "object", pero la API que expone es de un borrador antiguo: tiene Temporal.TimeZone, Temporal.Calendar y Temporal.Now.timeZone(), que salieron de la propuesta, y no tiene Temporal.Now.timeZoneId(). El código escrito para Node 26 se rompe ahí; el primer script de este post se detiene en su primera línea:
TypeError: Temporal.Now.timeZoneId is not a function
En mi suite de 43 casos (los ejemplos de este post y algunos más), el flag pasó 36.
El WebKit que descarga Playwright 1.64.1 (webkit-2370, user agent Version/27.2 Safari/605.1.15) tiene Temporal nativo y pasó los 43 casos. Safari 27.2, lanzado el 26 de octubre, no lo tiene. Una prueba en verde en el proyecto webkit de Playwright dice que el motor de WebKit maneja bien tu código; no dice que el Safari de tus usuarios tenga la API. No ejecuté nada en un Safari real.
Polyfill solo donde falta Temporal
Mientras Safari no tenga Temporal, el código en el navegador necesita un polyfill:
npm install temporal-polyfill
Comparé dos paquetes, en un bundle de esbuild 0.28.2 (--bundle --minify --format=esm) cuya entrada importa el paquete y llama a Temporal.Now.plainDateISO():
| Paquete | Versión (fecha) | Minificado | gzip | brotli |
|---|---|---|---|---|
@js-temporal/polyfill | 0.5.1 (31/03/2025) | 162,1 kB | 47,1 kB | 40,7 kB |
temporal-polyfill/global | 1.0.6 (13/10/2026) | 59,2 kB | 20,6 kB | 18,5 kB |
temporal-polyfill (sin global) | 1.0.6 | 56,9 kB | 19,8 kB | 17,9 kB |
temporal-polyfill/full/global (todos los calendarios) | 1.0.6 | 68,6 kB | 24,5 kB | 22,0 kB |
En la suite de 43 casos, en Node 24.19.0, temporal-polyfill/global pasó todos con el código tal como corre en Node 26: instala Temporal, ajusta Intl.DateTimeFormat y agrega Date.prototype.toTemporalInstant. @js-temporal/polyfill no instala nada en el ámbito global y trae su propio Intl: pasó todos cuando la suite usó el Intl.DateTimeFormat exportado por el paquete, y falló los dos casos de formatear un PlainDate cuando usó el Intl global (TypeError). Por el tamaño y porque se mantiene (la última versión de @js-temporal/polyfill es de marzo de 2025), mi elección es temporal-polyfill.
Cargarlo solo cuando falta
Esos 20 kB no tienen por qué llegar a quien ya tiene Temporal. El patrón es un módulo que carga el polyfill solo cuando el global no existe:
// temporal.js: impórtalo una vez, antes de cualquier código que use Temporal.
if (typeof globalThis.Temporal === "undefined") {
await import("temporal-polyfill/global");
}
node v24.19.0: Temporal do polyfill, hoje = 2026-11-02
node v26.13.0: Temporal nativo, hoje = 2026-11-02
El await en el nivel superior del módulo hace esperar a quien importa temporal.js, directa o indirectamente, y a nadie más. Probé en Node 24 un punto de entrada que importa temporal.js primero y después dos módulos que leen typeof Temporal en su nivel superior: el que también importa temporal.js vio el polyfill; el que no lo importa corrió antes de que llegara.
sibling.mjs: undefined
dependent.mjs: object
main.mjs: object
O sea: todo módulo que usa Temporal en su propio nivel superior importa temporal.js; el resto puede usar Temporal dentro de funciones llamadas después de que el punto de entrada terminó de cargar. En el navegador, esbuild con --splitting puso el polyfill en un chunk separado (59,1 kB minificado) y dejó la entrada en 0,1 kB.
En Node 24 con --harmony-temporal, esta verificación se engaña: typeof Temporal no es "undefined", el polyfill no se carga y el código recibe la API antigua. temporal-polyfill/global también respeta la implementación nativa que encuentra, y con ese flag Temporal.Now.timeZoneId siguió sin definirse. No actives ese flag.
Tipos
Con TypeScript 6 o más nuevo y "lib": ["esnext"], los tipos ya vienen en el lib.esnext.temporal.d.ts del propio TypeScript (lo probé con 7.0.2). En un proyecto con una lib más antigua, Temporal no existe para el compilador (Cannot find name 'Temporal'), e importar temporal-polyfill/global no lo resuelve: el global.d.ts de esa ruta está vacío. Los tipos están en otra ruta del paquete, y basta un archivo de declaración:
// temporal-types.d.ts
import "temporal-polyfill/types/global";
Con "lib": ["es2024", "dom"] y ese archivo, TypeScript 7.0.2 pasó a conocer Temporal.PlainDate y marcó solo el error que yo había puesto a propósito.
En Next.js
Lo probé en una app mínima con Next.js 16.4.4 (next build y next start). El lugar es instrumentation-client.js, que corre en el navegador antes de la hidratación. La documentación de Next advierte que solo el código síncrono del nivel superior de ese archivo termina antes de la hidratación; un import() o un await se lanza y se olvida. Medí las dos formas, con Playwright retrasando 2 segundos el archivo que trae el polyfill y un WebKit sin Temporal:
### instrumentation-client.js com import estático (porta 3998), atraso 2000
atraso 2000 ms | webkit* botão="02/11/2026" polyfill carregado=false chunk pedido=true erros=0
### instrumentation-client.js com await import() condicional (porta 3999), atraso 2000
atraso 2000 ms | webkit* botão="(sem #today; body: This page couldn’t load
Con el await import() condicional, el componente corrió antes del polyfill y la página se rompió (Can't find variable: Temporal); sin el retraso funcionó, lo que solo hace el error más raro. Con el import estático (el primer bloque, "import estático"), funcionó en los cuatro navegadores:
// instrumentation-client.js: corre en el navegador antes del código de la aplicación.
// El polyfill usa el Temporal nativo cuando existe.
import "temporal-polyfill/global";
El costo es que todo visitante descarga el polyfill: el JS de la página inicial pasó de 175,1 kB a 193,6 kB (gzip). Para cargarlo solo donde falta, la carga condicional tiene que estar en el código que usa Temporal, no en ese archivo. Esto vale para el navegador; el servidor de Next corre en Node, y en Node 26 no necesita nada.
El #418 reproducido con Temporal
Para quien renderiza en el servidor, armé una reproducción mínima: el HTML sale de un renderToString en Node 26 con TZ=UTC, y la hidratación ocurre en el Chromium, el Firefox y el WebKit de Playwright 1.64.1, los tres con la zona America/Sao_Paulo. El componente es el del bug original, cambiando Date por Temporal (fragmento):
const label = (iso) => (iso ? Temporal.PlainDate.from(iso).toLocaleString("pt-BR") : "");
// Lo mismo con Temporal: Temporal.Now.plainDateISO() en el estado inicial.
function TemporalInState() {
const [date] = useState(() => Temporal.Now.plainDateISO().toString());
return <button>{label(date)}</button>;
}
Poco antes de las 22 h del 2 de noviembre, React acusó la divergencia en los tres navegadores. La salida es la del build de desarrollo en Chromium:
Hydration failed because the server rendered text didn't match the client. ...
<App variant="TemporalIn...">
<TemporalInState>
<button>
+ 02/11/2026
- 03/11/2026
El + es el navegador; el -, el servidor. Es la misma línea del post de octubre, con otra fecha.
useToday con Temporal
El hook del post de octubre, reescrito:
"use client";
import { useMemo, useSyncExternalStore } from "react";
// No hay nada que escuchar: el valor se vuelve a leer en cada render, lo que basta para una fecha.
function subscribe() {
return () => {};
}
const onServer = () => null;
// El snapshot sigue siendo una cadena: React compara lecturas con Object.is.
const getToday = () => Temporal.Now.plainDateISO().toString();
/** El día de hoy en la zona del navegador, o null mientras el servidor renderiza y la página hidrata. */
export function useToday(): Temporal.PlainDate | null {
const iso = useSyncExternalStore(subscribe, getToday, onServer);
return useMemo(() => (iso === null ? null : Temporal.PlainDate.from(iso)), [iso]);
}
La getCurrentDate() con padStart desapareció: plainDateISO().toString() ya devuelve 2026-11-02. El retorno dejó de ser string | null para ser Temporal.PlainDate | null, así que el compilador sabe que eso es un día y no un instante. Con TypeScript 7.0.2 y "lib": ["esnext"], un componente que intenta leer la hora de ese valor, o pasar un PlainDateTime donde se espera un PlainDate, no compila:
import { useToday } from "./use-today";
export function Label() {
const today = useToday();
if (!today) return "";
today.getHours(); // un PlainDate no tiene hora
const d: Temporal.PlainDate = Temporal.Now.plainDateTimeISO(); // y un PlainDateTime no pasa por PlainDate
return today.toLocaleString("pt-BR") + d;
}
misuse.ts(6,9): error TS2339: Property 'getHours' does not exist on type 'PlainDate'.
misuse.ts(7,9): error TS2739: Type 'PlainDateTime' is missing the following properties from type 'PlainDate': toPlainYearMonth, toPlainMonthDay, toPlainDateTime
El snapshot del servidor sigue siendo null: es él, y no la API de fechas, lo que hace que servidor y navegador rendericen el mismo HTML. El snapshot del cliente sigue siendo una cadena. Probé devolver el PlainDate directamente desde getSnapshot: cada lectura crea un objeto nuevo, Object.is nunca coincide, y React se rinde en los tres navegadores:
console.error: The result of getSnapshot should be cached to avoid an infinite loop
pageerror: Maximum update depth exceeded. This can happen when a component repeatedly calls setState inside componentWillUpdate or componentDidUpdate. ...
Por eso el hook lee la cadena y solo la convierte en el useMemo, que entrega a los componentes un PlainDate que solo cambia cuando cambia el día.
Las cuatro variantes, renderizadas en el servidor en UTC e hidratadas con el navegador en America/Sao_Paulo a las 21:55 del 2 de noviembre:
| Variante | HTML del servidor | Chromium 156, Firefox 157 y WebKit de Playwright |
|---|---|---|
Date en el estado inicial (el bug original) | 03/11/2026 | error de hidratación, el botón termina en 02/11/2026 |
Temporal.Now.plainDateISO() en el estado inicial | 03/11/2026 | error de hidratación, el botón termina en 02/11/2026 |
useToday con Temporal y snapshot nulo | botón vacío | sin error, 02/11/2026 |
getSnapshot devolviendo el PlainDate | botón vacío | bucle, "Maximum update depth exceeded" |
Las pruebas que dejan de ver el reloj
El post de octubre terminó con una prueba de CI: Playwright atrasa 45 días el reloj del navegador con page.clock.setFixedTime, y así servidor y navegador discrepan sobre el día a cualquier hora. Hasta Playwright 1.63, page.clock reemplaza Date pero no alcanza a Temporal.Now.
Ejecuté la misma lógica (45 días, la misma expresión regular para el error) en la reproducción mínima, con dos versiones de Playwright y el navegador en UTC, la zona del servidor, para que solo el reloj desplazado pudiera crear divergencia:
playwright-core 1.64.1 / chromium 156.0.8078.4 DateInState erros de hidratação: 1
playwright-core 1.64.1 / chromium 156.0.8078.4 TemporalInState erros de hidratação: 1
playwright-core 1.64.1 / chromium 156.0.8078.4 TemporalHook erros de hidratação: 0
playwright-core 1.63.0 / chromium 153.0.8010.12 DateInState erros de hidratação: 1
playwright-core 1.63.0 / chromium 153.0.8010.12 TemporalInState erros de hidratação: 0
playwright-core 1.63.0 / chromium 153.0.8010.12 TemporalHook erros de hidratação: 0
En 1.63.0, el bug escrito con Temporal pasa en verde, porque el Temporal.Now nativo de Chromium sigue leyendo el reloj real. Lo comprobé directamente, con el reloj fijado en el 25/09:
playwright-core 1.63.0 chromium 153.0.8010.12 Date=2026-09-26T00:50:00.000Z Temporal.Now.instant=2026-11-03T00:52:53Z plainDateISO=2026-11-02
El código que intercepta Temporal aparece en playwright-core a partir de 1.64.0 (lo busqué en los paquetes 1.62.0, 1.63.0 y 1.64.0 publicados en npm); las notas de versión de 1.64.0 no mencionan el cambio. En 1.64.1, el reloj falso llegó a Temporal.Now en los tres navegadores. Si migras a Temporal con un Playwright anterior a 1.64, te quedas con una prueba de regresión que ya no puede fallar.
En Vitest 5.1.0, la trampa es de configuración. La prueba unitaria del post de octubre usaba vi.useFakeTimers({ toFake: ["Date"] }), y con esa lista solo Date queda falso:
toFake Date {"date":"2026-10-01T01:30:00.000Z","temporal":"2026-11-03T00:53:05Z"}
padrão {"date":"2026-10-01T01:30:00.000Z","temporal":"2026-10-01T01:30:00Z"}
toFake Date+Temporal {"date":"2026-10-01T01:30:00.000Z","temporal":"2026-10-01T01:30:00Z"}
Sin lista (padrão, el valor por defecto), Vitest ya incluye Temporal; con lista, tiene que estar en ella. La prueba del hook, reescrita, pasó en Node 26 (fragmento):
beforeEach(() => {
vi.useFakeTimers({ toFake: ["Date", "Temporal"] });
// 22:30 en Brasilia el último día del mes: en UTC, ya es octubre.
vi.setSystemTime(new Date("2026-09-30T22:30:00-03:00"));
});
it("não escreve nada que dependa da data no HTML do servidor", () => {
expect(renderToString(<Probe />)).toContain("no date");
});
it("o relógio falso chega ao Temporal.Now", () => {
expect(Temporal.Now.plainDateISO("America/Sao_Paulo").toString()).toBe("2026-09-30");
expect(Temporal.Now.plainDateISO("UTC").toString()).toBe("2026-10-01");
});
Qué tipo para qué dato
PlainDate para el día que el usuario eligió en un calendario. Instant para cuándo pasó algo, y es lo que va a la columna timestamptz. ZonedDateTime cuando la zona es parte del dato, como una reunión en Nueva York; en la base de datos, se convierte en un Instant más el nombre de la zona en una columna aparte, porque ni el JSON de otros sistemas ni Postgres entienden el sufijo [America/New_York].
No medí el rendimiento de Temporal frente a Date, no ejecuté nada en un Safari real ni en las imágenes Docker de Node 26, y la reproducción del #418 usa renderToString y hydrateRoot directamente, fuera de una app Next.js completa.
Comentarios
Cargando comentarios...