Front-end11 min read
Was Aura deprecated? What changed and how to move to LWC
Aura has no end date, but Salesforce's future is LWC. What was really retired, how the two live together and how to migrate a component without breaking the page.

Anyone who works with Salesforce has heard some version of this: "Aura was deprecated, it's all LWC now". It's half true. And the wrong half is exactly the one that decides whether you need to rewrite everything tomorrow or can migrate calmly.
This post separates what was actually retired from what simply stopped being the recommended path. Then it shows the same component written in both models and a way to migrate without breaking a single page.
An honest note: everything here comes from the official Salesforce documentation, linked at the end. The code samples are mine, written to show the switch from one model to the other.
TL;DR#
- Aura was not deprecated. As of this post, I found no official announcement of an end date for the framework. Aura components still run and can sit on the same page as LWC components.
- What was retired is the
uinamespace, that old family of Aura components (ui:inputText,ui:buttonand friends). Support ended on May 1, 2021. - The recommended path is LWC. That's where the new documentation and the migration tools point, and Experience Cloud LWR sites are built on top of it.
- Migration is not a line-by-line translation. The official guide says it plainly: it's the time to rethink the component.
- Migrate from the leaves to the root. An Aura component can have LWC children, but an LWC can't have Aura children.
- New component, always LWC. A stable Aura component nobody touches can wait.
What was actually deprecated#
The confusion comes from a Summer '21 release note with a very direct title: the Aura components in the ui namespace were deprecated. Many people only read the first half of that sentence.
The ui namespace was a set of basic components without the Lightning Design System (SLDS) look: text fields, buttons, menus, spinners. Salesforce ended support for them on May 1, 2021. They still work, but the company no longer accepts support cases about them.
The replacement is direct, with the equivalents from the lightning namespace:
Before (ui, deprecated) | After (lightning) |
|---|---|
ui:inputText | lightning:input (Aura) or lightning-input (LWC) |
ui:inputCheckbox | lightning:input with type="checkbox" |
ui:inputSelect | lightning:combobox or lightning-combobox |
ui:button | lightning:button or lightning-button |
ui:spinner | lightning:spinner or lightning-spinner |
ui:outputDate | lightning:formattedDateTime |
If your org still has ui: somewhere, that's the first target. It's not all of Aura that lost support, it's this family of components.
So does Aura still work?#
It does. Salesforce's own migration guide opens by saying that Aura components and LWC can exist in the same application, and lists three valid decisions after you migrate a first component:
- take on a larger migration;
- use LWC only for new components;
- stick with Aura for now.
In other words: there's no deadline to switch Aura off. What there is, is a very clear direction. The new documentation, the samples and the migration tools all point to LWC. And some places no longer take Aura: Experience Cloud LWR templates, for example, are based on the LWC model and lack several features of the Aura templates, such as application events.
In practice, Aura became supported legacy code: it runs, but it gets nothing new.
What changes from Aura to LWC#
Aura was created before browsers had Web Components. That's why it has its own model for everything: attributes declared in XML, its own events, a global $A object to talk to the server.
LWC uses what the browser already knows how to do: JavaScript classes, modules with import, Custom Elements and standard DOM events. Anyone who has written React, Vue or Web Components reads an LWC without much surprise.
The file structure changes too. The official guide maps it like this:
| Resource | Aura | LWC |
|---|---|---|
| Markup | sample.cmp | sample.html |
| Controller | sampleController.js | sample.js |
| Helper | sampleHelper.js | sample.js |
| Renderer | sampleRenderer.js | sample.js |
| CSS | sample.css | sample.css |
| Design (Lightning App Builder) | sample.design | sample.js-meta.xml |
Controller, helper and renderer become a single file. It's a class, and the helper functions become its methods.
The same component in both models#
A small example, but with the pieces that show up in almost every real component: it receives the record id from the page, fetches data from Apex when it opens and shows a list or an "empty" message.
The Apex (barely changes)#
public with sharing class ContactController {
@AuraEnabled(cacheable=true)
public static List<Contact> getContacts(Id accountId) {
return [
SELECT Id, Name
FROM Contact
WHERE AccountId = :accountId
WITH USER_MODE
LIMIT 50
];
}
}The guide says Apex is the same in both models. The only difference shows up if you want to use @wire in LWC: the method needs cacheable=true. A method that writes data can't be cacheable, so it's called imperatively (more on that below).
In Aura#
<aura:component controller="ContactController"
implements="flexipage:availableForRecordHome,force:hasRecordId">
<aura:attribute name="contacts" type="Contact[]" />
<aura:handler name="init" value="{!this}" action="{!c.doInit}" />
<lightning:card title="Contacts">
<aura:if isTrue="{!not(empty(v.contacts))}">
<ul class="slds-p-horizontal_medium">
<aura:iteration items="{!v.contacts}" var="contact">
<li>{!contact.Name}</li>
</aura:iteration>
</ul>
<aura:set attribute="else">
<p class="slds-p-horizontal_medium">No contacts yet.</p>
</aura:set>
</aura:if>
</lightning:card>
</aura:component>({
doInit: function (component, event, helper) {
helper.loadContacts(component);
}
})({
loadContacts: function (component) {
var action = component.get('c.getContacts');
action.setParams({ accountId: component.get('v.recordId') });
action.setCallback(this, function (response) {
if (response.getState() === 'SUCCESS') {
component.set('v.contacts', response.getReturnValue());
}
});
$A.enqueueAction(action);
}
})Three files, an init event, and the server call put together by hand with setParams, setCallback and $A.enqueueAction.
In LWC#
<template>
<lightning-card title="Contacts">
<template lwc:if={hasContacts}>
<ul class="slds-p-horizontal_medium">
<template for:each={contacts.data} for:item="contact">
<li key={contact.Id}>{contact.Name}</li>
</template>
</ul>
</template>
<template lwc:else>
<p class="slds-p-horizontal_medium">No contacts yet.</p>
</template>
</lightning-card>
</template>import { LightningElement, api, wire } from 'lwc';
import getContacts from '@salesforce/apex/ContactController.getContacts';
export default class ContactList extends LightningElement {
@api recordId;
@wire(getContacts, { accountId: '$recordId' })
contacts;
get hasContacts() {
return Array.isArray(this.contacts.data) && this.contacts.data.length > 0;
}
}<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
<apiVersion>62.0</apiVersion>
<isExposed>true</isExposed>
<targets>
<target>lightning__RecordPage</target>
</targets>
</LightningComponentBundle>What changed, point by point:
aura:attributebecame a class property.@apimakesrecordIdpublic, and the page fills it in because the component sits on a record page.initis gone.@wirecalls Apex when the component enters the screen and again whenrecordIdchanges. The$in front of'$recordId'is what turns on that reactivity.- The expression left the HTML. An LWC template doesn't accept
not(empty(...)). The logic moves to a getter (hasContacts), and the HTML just reads the result. aura:iterationbecamefor:each, with a requiredkeyon each item.aura:ifbecamelwc:if/lwc:else. The oldif:trueandif:falsestill exist, but the documentation says they're no longer recommended. In new code, uselwc:if,lwc:elseifandlwc:else.
One detail that catches people who migrate: @wire hands you an object with data and error. While it loads, both are empty. In a real component, handle the error and show a loading state.
What if the call can't be @wire?#
To write data, or to call Apex only when the user clicks, import the method and call it like a function that returns a Promise. Here, assuming a saveContact method in the same controller, without cacheable:
import { LightningElement, api } from 'lwc';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';
import saveContact from '@salesforce/apex/ContactController.saveContact';
export default class ContactForm extends LightningElement {
@api recordId;
lastName = '';
handleChange(event) {
this.lastName = event.target.value;
}
async handleSave() {
try {
await saveContact({ accountId: this.recordId, lastName: this.lastName });
this.dispatchEvent(new ShowToastEvent({ title: 'Contact saved', variant: 'success' }));
} catch (error) {
this.dispatchEvent(new ShowToastEvent({ title: 'Could not save', message: error.body.message, variant: 'error' }));
}
}
}Aura's force:showToast became ShowToastEvent, imported from lightning/platformShowToastEvent. That's the pattern for almost every force: event in Aura: it becomes a module you import.
Events: from fire() to dispatchEvent#
In Aura, the child registers the event in markup (aura:registerEvent), builds the event and fires it with fire():
({
handleClick: function (component) {
var selectEvent = component.getEvent('select');
selectEvent.setParams({ contactId: component.get('v.contactId') });
selectEvent.fire();
}
})In LWC there's no registration. The child creates a CustomEvent, which comes from the browser itself, and fires it with dispatchEvent:
handleClick() {
this.dispatchEvent(new CustomEvent('select', { detail: { contactId: this.contactId } }));
}The parent listens with on + the event name and reads the payload from event.detail:
<c-contact-item contact-id={contact.Id} onselect={handleSelect}></c-contact-item>handleSelect(event) {
const { contactId } = event.detail;
}Two conventions save you headaches: the event name is lowercase and has no on prefix (fire select, listen to onselect), and a camelCase property in JavaScript becomes kebab-case in HTML (contactId becomes contact-id).
For components that aren't parent and child, the replacement for Aura application events is Lightning Message Service (lightning/messageService), which works between components on the same page and across pages.
Equivalence table#
The swaps that show up most often, all taken from the official migration guide:
| Aura | LWC |
|---|---|
<aura:attribute> | class property (@api if public) |
<aura:iteration> | for:each with key |
<aura:if> | lwc:if, lwc:elseif, lwc:else |
init (aura:valueInit) | connectedCallback() |
aura:valueRender | renderedCallback() |
aura:valueDestroy | disconnectedCallback() |
aura:valueChange | getter and setter on the property |
component.getEvent() + fire() | new CustomEvent() + dispatchEvent() |
| application event | Lightning Message Service |
$A.enqueueAction() | @wire or importing the Apex method |
force:showToast | ShowToastEvent |
force:navigateToSObject, force:navigateToURL and similar | navigation service (lightning/navigation) |
force:refreshView | RefreshView API |
ltng:require | lightning/platformResourceLoader |
How the two live on the same page#
The most important rule of the whole migration is this one, straight from the documentation:
- an Aura component can contain an LWC;
- an LWC can't contain an Aura component.
Inside Aura, the LWC goes in with the c: namespace and its name in camelCase. Its events are handled like any other:
<aura:component implements="flexipage:availableForRecordHome,force:hasRecordId">
<c:contactList recordId="{!v.recordId}" onselect="{!c.handleSelect}" />
</aura:component>({
handleSelect: function (component, event) {
var contactId = event.getParam('contactId');
}
})This rule sets the order of the migration: you swap components from the bottom up. First the leaves, which have no children. The Aura parents keep working with LWC children inside. When all the children of a parent are LWC, it's the parent's turn.
One gotcha: if the Aura component receives other Aura components through a facet (an attribute of type Aura.Component[], like a "slot"), those need to be migrated first too, because the LWC won't be able to render them.
A migration plan that breaks nothing#
The official guide suggests an order, and it works well as a roadmap:
- Take inventory. List the Aura components in the org, who uses whom and how much testing each one has.
- Start with a UI-only component with no dependencies. Use base components (
lightning-*) whenever there's an equivalent. - Then the utilities without UI, which in Aura use
aura:method. In LWC they become a plain JavaScript module with exported functions. - Then the components that fire events.
- Then the ones that read records or call Salesforce APIs, swapping them for
@wireand the equivalent modules. - The parents last, once all their children are LWC.
And two pieces of advice worth more than any table:
- Migrate trees, not loose pieces. The guide says the performance and productivity gains show up when you migrate a whole tree of components, not one isolated component.
- Write Jest tests before deleting the Aura. LWC has unit tests with Jest. They're your guarantee that the new component does the same as the old one.
Does AI help?#
Salesforce now mentions AI assistants in the migration guide itself. The Salesforce DX MCP server has a toolset called aura-experts, in beta, that analyzes an Aura component, writes a specification and generates the LWC from it. The page for those tools notes that they were superseded by a migration skill (experience-aura-lwc-migrate), so check the current version before setting it up.
It's worth it to speed up the grunt work. But the documentation itself reminds you that the output is AI-generated, can be wrong, and that reviewing it is your responsibility. AI translates syntax very well. What it doesn't know is which old behavior was a bug and which was a business rule.
Is it worth migrating now?#
My recommendation, based on what Salesforce says and doesn't say:
- New component: always LWC. There's no reason to start anything in Aura today.
- You have
ui:in the org: migrate now. It has had no support since 2021. - You're creating or moving a site to the LWR template: you need LWC.
- You're going to change an Aura component a lot: migrate it while you're there. You're already paying the cost of understanding it.
- A stable Aura component nobody touches: it can wait. Rewriting working code just to rewrite it is risk with no return. Put it on the inventory and migrate it when you touch it.
Checklist#
- No
ui:components left in the org. - New components are born in LWC.
- Inventory of Aura components with dependencies and test coverage.
- Migration from the leaves to the root, with no LWC trying to contain Aura.
- Facets (
Aura.Component[]) migrated together with the component that receives them. if:true/if:falseswapped forlwc:if/lwc:elseif/lwc:else.- Apex methods used with
@wiremarked ascacheable=true. - Events with lowercase names, no
on, payload indetail. - Application events swapped for Lightning Message Service.
- Jest tests before deleting the Aura component.
- AI-generated code reviewed line by line.
References#
- Aura components in the ui namespace are deprecated (Summer '21 release note)
- List of deprecated ui components
- Migrate Aura components to Lightning Web Components
- Migration strategy
- Pick a component to migrate
- Migrate component bundle files
- Migrate events
- Render DOM elements conditionally with lwc:if
- Migrate Apex
- Aura-to-LWC migration tools (beta)
- Experience Cloud LWR template limitations
Comments
Sign in with your GitHub account to comment.
Read next

Front-end16 min read
Multilingual SEO in React: hreflang, prerendering, sitemap

Front-end15 min read
How I make AI videos with Remotion: a real case study

Front-end15 min read
How to share passwords securely: inside Yush