"Add one day" is harder than it looks: JavaScript Date, time zones and DST
Here are three small JavaScript snippets. Each one looks correct, and each one can move a deadline by a day. 1. Parsing a date string new Date('2026-11-20').toLocaleDateString('en-US', { timeZone: 'America
Here are three small JavaScript snippets. Each one looks correct, and each one can move a deadline by a day.
1. Parsing a date string
new Date('2026-11-20').toLocaleDateString('en-US', { timeZone: 'America/New_York' });
// '11/19/2026'
new Date('2026-11-20').toLocaleDateString('en-US', { timeZone: 'America/Sao_Paulo' });
// '11/19/2026'
new Date('2026-11-20').toLocaleDateString('en-US', { timeZone: 'Asia/Tokyo' });
// '11/20/2026'
A date-only string like '2026-11-20' is parsed as midnight UTC. Anywhere west of UTC β the whole American continent β that moment is still the evening of the 19th. Your invoice "due on November 20" shows up as due on the 19th.
2. Adding 24 hours
In New York, daylight saving time ends on November 1, 2026: that day has 25 hours.
const fmt = (d) =>
d.toLocaleString('en-US', { timeZone: 'America/New_York', dateStyle: 'medium', timeStyle: 'short' });
const midnight = new Date('2026-11-01T04:00:00Z');
fmt(midnight); // 'Nov 1, 2026, 12:00 AM'
fmt(new Date(midnight.getTime() + 24 * 60 * 60 * 1000)); // 'Nov 1, 2026, 11:00 PM'
"Midnight plus one day" is still November 1. In March it goes the other way: midnight on March 8 plus 24 hours is 1:00 AM on March 9, because that day only has 23 hours. Code that adds 86_400_000 milliseconds and then reads the date works 363 days a year.
3. Formatting with toISOString()
A very common way to get YYYY-MM-DD:
// 11:30 PM on November 2, in SΓ£o Paulo (UTC-3)
new Date('2026-11-02T23:30:00-03:00').toISOString().slice(0, 10);
// '2026-11-03'
toISOString() always converts to UTC. Late in the evening, anywhere behind UTC, it returns tomorrow's date.
The root cause
All three bugs have the same origin: Date is an instant in time, not a calendar day. It's a number of milliseconds since 1970 in UTC. A deadline like "November 20" isn't an instant β it's a day on someone's calendar, and it means the same thing whether your server runs in UTC or your user lives in Tokyo.
When you store a calendar day as an instant, you have to pick a time zone to convert it, and every conversion is a chance to slip.
The fix: keep calendar days as calendar days
Represent dates as plain YYYY-MM-DD strings and do arithmetic on whole days. No time zone is ever involved, so none can shift the result.
That's the approach of duedates, a small TypeScript library for deadlines:
import { addDays, today, now } from '@contalert/duedates';
addDays('2026-11-01', 1); // '2026-11-02' β DST doesn't exist for a calendar day
addDays('2026-03-08', 1); // '2026-03-09'
Time zones matter in exactly one place: deciding what "today" is. So that becomes an explicit question:
const instant = new Date('2026-11-03T20:00:00Z');
today('Asia/Tokyo', instant); // '2026-11-04'
today('America/New_York', instant); // '2026-11-03'
now('Asia/Tokyo', instant); // '2026-11-04T05:00'
Same instant, two different calendar days β and the code says which one you mean.
Rules of thumb
-
Store calendar days as
YYYY-MM-DDstrings (or aDATEcolumn), never as timestamps. - Convert an instant to a day exactly once, at the edge, with an explicit time zone: the user's or the business's.
-
Never read the date back from
toISOString()unless you really mean UTC. - Add days, not milliseconds.
- Keep an eye on the Temporal API: its
Temporal.PlainDateis exactly this idea, built into the language.
Next week: business days around the world β FridayβSaturday weekends, regional holidays and the "modified following" convention from finance.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.