Migration | mmntjs

Compatibility-first migration bridge away from moment.js

CLI Migration Tool

The mmntjs CLI automates the mechanical part of migration: scanning source files, rewriting import paths, and generating a report to make rollout decisions visible.

# Scan first, then apply
 mmntjs migrate --check              # analyze

 mmntjs migrate --mode=alias         # npm alias (zero code change)

 mmntjs migrate --apply --dry        # preview rewrite

 mmntjs migrate --apply              # apply rewrite

 mmntjs migrate --apply --fns        # switch to fns

mmntjs migrate --check [dir]

Analyzes API usage, detects moment-timezone imports, and suggests the best entry point (full, lite, or fns).

mmntjs migrate --mode=alias [dir]

Analyzes + sets npm alias in package.json (zero code change, safe first step).

mmntjs migrate --apply [dir]

Auto-rewrites imports: moment → mmntjs (<code>/lite</code>/<code>/fns</code>) and moment-timezone → mmntjs + <code>import 'mmntjs-timezone'</code>.

mmntjs migrate --apply --fns [dir]

Force rewrites to 'mmntjs/fns' (standalone functions).

mmntjs migrate --apply --dry [dir]

Preview changes without writing files.

mmntjs report [dir]

Generates MIGRATION.md with usage stats and Temporal-readiness estimate.

mmntjs audit [dir]

Analyzes moment usage and flags risky APIs for manual review.

mmntjs stats [dir]

Prints usage count and migration progress summary.

Migration Overview

The safest way to adopt mmntjs is to treat it as a compatibility bridge first and an optimization or modernization step second. Teams usually get better results by reducing the migration surface one ownership boundary at a time instead of attempting a global swap.

A good migration plan also makes room for the possibility that a few modules should stay on moment.js longer than others. That is not failure. It is a controlled rollout doing its job.

Locale Import Migration

Locale imports deserve an explicit check during migration because moment.js commonly relies on side effects here. The mmntjs migration tool rewrites bare locale imports to mmntjs/locale-auto/* so that import "moment/locale/ja" keeps the same one-line behavior after migration.

Side-effect locale import

Before

import "moment/locale/ja";

After

import "mmntjs/locale-auto/ja";

Use this when you want the old one-line import behavior to keep working during migration.

If you do not want side effects, keep using mmntjs/locale/* as pure data and register only the locales you need with moment.locale(name, localeSpec).

import moment from "mmntjs";
import { jaLocale } from "mmntjs/locale/ja";

moment.locale("ja", jaLocale);

Staged Rollout

Phase 0

Inventory current moment usage with mmntjs migrate --check. Identify timezone, locale, and parsing hotspots.

Phase 0.5

Optionally set npm alias with mmntjs migrate --mode=alias: zero code change, lets your build tool resolve moment → mmntjs at install time.

Phase 1

Run mmntjs migrate --apply to auto-rewrite imports. For full-only codebases, start with mmntjs (full compat). For lite-compatible code, switch directly to mmntjs/lite.

Phase 2

If your code only uses basic formatting/manipulation, mmntjs/fns is an option: standalone functions with tree-shakeable cost. Run mmntjs migrate --apply --fns --dry to preview.

Phase 3

Run compatibility checks and review known differences for the APIs your codebase uses. Compare production-like behavior, especially invalid dates, offsets, and custom parsing.

Phase 4

Replace imports in a low-risk module or service and run the existing test suite. 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.

Migration Approaches by Build Tool

mmntjs supports three migration patterns. Which one works best depends on your package manager and test runner.

Approach	npm / yarn	pnpm	Jest / webpack	vitest	bun
A: npm alias `"moment": "npm:mmntjs"`	✅	✅*	✅	✅*	✅
B: Migration tool rewrite `mmntjs migrate --apply`	✅	✅	✅	✅	✅
C: Preload alias `Module._resolveFilename` hook	✅	✅*	✅	✅*	✅*

^* See notes below for details.

pnpm + vitest notes from a real Ghost trial

pnpm overrides: set "moment": "link:../mmntjs/dist" in the root package.json pnpm.overrides. The file: and npm: protocols can interact poorly with pnpm's virtual store in this setup.
vitest pool: with pool: forks, forked workers may not inherit the pnpm override resolution and can fail with Failed to resolve import "moment". Switching to pool: threads resolves that failure mode.
Approaches that did not hold up: vitest.resolve.alias with a 'moment' key does not reliably catch the bare module specifier. Directly replacing node_modules/moment with a symlink is overwritten by pnpm install.
moment-timezone: mmntjs migrate --apply now rewrites moment-timezone imports to mmntjs and adds a side-effect import "mmntjs-timezone". Verify that the timezone package is installed (npm install mmntjs-timezone) and test timezone-sensitive paths after migration.

Migration to Temporal

The report shows you where Temporal is already an option.

mmntjs report analyzes each file and estimates how many moment usages can be expressed directly with Temporal APIs. That number is not a migration promise; it is a signal for which modules are worth evaluating for a Temporal path first.

mmntjs report .

Generate a migration report that shows which moment usages are Temporal-ready.

Review the Temporal-ready count and API breakdown.

Focus on simple parse, format, add, diff calls that can be expressed directly in Temporal.

Use mmntjs as the bridge.

Keep existing moment-shaped code on mmntjs while writing new modules directly against Temporal APIs.

Expand incrementally.

The report makes it visible whether a module's moment usage is simple enough for a future Temporal rewrite.

mmntjs itself is the bridge: keep legacy moment-shaped code stable on mmntjs, write new code against Temporal where the report shows a clean mapping, and retire the old surface on your schedule rather than on a migration deadline.

Concrete Rollout Examples

Example A: package-by-package migration in a monorepo

Start with one internal package that formats and compares dates but does not own timezone-heavy scheduling logic.
Replace imports in that package only and run its tests plus a small integration slice that consumes it.
Add a few explicit fixtures for custom parsing, invalid inputs, and date-boundary math before expanding to the next package.

Example B: service-by-service migration

Begin with a service that has clear ownership and a deploy path independent from billing or scheduling-critical systems.
Switch the import path, compare outputs in staging or canary logs, then expand after those comparisons stay boring for a full release cycle.
Leave higher-risk services on moment.js longer if needed; controlled uneven rollout is better than a misleading all-at-once switch.

Good Fit

Large codebases with deep moment.js usage.
Teams that need behavioral continuity before broader modernization.
Owners who can stage adoption by module, package, or service.

Use Caution

Critical timezone-data workflows that assume full IANA behavior in core.
Codebases with little or no regression testing around date parsing and formatting.
Rollouts that demand a same-day global replacement without verification time.

Testing Strategy

Run the tests you already trust before writing new migration-specific wrappers.
Add a small set of targeted comparisons for parsing, invalid dates, offsets, and DST boundaries.
Prefer module-level rollout so failures have a clear owner and rollback path.

What Not To Rush

Do not start with your most time-sensitive billing, reporting, or scheduling path.
Do not treat a benchmark win as evidence of behavioral safety.
Do not assume timezone-heavy code is low-risk just because the tests are green in UTC.

Risk Checklist

Inventory custom parsing and custom format usage.
Identify timezone and locale heavy modules early.
Verify invalid-date behavior in both UI and business logic paths.
Expand rollout only after production-like comparisons pass.

If your team can complete this checklist for one low-risk module first, the next expansion step becomes much more credible to reviewers and maintainers.

Minimal Comparison Set

Before expanding beyond the first module or service, keep a tiny comparison set that reflects the way your application actually uses dates. It does not need to be large. It needs to be representative.

A custom-format parse example your application already relies on
An invalid input that should stay invalid
A timezone-offset or parseZone example used in production
A DST-adjacent example if the system operates in local time
A locale-sensitive format used in customer-visible output or exported reports

Roll out in stages, not in hope.