Migrating to v1

Messagevisor v1 makes the JavaScript SDK's supported surface explicit, tightens cross-language evaluation behavior, and completes the module, event, and diagnostic contracts.

Upgrade the CLI, SDK, framework packages, and Messagevisor modules together. Build fresh datafiles before deploying the upgraded application.

Use the factory as the runtime entry point#

The Messagevisor class is no longer a constructable package export. Create the runtime through createMessagevisor() and use Messagevisor only as a TypeScript type.

import { createMessagevisor, type Messagevisor } from "@messagevisor/sdk";
const m: Messagevisor = createMessagevisor({ datafile });

Replace code such as new Messagevisor(options) with createMessagevisor(options).

Remove caller-managed formatter caches#

Remove createMessagevisorCache(), MessagevisorCache, and the cache instance option. Formatter reuse is an SDK implementation detail in v1. A root instance owns its internal cache and spawned children reuse that infrastructure automatically.

const m = createMessagevisor({ datafile });
const child = m.spawn({ accountId: "account-1" });

Await module removal and cleanup#

addModule() returns an idempotent async removal function. removeModule() and close() are async because module cleanup may be async and failures are collected without skipping later modules.

const remove = m.addModule(module);
await remove();
await m.removeModule("module-name");
await m.close();

Module setup failures now roll back resolver and diagnostic registrations. Modules close in reverse registration order. Treat use after close() as unsupported.

Update event handling#

Events now have event-specific typed payloads. Every state event is emitted before its corresponding change event, and change.source identifies the originating event.

m.on("change", (event) => {
  console.log(event.source, event.snapshot);
});

For datafile_set, locale identifies the stored datafile that changed and activeLocale identifies the locale currently selected for evaluation. Loading another locale does not switch the active locale.

Review datafile updates#

Same-locale setDatafile(datafile) calls merge by default. Pass true as the second argument for replacement:

m.setDatafile(partialDatafile);
m.setDatafile(completeDatafile, true);

Datafiles remain keyed by locale. Datafiles for different targets of the same locale may therefore be merged when they come from the same CLI build output.

Review diagnostics#

Every diagnostic now has an always-present details object. Translation, locale, message, override, and source context lives in details. New stable diagnostics include missing_datafile, missing_format, invalid_format, and module_setup_error. Error-level diagnostics also emit the SDK's error event.

Review condition portability#

v1 deliberately removes implicit coercion from condition operators. Numeric, string, membership, regular-expression, and date operators reject values of the wrong type. Portable regular-expression flags are i, m, s, and u. Date comparisons require native Date values or complete timezone-qualified ISO date-times.

Run your Messagevisor tests after upgrading, especially tests around negative operators, regular expressions, dates, overrides that combine conditions and segments, locale fallbacks, and empty translations.

Update package declarations#

Messagevisor modules and framework adapters consume @messagevisor/sdk as a peer dependency in v1. Applications should install one compatible SDK version at the top level instead of bundling separate SDK copies through each module.

Suggested upgrade sequence#

Upgrade all Messagevisor packages together.
Replace direct construction and remove caller-managed formatter caches.
Await module removal and close() calls.
Update event payload access and diagnostic detail access.
Run npx messagevisor lint, npx messagevisor test, and application tests.
Build fresh datafiles and deploy them with the upgraded SDK.