Moment Timezone

Moment Timezone is an add-on for Moment.js that brings full IANA (Olson) time zone support to date handling in JavaScript. It lets you take any moment and convert, display, or compute it in a named zone such as ‘America/New_York’ or ‘Asia/Tokyo’, correctly accounting for historical offsets and daylight saving time transitions.

Bundled with the IANA time zone database, it exposes a small moment.tz API layered directly onto Moment’s chainable interface, plus utilities to guess the user’s zone, list zones by country, and load trimmed data sets to keep bundle size down. Note that Moment.js and this add-on are now in maintenance mode; for new projects the maintainers recommend a modern alternative such as Luxon or date-fns.

What You Get

• A moment.tz() constructor and .tz() chaining method that convert any moment into a named IANA zone
• The bundled IANA (Olson) time zone database with correct historical offsets and DST rules
• Zone-guessing (moment.tz.guess()), per-country zone listing, and default-zone helpers
• Data-loading utilities to pack, filter, and ship trimmed zone data for smaller bundles
• TypeScript definitions that augment the Moment module for typed zone operations

Common Use Cases

• Displaying a single UTC timestamp correctly across users in different time zones
• Scheduling and computing events against a fixed business zone regardless of server locale
• Detecting the browser’s current time zone to localize dates client-side
• Handling daylight saving time boundaries and ambiguous or invalid local times

Under The Hood

Architecture — moment-timezone.js is a single UMD module that wraps and augments Moment.js, attaching a moment.tz object and Moment.prototype.tz method. Zone data is stored in a compact packed base-60 string format that unpack()/unpackBase60() decode into Zone objects holding parallel untils/offsets/abbrs arrays; Zone.prototype._index runs a binary-search (closest) over the untils boundaries to find the applicable offset for a given timestamp, while parse resolves ambiguous and invalid local times via the moveAmbiguousForward/moveInvalidForward flags. Zone guessing (guess, ZoneScore, userOffsets) scores candidate zones against the runtime’s observed offsets. index.js is the default entry that loads data/packed/latest.json before re-exporting moment.

Tech Stack — Plain ES5 JavaScript (99.98% of the codebase) with one runtime dependency, moment ^2.29.4. The build uses Grunt (grunt-contrib-uglify, grunt-contrib-jshint, grunt-contrib-nodeunit, grunt-exec) driven by Gruntfile.js and tasks/, with hand-maintained TypeScript definitions (index.d.ts, moment-timezone-utils.d.ts) and the IANA (Olson) database as the underlying data source, versioned under data/ in meta, unpacked, and packed forms.

Code Quality — A substantial nodeunit test suite lives under tests/moment-timezone/ (parse, zone, guess, load, pack/unpack, base-60, add, link, utc, manipulate, and more), complemented by typing-tests/ that exercise the TypeScript definitions. Code style is enforced by .jshintrc and .editorconfig. The implementation is terse ES5 with small single-purpose functions and clear naming; as an established maintenance-mode project, coverage of the core encoding, lookup, and parsing paths is solid.

API Design — The public surface is small and ergonomic, layering onto Moment’s chainable style: moment().tz('America/Los_Angeles').format(...), plus moment.tz.guess(), moment.tz.zonesForCountry(), moment.tz.names(), and setDefault(). It requires almost no boilerplate to adopt in an existing Moment codebase, is documented on the momentjs.com timezone site with runnable examples, and is fully typed. A few methods (e.g. Zone.offset) are marked deprecated in favor of utcOffset, reflecting the library’s long history.