Pular para o conteúdo
< samuelsantana.dev />
Voltar para o BlogTemporal.Now.plainDateISO() no mesmo instante: 2026-11-02 no navegador em São Paulo às 21:45 e 2026-11-03 no servidor em UTC às 00:45.

Temporal API vs Date: o servidor continua achando que já é amanhã

Samuel Santana
Publicado em 02 de novembro de 2026
NodeJSReactTypeScriptPostgreSQL

Em outubro eu contei aqui um erro #418 do React que só aparecia depois das 21h: o servidor, em UTC, já estava no dia seguinte e escrevia no HTML uma data que o navegador não reconhecia. A correção foi um hook com useSyncExternalStore que devolve null no servidor.

O Temporal chegou ao Node 26, ligado por padrão, e é tentador ler aquele bug como mais um defeito do Date. Eu testei. Em 2 de novembro, às 21h45 em Brasília, rodei o mesmo cálculo de "hoje" no Node 26.13.0 com o processo em dois fusos:

// TZ=UTC node now-system-tz.mjs   e   TZ=America/Sao_Paulo node now-system-tz.mjs
function getCurrentDate() {
  // a função do post do #418: o dia local de quem executa
  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

Com o processo em UTC, Temporal.Now.plainDateISO() respondeu 3 de novembro, igual ao Date. É o mesmo erro com uma API nova, e a documentação do Temporal não esconde: sem o argumento, o fuso usado é o do sistema. Nenhuma API que roda no servidor sabe que dia é para quem está do outro lado da tela.

Para o #418, trocar de API não muda nada. Muda o lugar onde o fuso aparece. No Date, ele está escondido no nome de cada método (getDate() é local, getUTCDate() é UTC, toISOString() é UTC). No Temporal, ele está no tipo, e é isso que tira do caminho os outros bugs de data deste post.

Os tipos do Temporal e o fuso

O Temporal separa em tipos o que o Date mistura num número de milissegundos:

TipoRepresentaExemplo
Temporal.Instantum ponto na linha do tempo, sem calendário nem fuso2026-09-26T00:50:00Z
Temporal.ZonedDateTimeum instante visto num fuso com nome2026-09-25T21:50:00-03:00[America/Sao_Paulo]
Temporal.PlainDateum dia do calendário, sem hora e sem fuso2026-09-25
Temporal.PlainDateTimedata e hora de relógio de parede, sem fuso2026-09-25T21:50:00

E as chamadas do Date que mais aparecem, com o equivalente que eu rodei no Node 26 (ms é um número de milissegundos, zdt um ZonedDateTime):

Com DateCom Temporal
new Date()Temporal.Now.instant()
dia de hoje com getFullYear(), getMonth(), getDate()Temporal.Now.plainDateISO(timeZone)
date.getDate()zdt.day (o dia no fuso do zdt, não no do processo)
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("pt-BR")plainDate.toLocaleString("pt-BR")
de Date para Temporaldate.toTemporalInstant()
de Temporal para Datenew Date(instant.epochMilliseconds)

No #418, o campo da gaveta de despesas é, no fundo, um PlainDate. "Que dia é hoje" é a conversão de um Instant (agora) para um PlainDate, e essa conversão só existe com um fuso. O Temporal deixa o fuso aparecer na chamada, Temporal.Now.plainDateISO("America/Sao_Paulo"), mas não escolhe o fuso certo por você. Fixar Brasília no servidor é a mesma correção tentadora que o post de outubro descartou: erra para todo mundo que não está em Brasília. A diferença é que, escrito assim, o erro fica numa linha que alguém lê no pull request, em vez de morar no TZ da máquina.

As armadilhas do Date que o Temporal resolve

Tudo abaixo rodou no Node 26.13.0. Rodei os mesmos scripts no Node 24.19.0 com o temporal-polyfill e os valores foram os mesmos; só as mensagens de erro mudam de texto.

"2026-09-25" é meia-noite em UTC

// TZ=America/Sao_Paulo node date-only.mjs
const d = new Date("2026-09-25");                    // só data: o JavaScript lê como meia-noite em UTC
console.log(d.toISOString());
console.log(d.toLocaleDateString("pt-BR"));

const local = new Date("2026-09-25T00:00");          // data e hora sem offset: aí é hora local
console.log(local.toISOString());

const day = Temporal.PlainDate.from("2026-09-25");   // um dia do calendário, sem hora e sem fuso
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

A regra está na especificação: sem offset, a forma só com data é lida como UTC, e a forma com data e hora é lida como hora local. Em Brasília, a meia-noite UTC de 25 de setembro é 21h do dia 24, e é o dia 24 que aparece na tela. O valor de um <input type="date"> tem exatamente esse formato; passado por new Date(), vira o dia anterior em qualquer fuso com offset negativo, ou seja, em toda a América.

Somar um dia não é somar 24 horas

No domingo, 1º de novembro de 2026, Nova York voltou o relógio uma hora: aquele dia teve 25 horas. Um servidor que agenda "o mesmo horário amanhã" para alguém de lá:

// TZ=UTC node dst.mjs   e   TZ=America/New_York node dst.mjs
// Sábado, 31/10/2026, 9h em Nova York. "Mesmo horário amanhã" cai em 01/11, o dia em que o relógio volta uma 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

O setDate soma um dia no fuso do processo. Com o servidor em Nova York, a reunião continua às 9h; com o servidor em UTC (ou em São Paulo, que deu o mesmo 8h), ela anda para as 8h. O mesmo código dá duas respostas, e qual delas sai depende de onde ele roda. No ZonedDateTime, o fuso vai junto com o valor: add({ days: 1 }) é o mesmo horário no dia seguinte, add({ hours: 24 }) é exatamente 24 horas depois, e as duas operações têm nomes diferentes.

O exemplo é em Nova York porque o Brasil não tem horário de verão desde o Decreto 9.772/2019. O tzdata que vem no Node 26.13.0 confirma que não há nenhuma transição em São Paulo depois de fevereiro de 2019:

// A última transição de America/Sao_Paulo no tzdata do 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

Daí sai uma regra que vale com ou sem Temporal: guarde o nome do fuso (America/Sao_Paulo), não o offset (-03:00). Se o horário de verão voltar, o tzdata muda e o nome acompanha; um offset gravado no banco fica errado em silêncio.

31 de janeiro mais um mês

// 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.

O Date aceita 31 de fevereiro e transborda para 3 de março sem avisar. O Temporal, por padrão (overflow: "constrain"), para no último dia do mês; com overflow: "reject", lança. A linha do meio é a que pega quem calcula vencimentos: somar e subtrair um mês não volta ao ponto de partida, porque o dia 31 virou 28 no caminho. No polyfill, a mensagem do RangeError é outra ("Invalid day: 31; must be between 1-28"), então não teste pelo texto.

Comparar e ordenar

Aqui o Temporal muda menos. === continua comparando referência, nos dois: dois PlainDate iguais dão false, sem erro. A diferença está em < e >: no Date eles funcionam por coerção numérica; no Temporal, lançam TypeError, e a comparação tem que ser explícita, com equals e compare (que também serve de função para o 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

A última linha tem um detalhe: dois ZonedDateTime no mesmo instante, em fusos diferentes, não são equals (o fuso faz parte do valor), mas compare devolve 0. Se o que interessa é o instante, compare os Instant.

JSON de ida e volta

Cada tipo vira a string ISO que o representa, o que já é melhor que o Date, que transforma um dia de calendário num instante em UTC. A volta continua igual: JSON.parse devolve strings, e o tipo se perde na rede.

// 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());       // o Date não entende o [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

A reconstrução fica na chegada, com um reviver ou com o schema que valida o payload. E o sufixo [America/New_York] do ZonedDateTime é desconhecido para quem não fala Temporal: new Date() devolve data inválida, e o Postgres recusa (está na seção do banco). Para uma API que outros sistemas consomem, eu mandaria o Instant e o nome do fuso em campos separados.

O Date e o Intl na fronteira

Bibliotecas que devolvem Date vão continuar existindo. A conversão é direta, e rodei com o processo em São Paulo para ver o que cada lado faz com o fuso:

// TZ=America/Sao_Paulo node interop.mjs
const legacy = new Date("2026-09-26T00:50:00Z");            // o que chega de uma lib antiga
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()); // e de volta para 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]

O mesmo formatador, no mesmo processo em São Paulo, mostra 24 de setembro para o Date e 25 para o PlainDate: o Intl.DateTimeFormat aplica o fuso a um Date e não aplica fuso nenhum a um PlainDate (em America/Los_Angeles a saída foi a mesma). Ele recusa um ZonedDateTime; para esse, use toLocaleString, que formata no fuso do próprio valor. E um formatador com timeStyle recusa um PlainDate, porque não há hora para mostrar. Date.prototype.toTemporalInstant() existe no Node 26 e nos três navegadores que testei.

Postgres: date, timestamp e timestamptz

A outra fronteira é o banco. Num PostgreSQL 18.6 local, gravei uma linha com as três colunas de data:

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');

E li a mesma linha com três drivers, mudando só o TZ do processo 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

Só o timestamptz é o mesmo instante em todas as linhas, porque só ele é um instante. O timestamp não tem fuso, e o driver escolhe um ao transformá-lo em Date: o postgres 4.0.0, publicado em 29 de outubro, lê como UTC (o README novo diz isso); o 3.4.9 e o pg leem no fuso do processo, e em São Paulo o mesmo valor vira um instante três horas depois. A coluna date vira meia-noite UTC no postgres (o mesmo 24/09 da seção do "2026-09-25", quando exibida em Brasília) e meia-noite local no pg. Atualizar o driver, ou mudar o TZ do container, muda o que o código lê do mesmo banco.

Com Temporal, cada coluna vira o tipo que ela é. No pg, o mapeamento é por OID e vale para todas as conexões do processo (trecho):

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

No postgres, pela opção types, registrando só o parse (trecho):

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 também to e serialize para o OID 1184 trocaria o jeito como o driver envia qualquer Date como parâmetro, por isso deixei só a leitura. No postgres 4.0.0 e no pg, com o processo em UTC e em São Paulo, a saída foi a mesma: PlainDate 2026-09-25, PlainDateTime 2026-09-25T21:50:00, Instant 2026-09-26T00:50:00Z. O Temporal.Instant.from aceita o formato de texto do Postgres (2026-09-26 00:50:00+00, com espaço e offset curto) sem ajuste.

Na ida, o cuidado é outro. Mandei três versões da reunião de Nova York (9h de 1º de novembro), convertidas com toString(), como parâmetro de um 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]"

O Instant chegou certo. O PlainDateTime foi aceito e virou 9h em UTC, cinco horas antes da reunião: sem fuso no valor, o Postgres usou o TimeZone da sessão. O ZonedDateTime foi recusado por causa do sufixo com o nome do fuso. Para uma coluna timestamptz, mande sempre um Instant: zdt.toInstant() para um ZonedDateTime, e pdt.toZonedDateTime(timeZone).toInstant() para um PlainDateTime, que precisa receber o fuso antes (com "America/New_York", deu 2026-11-01T14:00:00Z).

Onde o Temporal já existe (2 de novembro de 2026)

O Temporal chegou ao estágio 4 no TC39 em março de 2026 e está previsto para o ES2027. O suporte:

AmbienteTemporalFonte
Node 24.19.0não; --harmony-temporal liga uma versão antigatestei
Node 26sim, desde o 26.0.0 (5 de maio); o 26.13.0 é LTS desde 28 de outubronotas do 26.0.0 e testei o 26.13.0
Chrome e Edge144 em diantenotas do Chrome 144, dados do MDN
Firefox139 em diantenotas do Firefox 139
Safari 27.2 (macOS e iOS)nãonotas do Safari 27.2, caniuse
Safari Technology Previewsim, desde a 249notas da STP 249

No Node 24, a flag do V8 existe e typeof Temporal vira "object", mas a API exposta é de um rascunho antigo: tem Temporal.TimeZone, Temporal.Calendar e Temporal.Now.timeZone(), que saíram da proposta, e não tem Temporal.Now.timeZoneId(). Código escrito para o Node 26 quebra ali; o primeiro script deste post para na primeira linha:

TypeError: Temporal.Now.timeZoneId is not a function

Na minha suíte de 43 casos (os exemplos deste post e mais alguns), a flag passou em 36.

O WebKit que o Playwright 1.64.1 baixa (webkit-2370, user agent Version/27.2 Safari/605.1.15) tem Temporal nativo e passou nos 43 casos. O Safari 27.2, lançado em 26 de outubro, não tem. Um teste verde no projeto webkit do Playwright diz que o motor do WebKit trata bem o seu código; não diz que o Safari do usuário tem a API. Eu não rodei nada num Safari de verdade.

Polyfill só onde falta Temporal

Enquanto o Safari não tiver Temporal, o código no navegador precisa de polyfill:

npm install temporal-polyfill

Comparei dois pacotes, num bundle do esbuild 0.28.2 (--bundle --minify --format=esm) cuja entrada importa o pacote e chama Temporal.Now.plainDateISO():

PacoteVersão (data)Minificadogzipbrotli
@js-temporal/polyfill0.5.1 (31/03/2025)162,1 kB47,1 kB40,7 kB
temporal-polyfill/global1.0.6 (13/10/2026)59,2 kB20,6 kB18,5 kB
temporal-polyfill (sem global)1.0.656,9 kB19,8 kB17,9 kB
temporal-polyfill/full/global (todos os calendários)1.0.668,6 kB24,5 kB22,0 kB

Na suíte de 43 casos, no Node 24.19.0, o temporal-polyfill/global passou em todos do jeito que o código roda no Node 26: ele instala Temporal, ajusta o Intl.DateTimeFormat e adiciona Date.prototype.toTemporalInstant. O @js-temporal/polyfill não instala nada no escopo global e traz o próprio Intl: passou em todos quando a suíte usou o Intl.DateTimeFormat exportado pelo pacote, e falhou nos dois casos de formatar um PlainDate quando usou o Intl global (TypeError). Pelo tamanho e por estar sendo mantido (a última versão do @js-temporal/polyfill é de março de 2025), a minha escolha é o temporal-polyfill.

Carregar só quando falta

Os 20 kB não precisam ir para quem já tem Temporal. O padrão é um módulo que carrega o polyfill só quando o global não existe:

// temporal.js: importe este arquivo uma vez, antes de qualquer 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

O await no topo do módulo faz esperar quem importa temporal.js, direta ou indiretamente, e mais ninguém. Testei no Node 24 um ponto de entrada que importa temporal.js primeiro e depois dois módulos que leem typeof Temporal no topo: o que também importa temporal.js viu o polyfill; o que não importa rodou antes de ele chegar.

sibling.mjs: undefined
dependent.mjs: object
main.mjs: object

Ou seja: todo módulo que usa Temporal no próprio topo importa temporal.js; o resto pode usar Temporal dentro de funções chamadas depois que o ponto de entrada terminou de carregar. No navegador, o esbuild com --splitting pôs o polyfill num chunk separado (59,1 kB minificado) e deixou a entrada com 0,1 kB.

No Node 24 com --harmony-temporal, essa checagem engana: typeof Temporal não é "undefined", o polyfill não carrega e o código recebe a API antiga. O temporal-polyfill/global também respeita o nativo que encontra, e com essa flag Temporal.Now.timeZoneId continuou indefinido. Não ligue essa flag.

Tipos

Com TypeScript 6 ou mais novo e "lib": ["esnext"], os tipos já vêm no lib.esnext.temporal.d.ts do próprio TypeScript (testei com o 7.0.2). Num projeto com uma lib mais antiga, o Temporal não existe para o compilador (Cannot find name 'Temporal'), e importar temporal-polyfill/global não resolve: o global.d.ts desse caminho está vazio. Os tipos ficam em outro caminho do pacote, e um arquivo de declaração basta:

// temporal-types.d.ts
import "temporal-polyfill/types/global";

Com "lib": ["es2024", "dom"] e esse arquivo, o TypeScript 7.0.2 passou a conhecer Temporal.PlainDate e acusou só o erro que eu tinha posto de propósito.

No Next.js

Testei num app mínimo com Next.js 16.4.4 (next build e next start). O lugar é o instrumentation-client.js, que roda no navegador antes da hidratação. A documentação do Next avisa que só o código síncrono do topo desse arquivo termina antes da hidratação; um import() ou await é disparado e esquecido. Medi as duas formas, com o Playwright atrasando em 2 segundos o arquivo que traz o polyfill e um WebKit sem 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

Com o await import() condicional, o componente rodou antes do polyfill e a página quebrou (Can't find variable: Temporal); sem o atraso, funcionou, o que só torna o erro mais raro. Com o import estático, funcionou nos quatro navegadores:

// instrumentation-client.js: roda no navegador antes do código da aplicação.
// O polyfill usa o Temporal nativo quando ele existe.
import "temporal-polyfill/global";

O custo é que todo visitante baixa o polyfill: o JS da página inicial subiu de 175,1 kB para 193,6 kB (gzip). Para carregar só onde falta, a carga condicional tem que ficar no código que usa Temporal, e não nesse arquivo. Isso vale para o navegador; o servidor do Next roda no Node, e no Node 26 não precisa de nada.

O #418 reproduzido com Temporal

Para quem renderiza no servidor, montei uma reprodução mínima: o HTML sai de um renderToString no Node 26 com TZ=UTC, e a hidratação acontece no Chromium, no Firefox e no WebKit do Playwright 1.64.1, os três com o fuso America/Sao_Paulo. O componente é o do bug original, trocando Date por Temporal (trecho):

const label = (iso) => (iso ? Temporal.PlainDate.from(iso).toLocaleString("pt-BR") : "");

// A mesma coisa com Temporal: Temporal.Now.plainDateISO() no estado inicial.
function TemporalInState() {
  const [date] = useState(() => Temporal.Now.plainDateISO().toString());
  return <button>{label(date)}</button>;
}

Pouco antes das 22h de 2 de novembro, o React acusou a divergência nos três navegadores. A saída é a do build de desenvolvimento no Chromium:

Hydration failed because the server rendered text didn't match the client. ...

  <App variant="TemporalIn...">
    <TemporalInState>
      <button>
+       02/11/2026
-       03/11/2026

O + é o navegador; o -, o servidor. É a mesma linha do post de outubro, com outra data.

O useToday com Temporal

O hook do post de outubro, reescrito:

"use client";

import { useMemo, useSyncExternalStore } from "react";

// Não há o que escutar: o valor é lido de novo a cada render, o que basta para uma data.
function subscribe() {
  return () => {};
}

const onServer = () => null;

// O snapshot continua sendo uma string: o React compara leituras com Object.is.
const getToday = () => Temporal.Now.plainDateISO().toString();

/** O dia de hoje no fuso do navegador, ou null enquanto o servidor renderiza e a 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]);
}

A getCurrentDate() com padStart sumiu: plainDateISO().toString() já devolve 2026-11-02. O retorno deixou de ser string | null para ser Temporal.PlainDate | null, então o compilador sabe que aquilo é um dia e não um instante. Com TypeScript 7.0.2 e "lib": ["esnext"], um componente que tenta ler a hora desse valor, ou passar um PlainDateTime onde se espera um PlainDate, não compila:

import { useToday } from "./use-today";

export function Label() {
  const today = useToday();
  if (!today) return "";
  today.getHours();                         // não existe hora num PlainDate
  const d: Temporal.PlainDate = Temporal.Now.plainDateTimeISO(); // nem um PlainDateTime passa 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

O snapshot do servidor continua null: é ele, e não a API de datas, que faz servidor e navegador renderizarem o mesmo HTML. O snapshot do cliente continua sendo uma string. Testei devolver o PlainDate direto do getSnapshot: cada leitura cria um objeto novo, Object.is nunca bate, e o React desiste nos três 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 isso o hook lê a string e só converte no useMemo, que entrega aos componentes um PlainDate que só muda quando o dia muda.

As quatro variantes, renderizadas no servidor em UTC e hidratadas com o navegador em America/Sao_Paulo às 21h55 de 2 de novembro:

VarianteHTML do servidorChromium 156, Firefox 157 e WebKit do Playwright
Date no estado inicial (o bug original)03/11/2026erro de hidratação, botão termina em 02/11/2026
Temporal.Now.plainDateISO() no estado inicial03/11/2026erro de hidratação, botão termina em 02/11/2026
useToday com Temporal e snapshot nulobotão vaziosem erro, 02/11/2026
getSnapshot devolvendo o PlainDatebotão vazioloop, "Maximum update depth exceeded"

Os testes que deixam de ver o relógio

O post de outubro terminou com um teste de CI: o Playwright volta o relógio do navegador 45 dias com page.clock.setFixedTime, e assim servidor e navegador discordam do dia a qualquer hora. Até o Playwright 1.63, o page.clock troca o Date mas não alcança o Temporal.Now.

Rodei a mesma lógica (45 dias, a mesma expressão regular para o erro) na reprodução mínima, em duas versões do Playwright, com o navegador em UTC, o fuso do servidor, para que só o relógio deslocado pudesse criar divergência:

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

No 1.63.0, o bug escrito com Temporal passa verde, porque o Temporal.Now nativo do Chromium continua lendo o relógio real. Conferi direto, com o relógio fixado em 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

O código que intercepta o Temporal aparece no playwright-core a partir do 1.64.0 (procurei nos pacotes 1.62.0, 1.63.0 e 1.64.0 publicados no npm); as notas de versão do 1.64.0 não mencionam a mudança. No 1.64.1, o relógio falso chegou ao Temporal.Now nos três navegadores. Quem migra para Temporal com um Playwright anterior ao 1.64 fica com um teste de regressão que não falha mais.

No Vitest 5.1.0, a armadilha é de configuração. O teste unitário do post de outubro usava vi.useFakeTimers({ toFake: ["Date"] }), e com essa lista só o Date fica 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"}

Sem lista, o padrão do Vitest já inclui o Temporal; com lista, ele precisa estar nela. O teste do hook, reescrito, passou no Node 26 (trecho):

beforeEach(() => {
  vi.useFakeTimers({ toFake: ["Date", "Temporal"] });
  // 22h30 em Brasília no último dia do mês: em UTC, já é outubro.
  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");
});

Qual tipo para qual dado

PlainDate para o dia que o usuário escolheu num calendário. Instant para quando algo aconteceu, e é ele que vai para a coluna timestamptz. ZonedDateTime quando o fuso é parte do dado, como uma reunião em Nova York; no banco, ela vira um Instant mais o nome do fuso numa coluna à parte, porque nem o JSON dos outros sistemas nem o Postgres entendem o sufixo [America/New_York].

Não medi o desempenho do Temporal contra o Date, não rodei num Safari de verdade nem nas imagens Docker do Node 26, e a reprodução do #418 usa renderToString e hydrateRoot direto, fora de um app Next.js completo.

Comentários

Carregando comentários...