Plugins

Plugins observe a journey and add namespaced APIs or snapshot data. They do not intercept navigation, replace snapshots, or merge methods into the base machine.

Add plugins

import { createLinearJourney } from "@rxova/journey-core";
import { createReplayPlugin } from "@rxova/journey-core/plugins";
import { createAnalyticsPlugin } from "@rxova/journey-core/plugins";

const machine = createLinearJourney(definition, {
  plugins: [createReplayPlugin(), createAnalyticsPlugin({ track })]
});

machine.plugins.replay.getReplaySession();
machine.plugins.analytics.getRecentEvents();

Plugin names must be unique within a machine. Keep a plugin array as a readonly tuple when you need precise TypeScript inference.

Machine and snapshot extensions

A plugin can contribute either or both:

machine.plugins[name];
machine.getSnapshot().plugins[name];

Machine extensions are commands and reads implemented by the plugin. Snapshot extensions are derived, observable values suitable for selectors and UI rendering.

Built-in plugins

Plugin	Purpose
Persistence	Write status, context, and timeline on every observed change.
Analytics	Normalize lifecycle observations and custom analytics events.
Replay	Record a bounded, exportable runtime session.
Execution paths	Track realized paths for current and finished runs.

Each plugin is published through a separate package entry point so unused integrations do not add to a factory’s bundle.

Plugin guarantees

setup runs once per machine.
Per-machine state should be created inside setup, even when one plugin object is reused.
Host observation callbacks are isolated from the core pipeline.
onDispose callbacks run during machine teardown and cannot break other teardown work.
Snapshot derivation receives the previous extension so plugins can preserve references.

Where to next