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, but auto-registration does not happen. Users must call moment.locale('ja', jaLocale) explicitly.

Impact

Teams migrating from moment.js may find that locale imports compile but locale output does not change until explicit registration is added.

Workaround

Import the locale data and register it explicitly: import { jaLocale } from 'mmntjs/locale/ja'; moment.locale('ja', jaLocale). This is intentional: pure exports enable better tree-shaking.

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.