Composing Plugins

Commiq plugins — devtools, effects, persist — each attach to a sealed store independently. As your application grows, a single store may use two or three plugins simultaneously. Getting the initialization order right and cleaning up correctly prevents subtle bugs.

Plugin initialization order

All plugins consume a sealed store. The sequence is always:

const _store = createStore<AppState>(initialState)
  .useExtension(myExtension)       // extensions first
  .addCommandHandler("app:load", /* ... */)
  .addEventHandler(AppEvent.Loaded, /* ... */);

export const appStore = sealStore(_store);

const devtools = createDevtools({ stores: [{ name: "app", store: appStore }] });
const effects = createEffects(appStore);

Devtools + Effects

The most common combination. Devtools observes all events (including those triggered by effects), and effects react to events emitted by command handlers:

import { createDevtools } from "@naikidev/commiq-devtools-core";
import { createEffects } from "@naikidev/commiq-effects";
import { searchStore, SearchEvent } from "./search";

const devtools = createDevtools({
  stores: [{ name: "search", store: searchStore }],
});

const effects = createEffects(searchStore);

effects.on(
  SearchEvent.Completed,
  (data, ctx) => {
    ctx.queue(createCommand("search:add-recent", data.query));
  },
  { debounce: 300 },
);

Devtools captures every event in the timeline, including search:add-recent commands queued by the effect. This gives full visibility into the cause-and-effect chain. See effects and cancellation for the full effects API.

Full composition example

A store with devtools, effects, and OpenTelemetry:

import { createDevtools } from "@naikidev/commiq-devtools-core";
import { createEffects } from "@naikidev/commiq-effects";
import { createOtelPlugin } from "@naikidev/commiq-otel";

// ── Store (handlers registered, then sealed) ──

export const orderStore = sealStore(_store);

// ── Plugins ──

const devtools = createDevtools({
  stores: [{ name: "order", store: orderStore }],
  maxEvents: 500,
});

const effects = createEffects(orderStore);
effects.on(OrderEvent.Placed, async (data, ctx) => {
  await sendConfirmationEmail(data.orderId);
});

const otel = createOtelPlugin(orderStore, {
  serviceName: "order-service",
});

Each plugin operates independently. They share the same event stream but do not interfere with each other.

Cleanup

Destroy plugins in reverse initialization order. This matters in tests and during hot-module replacement:

// Teardown
effects.destroy();  // Stop effects first — prevents new commands from being queued
devtools.destroy();  // Then disconnect devtools

In tests, always clean up to prevent event listeners from leaking between test cases:

let effects: Effects;

beforeEach(() => {
  effects = createEffects(orderStore);
  // ... register effects
});

afterEach(() => {
  effects.destroy();
});

Writing plugin-friendly stores

Plugins work best when stores follow these conventions:

Keep the raw store private. Export only the sealed store — see store file structure. Register all handlers before calling sealStore.

Emit events for meaningful transitions. Plugins like effects react to events. A handler that silently mutates state without emitting events is invisible to effects — only BuiltinEvent.StateChanged fires, which carries no domain semantics. Emit explicit events for transitions that other parts of the system need to observe.