Docs

Known Differences

List currently known behavior differences in a way that helps teams assess practical impact.

Guidance

Trust Comes From Explicit Differences

A strong known-differences page is not an admission of weakness. It is a trust artifact. It tells reviewers exactly where to focus, what practical impact exists, and whether a workaround or tracking path already exists.

Tracked Differences

Parsing

Pre-release parsing edge cases

moment.js

Behavior for malformed inputs is defined by moment.js.

mmntjs

mmntjs matches moment.js for standard inputs, but one current known difference is "93280531 09-3911": mmntjs renders 9328-05-31 09:00 while moment.js renders 9328-06-02 09:11 even though valueOf() matches.

Impact

Low for normal ISO, RFC 2822, array, object, and format-string parsing. Relevant only if your app depends on unusual mixed-format strings.

Workaround

Review mixed-format parsing inputs and compare them directly against moment.js before rollout.

Timezone scope

Core scope is UTC and fixed-offset behavior, not full timezone data

moment.js

moment plus moment-timezone can be paired with IANA timezone data behavior when that package is in use.

mmntjs

Core mmntjs should be evaluated as covering UTC and fixed offsets. Full timezone-data expectations should be treated as a separate concern.

Impact

Important for systems that schedule or render by named timezone rather than by plain UTC or fixed offsets.

Workaround

Review timezone-sensitive code separately and use dedicated timezone support instead of assuming core behavior covers named-zone data cases.

Locale registration

Locale files do not auto-register on import

moment.js

Importing 'moment/locale/ja' automatically registers the locale via side effects during module evaluation.

mmntjs

mmntjs locale files export pure locale data with no side effects. Unused locale imports are safe for bundlers to tree-shake. For migration convenience, mmntjs also provides side-effect entries like mmntjs/locale-auto/ja.

Impact

Teams migrating from moment.js can choose between pure data imports and one-line side-effect locale registration.

Workaround

Use either import mmntjs/locale-auto/ja for drop-in migration or import { jaLocale } from 'mmntjs/locale/ja'; moment.locale('ja', jaLocale) for explicit registration and the smallest bundle.

CJS require interop

require('mmntjs') returns the default function with named exports attached

moment.js

require('moment') returns the moment function directly as module.exports.

mmntjs

require('mmntjs') also returns the moment function directly. Named exports like isMoment, Duration, and locale are attached as properties. This matches moment.js behavior; no adapter or .default access needed.

Impact

No impact for ESM import users. CJS require users get the same shape as moment.js.

Workaround

No workaround needed. This is handled at build time.

Performance comparison semantics

Some benchmark rows are cost comparisons, not perfectly equivalent APIs

moment.js

moment.js and its ecosystem comparisons often involve slightly different semantic definitions, especially around month or year differences.

mmntjs

mmntjs matches moment.js semantics in areas like truncated fractional diff, while some comparison libraries expose calendar-difference helpers instead.

Impact

This affects how benchmark tables should be interpreted, especially by reviewers comparing against date-fns or Temporal at face value.

Workaround

Read the methodology notes before using benchmark rows in architecture decisions, and prefer workload-specific comparisons where semantics truly align.

How To Use This Doc

Use this page as a migration review aid rather than as a generic tutorial. If the behavior in this area is business-critical, compare it directly against your current moment.js usage and record the outcome before expanding rollout.

The goal is not to eliminate every caveat before evaluation starts. The goal is to make the currently known caveats visible enough that they can be tested deliberately rather than discovered accidentally in production.