Setting Machine Options

The options field in createMachineConfig() allows you to fine-tune how your machine behaves at runtime — particularly in how it sets up context and actions.

---

⚙️ Available Options

1. dynamicSetupCtx

Enable dynamic context initialization on machine setup:

options: {
  dynamicSetupCtx: true;
}

This allows you to pass in new context values later via .setup().

---

2. dynamicSetupActions

Allow action handlers to be overridden at runtime:

options: {
  dynamicSetupActions: true;
}

Useful when different parts of your app want to inject different handler behavior.

---

3. sharedCtxIds

Declare global/shared context dependencies:

options: {
  sharedCtxIds: ['auth', 'globalCount'];
}

These IDs must match those registered with retomus.createCtx().

---

4. ctx Option Nesting

You can define defaults for individual context layers (state, sv, ref) and how to apply them:

options: {
  ctx: {
    overwrite: true; // Replace instead of merge
  }
}

---

📌 Complete Example

options: {
  dynamicSetupCtx: true,
  dynamicSetupActions: true,
  sharedCtxIds: ['sharedCtx'],
  ctx: {
    overwrite: true
  }
}

---

🧪 Best Practices

Tip	Why
Use overwrite: true only when you control the full context	Prevents unintentional value loss
Avoid too many sharedCtxIds	Increases coupling
Use dynamicSetup* only where needed	Keeps machines deterministic

---