# Migration playbooks — Aura → LWC, Visualforce → LWC

Target: Spring '26. Sources: [Migrate Aura Components to Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-introduction.html), [Composition with Aura](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-interop.html), [Lightning Usage App](https://help.salesforce.com/s/articleView?id=sf.lightning_usage_app.htm&type=5).

## 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.
