Home / lwc / aura-to-lwc-migration

aura-to-lwc-migration

Migrating Aura components to LWC: feature mapping, interoperability wrappers, event translation, navigation patterns, and Aura-LWC coexistence strategies. NOT for new LWC development from scratch or Aura feature development — use lwc/experience-cloud-lwc-components.

• v1.0.0
• Salesforce Spring '25+
• Updated 2026-04-04
• User Experience
• Operational Excellence

• aura-to-lwc-migration
• interoperability
• event-translation
• lightning-message-service
• navigation-mixin

Open the skill folder on GitHub

Aura to LWC Migration

This skill activates when a practitioner needs to migrate an existing Aura component to a Lightning Web Component, navigate Aura-LWC interoperability during a partial migration, or translate Aura-specific patterns (events, navigation, lifecycle hooks) to their LWC equivalents.

Before Starting

Gather this context before working on anything in this domain:

• Inventory all Aura application events the component registers as handler or fires — these have no direct LWC equivalent and require redesign via Lightning Message Service (LMS).
• Confirm whether the component lives in a Lightning App Builder page, Experience Cloud page, custom tab, or embedded in Visualforce — each surface has different LWC metadata requirements (targets in *.js-meta.xml).
• Identify dynamic component creation (ltng:dynamicComponent, $A.createComponent) — this pattern has no LWC native equivalent and must be refactored using conditional rendering or a slot-based composition strategy.

Core Concepts

1. Aura-LWC Interoperability Direction

Salesforce supports one direction of mixed-framework embedding natively:

• LWC inside Aura — supported. An LWC component can be added to an Aura component's markup just like any other child component. The LWC runs in its own synthetic shadow context.
• Aura inside LWC — not directly supported. An LWC component cannot directly include an Aura component tag in its template. The workaround is to create a thin Aura wrapper that exposes the Aura component and communicates with the LWC layer via Lightning Message Service or standard DOM events.

This asymmetry is critical for incremental migration planning. You can always wrap an existing Aura component inside LWC context using the wrapper pattern, but you should plan to eliminate the wrapper as the Aura component itself is eventually migrated.

2. Event Model Translation

Aura has two event types with different scoping semantics:

• Component events (aura:event type="COMPONENT") — propagate up the component tree to registered ancestor handlers. LWC equivalent: CustomEvent dispatched with bubbles: false (or bubbles: true for limited propagation up the shadow DOM tree). Component events are a straightforward one-to-one translation.
• Application events (aura:event type="APPLICATION") — broadcast to all registered handlers org-wide, regardless of component hierarchy. LWC has no equivalent mechanism. The canonical replacement is Lightning Message Service (LMS) using a LightningMessageChannel metadata type. LWC subscribes with subscribe() from @salesforce/messageChannel, Aura can also publish/subscribe to the same channel during a transitional coexistence period.

3. Lifecycle Hook Mapping

Aura and LWC lifecycle hooks map as follows:

$A.getCallback() in Aura is used to re-enter the Aura lifecycle from async contexts. In LWC this is unnecessary — standard JavaScript async patterns (Promise, async/await) work directly and property reassignment triggers re-render automatically.

4. Navigation Pattern Translation

Aura navigation uses force:navigateToSObject, force:navigateToURL, and similar application events. LWC uses the NavigationMixin from lightning/navigation.

Common Patterns

Pattern 1: Incremental Page-by-Page Migration with LMS Bridge

When to use: The org has many Aura components wired together via application events. A big-bang rewrite is too risky. Components need to coexist during a multi-sprint migration.

How it works:

1. Create a LightningMessageChannel (.messageChannel-meta.xml) that carries the same payload the Aura application event carried.
2. Update the Aura component that fires the event to publish to the LMS channel (Aura can publish LMS using lightning:messageChannel).
3. Build the new LWC version of the consuming component using subscribe() on the same LMS channel.
4. Deploy both side-by-side. The Aura publisher and LWC subscriber coexist until the publisher is also migrated.
5. Migrate the publisher component last; once it is LWC, the LMS channel can be kept or collapsed into direct CustomEvent/property binding.

Why not the alternative: Attempting to wire Aura application events directly to LWC breaks silently — the LWC never receives the event. LMS is the only supported cross-framework messaging channel.

Pattern 2: Aura Wrapper for Legacy Aura Components in LWC Pages

When to use: A page or parent component has been migrated to LWC but it depends on an Aura child component that has not yet been rewritten.

How it works:

1. Create a thin Aura component (the wrapper) that contains only the legacy Aura component in its markup.
2. Expose @api attributes on the wrapper using aura:attribute — these become the interface the LWC can set.
3. Use LMS to pass data from the LWC parent to the Aura wrapper and back. The Aura wrapper subscribes to the LMS channel and updates the inner Aura component.
4. When the inner Aura component is fully migrated, delete the wrapper.

Why not the alternative: You cannot embed an Aura component tag directly in an LWC template — it will be treated as an unknown HTML element and silently ignored.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Audit the Aura component. List all aura:attribute (becomes @api or reactive @track/plain property), aura:event registrations and handlers, force:navigation events, $A.* API calls, lifecycle hooks, and any ltng:dynamicComponent usage.
2. Map events to LWC equivalents. Component events → CustomEvent. Application events → design a LightningMessageChannel. Document payload shape parity.
3. Scaffold the LWC component. Create the .js, .html, .css, and .js-meta.xml files. Port aura:attribute to @api properties. Port lifecycle hooks to connectedCallback / renderedCallback / disconnectedCallback.
4. Translate navigation calls. Extend the LWC class with NavigationMixin. Replace each force:navigate* event fire with the equivalent this[NavigationMixin.Navigate](...) call.
5. Implement LMS channel if needed. Create the .messageChannel-meta.xml, update the Aura component to publish on it, subscribe in the LWC with subscribe() inside connectedCallback and unsubscribe() inside disconnectedCallback.
6. Verify parity. Side-by-side functional testing: same inputs must produce same DOM output and navigation behavior. Check shadow DOM event propagation differences.
7. Deploy and clean up. Deploy the new LWC and, where applicable, the Aura wrapper. After the migration is confirmed stable, deprecate and remove the original Aura component and any bridge wrappers.

Review Checklist

Run through these before marking work in this area complete:

• [ ] All aura:attribute values have been ported to @api (public) or reactive private properties in the LWC
• [ ] Aura application events have been replaced with an LMS channel definition committed to source control
• [ ] force:navigate* calls have been replaced with NavigationMixin.Navigate calls
• [ ] Aura lifecycle hooks (init, afterRender, destroy) have been mapped to the correct LWC hooks
• [ ] The .js-meta.xml targets array matches the deployment surfaces (App Builder, Experience, etc.)
• [ ] Shadow DOM event propagation verified — events that used to bubble up the Aura tree may not propagate through LWC shadow roots without composed: true
• [ ] No $A.* API calls remain in the new LWC code
• [ ] Dynamic component creation patterns have been explicitly refactored or deferred with a documented plan

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. LWC cannot receive Aura application events — An LWC component that calls application.on('c:MyAppEvent', handler) or registers <aura:handler event="c:MyAppEvent"> will silently never fire. There is no runtime error. The LWC event listener simply does not exist in the Aura event registry. Impact: cross-component communication breaks completely and the failure is invisible in the console.
2. Shadow DOM blocks Aura-style event bubbling — In Aura, events bubble up the logical component tree regardless of rendering hierarchy. In LWC, the synthetic shadow DOM retargets events at shadow boundaries. An event dispatched inside an LWC child will not propagate outside the shadow root unless you set bubbles: true, composed: true. If a migrated component relied on event bubbling to reach a parent Aura component, you must add composed: true or redesign the communication.
3. renderedCallback fires on every render, not just the first — Aura's afterRender hook was triggered after initial render. LWC's renderedCallback fires after every re-render, including reactive property changes. Code that initializes a third-party library or modifies the DOM in renderedCallback without a hasRendered guard flag will run on every property update, causing duplicate initialization or DOM corruption.
4. ltng:dynamicComponent has no LWC equivalent — Aura's ltng:dynamicComponent allows runtime component injection by string name. LWC has no equivalent API. Migration requires either static conditional rendering (if:true / lwc:if) or a slot-based composition pattern. This is the most architecturally disruptive pattern to migrate and should be identified before estimating effort.
5. $A.enqueueAction replaced by wire or imperative Apex — not by any $A equivalent — LWC does not expose any $A global. Attempting to call $A.enqueueAction in LWC JavaScript throws a ReferenceError. Server calls must use @wire adapters for reactive data or import apexMethodName from '@salesforce/apex/...' for imperative calls wrapped in async/await.

Output Artifacts

Related Skills

• architect/platform-selection-guidance — Use when deciding whether to migrate at all or when comparing Aura vs LWC for new work
• lwc/lwc-imperative-apex — Use when porting $A.enqueueAction Apex calls to LWC imperative or wire patterns

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/well-architected.md
• templates/aura-to-lwc-migration-template.md
• scripts/check_aura_to_lwc_migration.py