mmntjs
Compatibility-first migration bridge away from moment.js

Moment-compatible migration bridge

A safer path away from moment.js.

mmntjs is a compatibility-first replacement for teams that cannot justify a risky date/time rewrite today, but still want a smaller, better-tested path forward.

See Compatibility View GitHub Read Migration Guide

Install

npm install moment@npm:mmntjs

Drop-in import

import moment from "moment";

moment("2024-01-01").add(1, "day");

Migration tool

mmntjs migrate --apply path/to/module

Problem

Most teams keep moment.js because replacing it is risky.

Date/time rewrites rarely fail in the obvious paths. They fail in parsing edge cases, invalid-date handling, DST transitions, offsets, and locale behavior that production code has quietly depended on for years.

Quick Start

Start small, then verify.

Evaluate mmntjs in one module, run the tests you already trust, and expand only after checking compatibility-sensitive behavior. 

npm install moment@npm:mmntjs

# or migrate one module first
npm install mmntjs
mmntjs migrate --apply path/to/module
import moment from "moment";

moment("2024-01-01").utc().format("YYYY-MM-DD");

If your codebase is large, the safest first move is usually one owned module with clear tests, not a global replacement across every service at once.

Getting Started Installation Options

Why mmntjs

Compatibility-first

The project is organized around preserving moment.js behavior where compatibility is promised.

Smaller modern implementation

It aims to reduce runtime and bundle cost without asking teams to rewrite date logic upfront.

Bridge to modern APIs

Adopt incrementally today, then move new code toward Temporal over time rather than via a forced rewrite.

Compatibility Snapshot

Proof should come before persuasion.

Area Status Notes
Parsing Mostly compatible Standard ISO, RFC 2822, custom format, array, object, sign-prefixed, and control-character inputs match moment.js. One known difference is mixed input like "93280531 09-3911".
Formatting Compatible Token and locale output are covered by upstream and locale-derived tests.
Manipulation Compatible add/subtract/startOf/endOf semantics are treated as compatibility-critical.
Query and comparison Compatible diff and comparison methods are covered by oracle and property tests.
Duration Compatible Construction, normalization, and relative-time behavior are part of the test matrix.
Locale Compatible Locale behavior is validated against the upstream locale suite.
UTC and parseZone Compatible UTC and fixed-offset behavior are tested; timezone package provides compatible IANA timezone data support.
Invalid dates Compatible Examples: moment("2024-02-31"), moment("not-a-date"), moment([2024, 1, 31]), and moment.invalid().
Open Full Compatibility Page

Quality

Quality is part of the product surface.

  • 678/678 moment.js compatibility tests passing
  • Differential oracle tests and property-based comparisons
  • Coverage-guided fuzzing plus grammar-based ISO generation
  • DST and timezone boundary tests across multiple timezones
  • Regression fixtures for previously discovered edge cases
  • TZ-sensitive test runs in UTC and non-UTC environments
Quality Methodology

Performance

Performance claims are scoped and reproducible.

  • Performance claims should be reproducible, scoped, and benchmark-specific.
  • Compatibility matters more than microbenchmark wins in ambiguous behavior.
  • Common-path overhead matters more than leaderboard language.
  • Bundle size is measured at multiple layers — raw, minified, gzip, brotli, bundled, parsed, evaluated — not reduced to a single number.
Benchmark Methodology Package Size

Migration Path

Sell safety more than novelty.

Phase 0

Inventory current moment usage and identify timezone, locale, and parsing hotspots.

Phase 1

Run compatibility checks and review known differences for the APIs your codebase uses.

Phase 2

Replace imports in a low-risk module or service and run the existing test suite.

Phase 3

Compare production-like behavior, especially invalid dates, offsets, and custom parsing.

Phase 4

Expand rollout module by module with ownership and rollback clarity.

Phase 5

Use the bridge period to guide new code toward modern date/time APIs, including Temporal where it fits.

Read Migration Guide

FAQ Preview

Answer the objections directly.

  • Why not just use Temporal?
  • Is mmntjs a full replacement for moment.js?
  • Does it include timezone data?
  • Why not dayjs, date-fns, or Luxon?
  • How should we migrate safely?
Full FAQ