Org Skills

Migration playbooks — Aura → LWC, Visualforce → LWC

Supporting material for salesforce-frontend-architecture. Agents load it on demand; it ships inside the skill folder.

RawSource

Target: Spring '26. Sources: Migrate Aura Components to Lightning Web Components, Composition with Aura, Lightning Usage App.

1. Inventory first, always

| Artefact            | Type | Where used            | Users/week | Classification        | Target            |
|---------------------|------|-----------------------|-----------:|-----------------------|-------------------|
| OrderList           | Aura | Order record page     |      1 200 | rewrite               | c-order-list LWC  |
| AccountFieldPanel   | Aura | Account record page   |        900 | replace with standard | Dynamic Forms     |
| LegacyPricingTool   | VF   | Button on Opportunity |          4 | retire                | — (delete Q2)     |
| QuotePdf            | VF   | Print quote           |        300 | keep                  | VF renderAs="pdf" |

Three quarters of the value is in the classification column. The cheapest migration is the one that deletes the component:

  • Replace with standard — Dynamic Forms, Dynamic Related Lists, list views and screen flows remove a surprising share of custom Aura.
  • Rewrite — genuinely custom interaction.
  • Retire — usage data (Lightning Usage App, Event Monitoring, or a logging component) decides this, not opinion.
  • Keep — Visualforce PDF rendering and a few Aura-only APIs have no LWC equivalent yet; say so explicitly so nobody re-litigates it.

2. Aura → LWC, in order

  1. Leaves first. An LWC can be used inside an Aura component; an Aura component cannot be used inside an LWC. So convert the innermost components, leave the Aura shell in place, and shrink it over time.
  2. Public API. aura:attribute with access="global" becomes @api; aura:method becomes an @api method.
  3. Events. Component events become CustomEvent; application events become Lightning Message Service, with a message channel that is a documented contract.
  4. Data. $A.enqueueAction becomes @wire for reads (cacheable=true on the Apex) and imperative await for writes; force:recordData becomes getRecord/updateRecord.
  5. Navigation and UI events. force:navigateToSObject becomes NavigationMixin; force:showToast becomes ShowToastEvent; lightning:overlayLibrary becomes lightning/modal.
  6. Markup. aura:if becomes lwc:if; aura:iteration becomes for:each with a stable key; expressions move out of the template into getters, because LWC templates do not evaluate expressions.
  7. Styling. Take the opportunity to move to SLDS 2 hooks rather than porting the old CSS as-is.
  8. Retire the wrapper and measure: EPT on the page before and after, from the Lightning Usage App, is the number that closes the ticket.

Interop rules worth stating up front: an LWC inside Aura receives @api props like any other component and its events bubble into Aura handlers if bubbles: true, composed: true — the one place that combination is the right answer.

3. Visualforce → LWC

  1. Split the page by user-facing function, not by file. One VF page often becomes a flow (for the process), Dynamic Forms (for the fields) and one LWC (for the part that is genuinely custom).
  2. Controllers and extensions become Service and Selector classes. The @AuraEnabled controller is a new thin façade on top; nothing of the old controller is exposed directly.
  3. apex:inputField validation moves to the platform: validation rules, required fields and a before-save flow's Custom Error element.
  4. PDF rendering stays on Visualforce (renderAs="pdf") or moves off platform to a document service — LWC cannot render PDFs.
  5. JavaScript remoting and <apex:includeScript> for third-party libraries become static resources plus loadScript.
  6. Delete the VF page and its tab in the same release that the replacement ships, or it lives forever.

4. Risk and sequencing

  • Migrate one page at a time behind a custom permission or an App Builder audience, so the old page stays available for the users who need it while the new one is validated.
  • Keep the Apex layer stable across the migration: if the service and selector classes are right, both UIs can call them and the swap is low risk.
  • Freeze feature work on an artefact being migrated; a moving target doubles the work.
  • Exit criteria per artefact: the replacement is live, the old artefact has zero usage for two weeks, and it is deleted from the repo — not just deactivated in the org.