Todos os artigos

Front-end11 min de leitura

Aura foi descontinuado? O que mudou e como migrar pra LWC

O Aura não tem data de fim, mas o futuro da Salesforce é o LWC. O que saiu de verdade, como os dois convivem e como migrar um componente sem quebrar a página.

Também em English, Español, Français

Quem mexe com Salesforce já ouviu alguma versão desta frase: "o Aura foi descontinuado, agora é tudo LWC". Ela é meio verdade. E a parte que está errada é justamente a que decide se você precisa reescrever tudo amanhã ou se pode migrar com calma.

Este post separa o que saiu de linha de verdade do que só deixou de ser o caminho recomendado. Depois mostra o mesmo componente escrito nos dois modelos e um jeito de migrar sem quebrar nenhuma página.

Um aviso honesto: tudo aqui vem da documentação oficial da Salesforce, linkada no fim. Os códigos são exemplos meus, escritos pra mostrar a troca de um modelo pro outro.

TL;DR#

  • O Aura não foi descontinuado. Até a data deste post, não encontrei nenhum anúncio oficial de data de fim pro framework. Componentes Aura continuam rodando e podem ficar na mesma página que componentes LWC.
  • O que saiu de linha foi o namespace ui, aquela família antiga de componentes Aura (ui:inputText, ui:button e companhia). O suporte acabou em 1º de maio de 2021.
  • O caminho recomendado é o LWC. É pra ele que apontam a documentação nova e as ferramentas de migração, e os sites LWR do Experience Cloud são construídos em cima dele.
  • Migração não é tradução linha a linha. O guia oficial diz isso com todas as letras: é a hora de repensar o componente.
  • Migre das folhas pra raiz. Um componente Aura pode ter filhos LWC, mas um LWC não pode ter filhos Aura.
  • Componente novo, sempre em LWC. Componente Aura estável que ninguém mexe pode esperar.

O que foi descontinuado de verdade#

A confusão nasce de uma nota de versão do Summer '21 com um título bem direto: os componentes Aura do namespace ui foram descontinuados. Muita gente leu só a primeira metade da frase.

O namespace ui era um conjunto de componentes básicos sem o visual do Lightning Design System (SLDS): campos de texto, botões, menus, spinners. A Salesforce encerrou o suporte a eles em 1º de maio de 2021. Eles até continuam funcionando, mas a empresa não aceita mais chamado de suporte sobre eles.

A troca é direta, pelos equivalentes do namespace lightning:

Antes (ui, descontinuado)Depois (lightning)
ui:inputTextlightning:input (Aura) ou lightning-input (LWC)
ui:inputCheckboxlightning:input com type="checkbox"
ui:inputSelectlightning:combobox ou lightning-combobox
ui:buttonlightning:button ou lightning-button
ui:spinnerlightning:spinner ou lightning-spinner
ui:outputDatelightning:formattedDateTime

Se o seu org ainda tem ui: em algum lugar, esse é o primeiro alvo. Não é o Aura inteiro que está sem suporte, é essa família de componentes.

Então o Aura ainda funciona?#

Funciona. O próprio guia de migração da Salesforce começa dizendo que componentes Aura e LWC podem existir na mesma aplicação, e lista três decisões válidas depois de migrar um primeiro componente:

  • fazer uma migração maior;
  • usar LWC só nos componentes novos;
  • continuar com Aura por enquanto.

Ou seja: não existe prazo pra desligar o Aura. O que existe é uma direção bem clara. A documentação nova, os exemplos e as ferramentas de migração apontam todos pro LWC. E alguns lugares já não aceitam Aura: os templates LWR do Experience Cloud, por exemplo, são baseados no modelo do LWC e não têm vários recursos dos templates Aura, como os eventos de aplicação.

Na prática, o Aura virou código legado com suporte: roda, mas não ganha nada novo.

O que muda do Aura pro LWC#

O Aura foi criado antes de os navegadores terem Web Components. Por isso ele tem um modelo próprio de tudo: atributos declarados em XML, eventos próprios, um objeto global $A pra falar com o servidor.

O LWC usa o que o navegador já sabe fazer: classes JavaScript, módulos com import, Custom Elements e eventos padrão do DOM. Quem já escreveu React, Vue ou Web Components lê um LWC sem estranhar muito.

A estrutura dos arquivos também muda. O guia oficial mapeia assim:

RecursoAuraLWC
Marcaçãosample.cmpsample.html
ControllersampleController.jssample.js
HelpersampleHelper.jssample.js
RenderersampleRenderer.jssample.js
CSSsample.csssample.css
Design (Lightning App Builder)sample.designsample.js-meta.xml

Controller, helper e renderer viram um arquivo só. É uma classe, e as funções do helper viram métodos dela.

O mesmo componente nos dois modelos#

Um exemplo pequeno, mas com as peças que aparecem em quase todo componente real: recebe o id do registro da página, busca dados no Apex quando abre e mostra uma lista ou um texto de "vazio".

O Apex (quase não muda)#

ContactController.cls
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
        ];
    }
}

O guia diz que o Apex é o mesmo nos dois modelos. A única diferença aparece se você quiser usar o @wire no LWC: o método precisa de cacheable=true. Método que grava dados não pode ser cacheable, e aí ele é chamado de forma imperativa (mostro mais abaixo).

Em Aura#

contactList.cmp
<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>
contactListController.js
({
    doInit: function (component, event, helper) {
        helper.loadContacts(component);
    }
})
contactListHelper.js
({
    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);
    }
})

Três arquivos, um evento init, e a chamada ao servidor montada à mão com setParams, setCallback e $A.enqueueAction.

Em LWC#

contactList.html
<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>
contactList.js
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;
    }
}
contactList.js-meta.xml
<?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>

O que mudou, ponto a ponto:

  • aura:attribute virou propriedade da classe. O @api deixa recordId público, e a página preenche sozinha porque o componente está numa página de registro.
  • O init sumiu. O @wire chama o Apex quando o componente entra na tela e chama de novo quando recordId muda. O $ na frente de '$recordId' é o que liga essa reatividade.
  • A expressão saiu do HTML. Template de LWC não aceita not(empty(...)). A lógica vai pra um getter (hasContacts), e o HTML só lê o resultado.
  • aura:iteration virou for:each, com key obrigatório em cada item.
  • aura:if virou lwc:if / lwc:else. Os antigos if:true e if:false ainda existem, mas a documentação diz que não são mais recomendados. Em código novo, use lwc:if, lwc:elseif e lwc:else.

Um detalhe que pega quem migra: o @wire entrega um objeto com data e error. Enquanto carrega, os dois estão vazios. Em componente de verdade, vale tratar o error e mostrar um estado de carregando.

E quando a chamada não pode ser @wire?#

Pra gravar dados, ou pra chamar o Apex só quando o usuário clica, importe o método e chame como uma função que devolve Promise. Aqui, supondo um método saveContact no mesmo controller, sem cacheable:

contactForm.js
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' }));
        }
    }
}

O force:showToast do Aura virou o ShowToastEvent, importado de lightning/platformShowToastEvent. É o padrão de quase todo evento force: do Aura: ele vira um módulo que você importa.

Eventos: do fire() ao dispatchEvent#

No Aura, o filho registra o evento na marcação (aura:registerEvent), monta o evento e dispara com fire():

contactItemController.js (Aura)
({
    handleClick: function (component) {
        var selectEvent = component.getEvent('select');
        selectEvent.setParams({ contactId: component.get('v.contactId') });
        selectEvent.fire();
    }
})

No LWC não existe registro. O filho cria um CustomEvent, que é do próprio navegador, e dispara com dispatchEvent:

contactItem.js
handleClick() {
    this.dispatchEvent(new CustomEvent('select', { detail: { contactId: this.contactId } }));
}

O pai escuta com on + nome do evento e lê o conteúdo em event.detail:

contactList.html
<c-contact-item contact-id={contact.Id} onselect={handleSelect}></c-contact-item>
contactList.js
handleSelect(event) {
    const { contactId } = event.detail;
}

Duas convenções evitam dor de cabeça: o nome do evento vai em minúsculas e sem o prefixo on (dispare select, escute onselect), e propriedade em camelCase no JavaScript vira kebab-case no HTML (contactId vira contact-id).

Pra componentes que não são pai e filho, o substituto dos eventos de aplicação do Aura é o Lightning Message Service (lightning/messageService), que funciona entre componentes da mesma página e de páginas diferentes.

Tabela de equivalências#

As trocas que mais aparecem, todas tiradas do guia oficial de migração:

AuraLWC
<aura:attribute>propriedade da classe (@api se for pública)
<aura:iteration>for:each com key
<aura:if>lwc:if, lwc:elseif, lwc:else
init (aura:valueInit)connectedCallback()
aura:valueRenderrenderedCallback()
aura:valueDestroydisconnectedCallback()
aura:valueChangegetter e setter na propriedade
component.getEvent() + fire()new CustomEvent() + dispatchEvent()
evento de aplicaçãoLightning Message Service
$A.enqueueAction()@wire ou import do método Apex
force:showToastShowToastEvent
force:navigateToSObject, force:navigateToURL e afinsserviço de navegação (lightning/navigation)
force:refreshViewRefreshView API
ltng:requirelightning/platformResourceLoader

Como os dois convivem na mesma página#

A regra mais importante de toda a migração é esta, direto da documentação:

  • um componente Aura pode conter um LWC;
  • um LWC não pode conter um componente Aura.
O LWC pode morar dentro do Aura. O caminho inverso não existe

Dentro de um Aura, o LWC entra com o namespace c: e o nome em camelCase. Os eventos dele são ouvidos como qualquer outro:

accountPanel.cmp
<aura:component implements="flexipage:availableForRecordHome,force:hasRecordId">
    <c:contactList recordId="{!v.recordId}" onselect="{!c.handleSelect}" />
</aura:component>
accountPanelController.js
({
    handleSelect: function (component, event) {
        var contactId = event.getParam('contactId');
    }
})

Essa regra define a ordem da migração: você troca os componentes de baixo pra cima. Primeiro as folhas, que não têm filhos. Os pais em Aura continuam funcionando com filhos LWC dentro. Quando todos os filhos de um pai já são LWC, chega a vez do pai.

Em cada etapa, todo componente Aura só tem filhos que ele sabe renderizar

Uma pegadinha: se o componente Aura recebe outros componentes Aura por facet (um atributo do tipo Aura.Component[], como um "slot"), esses também precisam ser migrados antes, porque o LWC não vai conseguir renderizá-los.

Um plano de migração que não quebra nada#

O guia oficial sugere uma ordem, e ela funciona bem como roteiro:

  1. Faça um inventário. Liste os componentes Aura do org, quem usa quem e quanto teste cada um tem.
  2. Comece por um componente só de interface, sem dependências. Use os componentes base (lightning-*) sempre que existir equivalente.
  3. Depois os utilitários sem interface, que no Aura usam aura:method. No LWC eles viram um módulo JavaScript comum, com funções exportadas.
  4. Depois os componentes que disparam eventos.
  5. Depois os que leem registros ou chamam APIs da Salesforce, trocando por @wire e pelos módulos equivalentes.
  6. Por último os pais, quando todos os filhos já forem LWC.

E dois conselhos que valem mais que qualquer tabela:

  • Migre árvores, não peças soltas. O guia diz que o ganho de desempenho e de produtividade aparece quando você migra uma árvore inteira de componentes, não um componente isolado.
  • Escreva testes em Jest antes de apagar o Aura. LWC tem testes unitários com Jest. É a sua garantia de que o componente novo faz o mesmo que o antigo.

E a IA ajuda?#

A Salesforce agora cita assistentes de IA no próprio guia de migração. O servidor MCP do Salesforce DX tem um conjunto de ferramentas chamado aura-experts, em beta, que analisa um componente Aura, escreve uma especificação e gera o LWC a partir dela. A página dessas ferramentas avisa que elas foram substituídas por uma skill de migração (experience-aura-lwc-migrate), então confira a versão atual antes de configurar.

Vale pra acelerar a parte braçal. Mas a própria documentação lembra que a saída é gerada por IA e pode vir errada, e que revisar é sua responsabilidade. A IA traduz sintaxe muito bem. O que ela não sabe é qual comportamento antigo era bug e qual era regra de negócio.

Vale migrar agora?#

Minha recomendação, olhando pro que a Salesforce diz e não diz:

  • Componente novo: sempre LWC. Não existe motivo pra começar nada em Aura hoje.
  • Tem ui: no org: migre já. Isso está sem suporte desde 2021.
  • Vai criar ou mudar um site pro template LWR: precisa de LWC.
  • Vai mexer bastante num componente Aura: aproveite e migre. O custo de entender o componente você já está pagando.
  • Componente Aura estável, que ninguém mexe: pode esperar. Reescrever código que funciona só por reescrever é risco sem retorno. Coloque no inventário e migre quando for tocar nele.

Checklist#

  • Nenhum componente ui: sobrando no org.
  • Componente novo nasce em LWC.
  • Inventário dos componentes Aura com dependências e cobertura de testes.
  • Migração das folhas pra raiz, sem LWC tentando conter Aura.
  • Facets (Aura.Component[]) migrados junto com o componente que os recebe.
  • if:true/if:false trocados por lwc:if/lwc:elseif/lwc:else.
  • Método Apex usado com @wire marcado como cacheable=true.
  • Eventos com nome em minúsculas, sem on, conteúdo em detail.
  • Eventos de aplicação trocados por Lightning Message Service.
  • Testes em Jest antes de apagar o componente Aura.
  • Código gerado por IA revisado linha a linha.

Referências#

Escrito por

Engenheira de software e designer. Escrevo sobre o que encontro construindo apps, APIs e produtos.

Comentários

Pra comentar, entre com sua conta do GitHub.