message-channel-patterns

# Message Channel Patterns

This skill activates when components that have no parent-child relationship must share state or events across DOM boundaries on a Lightning page. It covers creating message channels, wiring up publishers and subscribers in LWC and Aura, choosing the correct scope, and ensuring lifecycle cleanup.

---

## Before Starting

Gather this context before working on anything in this domain:

- Are the communicating components in a direct ownership chain, or are they truly unrelated (utility bar, workspace tab, sidebar, inline region)? If they are directly related, use `@api` / custom events from `component-communication` instead.
- What UI technologies are involved? LWC-to-LWC, LWC-to-Aura, and LWC-to-Visualforce all use LMS but the subscriber wiring syntax differs per technology.
- Is the subscriber inside a navigation tab (inactive-able) or always-on utility? This determines whether `APPLICATION_SCOPE` is required.
- Is the message channel already deployed? Channels must exist in the org before components that reference them can be deployed.

---

## Core Concepts

### Message Channel Metadata

A Lightning Message Channel is a platform metadata artifact — not a custom object, even though it uses the `__c` suffix. It lives in `force-app/main/default/messageChannels/` as a file named `channelName.messageChannel-meta.xml`. The file declares the channel's label, description, whether it can be used outside its defining namespace (`isExposed`), and optional typed field declarations (`lightningMessageFields`). Channels are deployed like any other metadata via `sf project deploy start`. A component that imports a channel that has not been deployed will fail at load time.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningMessageChannel xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>ProductSelected</masterLabel>
    <isExposed>true</isExposed>
    <description>Published when a product record is selected in the catalog.</description>
    <lightningMessageFields>
        <fieldName>productId</fieldName>
        <description>Salesforce record ID of the selected product</description>
    </lightningMessageFields>
    <lightningMessageFields>
        <fieldName>productName</fieldName>
        <description>Display name of the selected product</description>
    </lightningMessageFields>
</LightningMessageChannel>
```

### Publishing on a Channel (LWC)

LWC components use the `lightning/messageService` wire adapter alongside two imports: the channel symbol and `MessageContext`. `MessageContext` is injected via `@wire` and must be present before calling `publish`. The payload is a plain serializable JavaScript object — functions and symbols are not allowed.

```javascript
// productCatalog.js
import { LightningElement, wire } from 'lwc';
import { publish, MessageContext } from 'lightning/messageService';
import PRODUCT_SELECTED_CHANNEL from '@salesforce/messageChannel/ProductSelected__c';

export default class ProductCatalog extends LightningElement {
    @wire(MessageContext)
    messageContext;

    handleProductClick(event) {
        const payload = {
            productId: event.currentTarget.dataset.id,
            productName: event.currentTarget.dataset.name
        };
        publish(this.messageContext, PRODUCT_SELECTED_CHANNEL, payload);
    }
}
```

### Subscribing and the Subscription Lifecycle (LWC)

Subscribers call `subscribe()` in `connectedCallback` and **must** call `unsubscribe()` in `disconnectedCallback`. Failing to unsubscribe causes the handler to continue firing even after the component is removed from the DOM because LMS holds a strong reference to the subscription object. Each `subscribe()` call returns a subscription handle — store it and pass it to `unsubscribe()` later.

```javascript
// productDetail.js
import { LightningElement, wire } from 'lwc';
import { subscribe, unsubscribe, MessageContext, APPLICATION_SCOPE } from 'lightning/messageService';
import PRODUCT_SELECTED_CHANNEL from '@salesforce/messageChannel/ProductSelected__c';

export default class ProductDetail extends LightningElement {
    @wire(MessageContext)
    messageContext;

    subscription = null;

    connectedCallback() {
        this.subscription = subscribe(
            this.messageContext,
            PRODUCT_SELECTED_CHANNEL,
            (message) => this.handleMessage(message),
            { scope: APPLICATION_SCOPE }
        );
    }

    disconnectedCallback() {
        unsubscribe(this.subscription);
        this.subscription = null;
    }

    handleMessage(message) {
        // message.productId and message.productName are available
        this.selectedProductId = message.productId;
    }
}
```

### Scope: APPLICATION_SCOPE vs Default

By default, LMS only delivers messages to subscribers in the **currently active navigation tab or item**. Utility bar items are always active. If a subscriber component lives in a tab that the user has not yet visited or has navigated away from, it will not receive the message unless `APPLICATION_SCOPE` is specified. Use `APPLICATION_SCOPE` when:

- The subscriber is in a workspace tab that might not be the active tab.
- The publisher and subscriber could be on different console navigation items at the same time.
- You want to ensure all live component instances receive the message regardless of visibility.

Do not use `APPLICATION_SCOPE` as a blanket default — it increases coupling and can trigger stale subscriber logic in components that are technically rendered but not visible.

---

## Common Patterns

### Pattern 1: Master-Detail Page Coordination

**When to use:** A list (master) component and a detail panel (detail) component live in separate regions of a Lightning App page and share no common ancestor in the LWC hierarchy.

**How it works:**
1. Create `RecordSelected__c` message channel with a `recordId` field.
2. The master component publishes on row click.
3. The detail component subscribes with `APPLICATION_SCOPE` if either component could be in a non-active tab; otherwise use the default scope for active-tab-only delivery.
4. The detail component unsubscribes in `disconnectedCallback`.

**Why not the alternative:** A Pub/Sub utility helper (legacy pattern) is not supported, not type-safe, and has no lifecycle guarantees. Custom events cannot cross the DOM boundary between independent page regions.

### Pattern 2: Visualforce-to-LWC Bridge

**When to use:** A Visualforce page is embedded in a Lightning page alongside LWC components, and the VF page must notify LWC components of user actions.

**How it works:**
1. Create the message channel and deploy it to the org.
2. In the Visualforce page, use the `sforce.one` LMS API to publish:
   ```javascript
   // Inside Visualforce page JavaScript
   sforce.one.publish('MyChannel__c', { action: 'refresh', context: 'vf' });
   ```
3. LWC subscriber uses `subscribe()` with `APPLICATION_SCOPE` — the VF page is inside an iframe and scope must be `APPLICATION` for messages to cross the iframe boundary.
4. Note that `sforce.one.subscribe()` / `sforce.one.unsubscribe()` is the only supported Visualforce-side API for LMS; standard `publish` from `lightning/messageService` cannot be imported in VF pages.

**Why not the alternative:** Postmessage hacks across iframe boundaries bypass Salesforce's security model and are unsupported.

### Pattern 3: Cross-Namespace Channel Consumption

**When to use:** A managed package defines a channel marked `isExposed: true` and a subscriber org component must subscribe to it.

**How it works:** Import the channel using the namespace prefix:
```javascript
import PACKAGE_CHANNEL from '@salesforce/messageChannel/myNamespace__SomeChannel__c';
```
The double underscore is intentional — namespace separator plus the custom `__c` suffix both appear. Subscribers in the managed package or subscriber orgs can publish and subscribe freely as long as `isExposed` is `true` on the channel definition. AppExchange security review requires `isExposed: false` unless cross-namespace use is intentional and documented.

---

## Decision Guidance

| Situation | Recommended Approach | Reason |
|---|---|---|
| Parent passes data to child | `@api` property | Direct, declarative, no infrastructure needed |
| Child notifies parent of intent | Custom event | Propagates up the ownership tree cleanly |
| Unrelated components on same page | Lightning Message Service | Designed for cross-hierarchy pub/sub on a single page |
| Components in separate workspace tabs | LMS + APPLICATION_SCOPE | Default scope only fires for the active tab |
| Visualforce embedded in Lightning page | LMS via `sforce.one` on VF side | Only supported cross-iframe LMS API |
| Cross-namespace package channel | LMS with namespace prefix import | Channel must have `isExposed: true` |
| Components in separate browser tabs | Not possible with LMS | LMS is single-page; use server polling or Streaming API |

---


## Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the org edition, relevant objects, and current configuration state
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
4. Validate — run the skill's checker script and verify against the Review Checklist below
5. Document — record any deviations from standard patterns and update the template if needed

---

## Review Checklist

Run through these before marking work in this area complete:

- [ ] Message channel XML is deployed to the org before dependent components are deployed.
- [ ] Publisher wires `MessageContext` via `@wire(MessageContext)` before calling `publish()`.
- [ ] Subscriber calls `subscribe()` in `connectedCallback`, not in the constructor.
- [ ] Subscriber stores the handle returned by `subscribe()` and calls `unsubscribe(handle)` in `disconnectedCallback`.
- [ ] Scope is explicitly chosen: `APPLICATION_SCOPE` for cross-tab delivery, default for active-tab-only.
- [ ] Payload is a plain serializable JSON object — no functions, no class instances, no symbols.
- [ ] Cross-namespace channel references use the full `namespace__ChannelName__c` import path.
- [ ] `lightning:messageChannel` in Aura is an immediate child of `aura:component`, not nested inside another component or HTML element.

---

## Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. **Messages are constrained by iframe boundaries** — LMS messages published inside a Visualforce page embedded via iframe do not reach LWC subscribers on the same Lightning page unless the Visualforce page uses `sforce.one.publish()` and subscribers use `APPLICATION_SCOPE`. Using the standard `publish()` import from `lightning/messageService` inside a VF page is not supported.
2. **Cached-but-not-destroyed components keep receiving messages** — When navigating away from a Lightning page, Salesforce may cache the component tree without destroying it. Components in this state still receive LMS messages if their subscription was not cleaned up. Always unsubscribe in `disconnectedCallback`, and test behavior after navigation rather than only on first load.
3. **Channel must be deployed before importing components** — There is no late-binding for message channel imports. If `ProductSelected__c` does not exist in the org, any component with `import ... from '@salesforce/messageChannel/ProductSelected__c'` will fail to load entirely, blocking the whole page region, not just the message feature.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| `messageChannels/ChannelName.messageChannel-meta.xml` | Deployable channel metadata with field declarations |
| Publisher LWC | Component with `@wire(MessageContext)` and `publish()` call |
| Subscriber LWC | Component with `connectedCallback` subscription and `disconnectedCallback` cleanup |
| Scope decision | `APPLICATION_SCOPE` recommendation with rationale for the specific use case |
| Review findings | Notes on missing unsubscribe, wrong scope, iframe boundary, or deployment order issues |

---

## Related Skills

- `lwc/component-communication` — use when components share a direct ownership chain; prefer `@api` or custom events before reaching for LMS.
- `lwc/lifecycle-hooks` — use when LMS subscription or cleanup bugs are really timing issues related to `connectedCallback` / `disconnectedCallback` execution order.