@date-fns/utc

@date-fns/utc provides UTCDate and UTCDateMini, drop-in Date subclasses that force every getter, setter, and formatter to operate in Coordinated Universal Time instead of the host system’s local time zone. This removes an entire class of bugs where date-fns calculations silently shift by an hour around Daylight Saving Time transitions, or produce different results depending on where a server or browser happens to be located.

The package also exports a utc context function that plugs directly into date-fns v4’s in option, letting existing date-fns function calls (like isSameDay or addHours) run in UTC without touching how dates are constructed elsewhere in an application. Both classes mirror the native Date API exactly, so migration is typically a drop-in swap for code that already imports Date.

What You Get

• UTCDate - a full Date-API-compatible class with UTC-based getters, setters, and formatter methods (toString, toLocaleString, and friends).
• UTCDateMini - a 239-byte minimal variant with only getters, setters, and getTimezoneOffset, for size-sensitive bundles.
• utc() context helper - a function passed as the in option to date-fns v4 functions so they operate against UTCDate under the hood.
• Dual ESM/CommonJS publish output with matching TypeScript type declarations (.d.ts and .d.cts) for both module formats.

Common Use Cases

• Calendar and date-picker rendering, where a given day’s boundaries must not shift when the viewer’s browser timezone differs from the server’s.
• Server-side date consistency across machines or regions configured with different local timezones.
• Adopting date-fns v4’s in context option to force UTC semantics across existing function calls without rewriting call sites.
• Bucketing timestamps into days/weeks for charts and reports without off-by-one-day errors caused by Daylight Saving Time transitions.

Under The Hood

Architecture The package is structured as three sibling modules under src/: date/mini.js defines UTCDateMini extending the native Date, overriding the constructor to route through Date.UTC and replacing every non-UTC-prefixed getter/setter pair via a reflection loop over Date.prototype at module-load time; date/index.js layers UTCDate on top of UTCDateMini, adding only the formatter methods (toString, toLocaleString family) using cached Intl.DateTimeFormat instances pinned to the UTC timezone; utc/index.ts is a thin factory function bridging into date-fns v4’s in context option. The three modules compose through straightforward inheritance and re-export via src/index.ts, keeping the entire runtime surface small enough for aggressive tree-shaking (importing just the mini subpath excludes all formatter code) — the one architectural risk is that correctness depends on iterating Date.prototype’s method names at runtime, coupling behavior to the shape of the host JS engine’s Date implementation.

Tech Stack Authored in a hybrid JS/TS source tree — the class implementations are plain .js files with hand-written companion .d.ts files, while the date-fns context helper is TypeScript — targeting both ESM and CommonJS consumers. The build is Makefile-driven rather than bundler-based: tsc emits declarations, Babel is run twice (BABEL_ENV=esm/cjs) to transpile src/ into .js and .cjs output, and a custom copy script plus a .d.ts-to-.d.cts duplication step assemble the dual-format package. Tests run under Vitest with TZ forced to a non-UTC, non-zero-offset zone to catch timezone leakage, and @sinonjs/fake-timers is a dev dependency used to validate compatibility with mocked clocks. The package declares zero runtime dependencies, keeping its published size trivial.

Code Quality Tests live in colocated tests.ts files (src/date/tests.ts, src/utc/tests.ts) and exercise the full surface of Date getters/setters against known offsets, constructor-argument-count branches, and Sinon fake-timer interop, with several assertions pinned to explicit dates rather than the system clock. Type safety comes from hand-written .d.ts files alongside .js implementations rather than compiling from TypeScript source for the class files, shifting responsibility for keeping types in sync onto the maintainer instead of the compiler. There is a single prettier devDependency but no visible lint step, and no GitHub Actions or other CI workflow files exist in the repository (only a FUNDING.yml under .github/) — correctness relies on manually-run Vitest and an “Are The Types Wrong” packaging check rather than automated CI gating.

API Design The public API is intentionally minimal — two Date subclasses and one context-factory function — with method signatures identical to the native Date API, so the learning curve is close to zero: code that constructs new Date(...) can switch to new UTCDate(...) with no other changes. The utc export composing with date-fns v4’s in option is a considered ergonomic choice, letting consumers opt entire call sites into UTC semantics without wrapping every date value manually. Documentation is concise but complete for a package this size, covering installation and the Mini/full tradeoff with exact byte sizes, though it assumes prior familiarity with date-fns’s context API and doesn’t spell out the package’s tree-shakeable subpath exports in the README itself, requiring a reader to check package.json to discover them.