Tous les articles

Front-end12 min de lecture

Aura obsolète ? Ce qui a changé et comment migrer vers LWC

Aura n'a pas de date de fin, mais l'avenir de Salesforce, c'est LWC. Ce qui a vraiment été retiré, comment les deux cohabitent et comment migrer sans casser la page.

Aussi en Português, English, Español

Quiconque travaille avec Salesforce a déjà entendu une version de cette phrase : « Aura est obsolète, maintenant tout est en LWC ». C'est à moitié vrai. Et la moitié fausse est justement celle qui décide si vous devez tout réécrire demain ou si vous pouvez migrer tranquillement.

Cet article sépare ce qui a vraiment été retiré de ce qui a simplement cessé d'être la voie recommandée. Ensuite, il montre le même composant écrit dans les deux modèles et une façon de migrer sans casser aucune page.

Une précision honnête : tout ce qui suit vient de la documentation officielle de Salesforce, en lien à la fin. Les exemples de code sont les miens, écrits pour montrer le passage d'un modèle à l'autre.

TL;DR#

  • Aura n'est pas obsolète. À la date de cet article, je n'ai trouvé aucune annonce officielle de date de fin pour le framework. Les composants Aura fonctionnent toujours et peuvent cohabiter sur la même page que des composants LWC.
  • Ce qui a été retiré, c'est le namespace ui, cette ancienne famille de composants Aura (ui:inputText, ui:button et compagnie). Le support a pris fin le 1er mai 2021.
  • La voie recommandée, c'est LWC. C'est vers lui que pointent la nouvelle documentation et les outils de migration, et les sites LWR d'Experience Cloud sont construits dessus.
  • Migrer n'est pas traduire ligne par ligne. Le guide officiel le dit clairement : c'est le moment de repenser le composant.
  • Migrez des feuilles vers la racine. Un composant Aura peut avoir des enfants LWC, mais un LWC ne peut pas avoir d'enfants Aura.
  • Nouveau composant, toujours en LWC. Un composant Aura stable auquel personne ne touche peut attendre.

Ce qui a vraiment été retiré#

La confusion vient d'une note de version de Summer '21 au titre très direct : les composants Aura du namespace ui sont obsolètes. Beaucoup de gens n'ont lu que la première moitié de la phrase.

Le namespace ui était un ensemble de composants de base sans le style du Lightning Design System (SLDS) : champs de texte, boutons, menus, spinners. Salesforce a mis fin à leur support le 1er mai 2021. Ils fonctionnent encore, mais l'entreprise n'accepte plus de demandes de support à leur sujet.

Le remplacement est direct, avec les équivalents du namespace lightning :

Avant (ui, obsolète)Après (lightning)
ui:inputTextlightning:input (Aura) ou lightning-input (LWC)
ui:inputCheckboxlightning:input avec type="checkbox"
ui:inputSelectlightning:combobox ou lightning-combobox
ui:buttonlightning:button ou lightning-button
ui:spinnerlightning:spinner ou lightning-spinner
ui:outputDatelightning:formattedDateTime

Si votre org contient encore du ui: quelque part, c'est la première cible. Ce n'est pas tout Aura qui a perdu son support, c'est cette famille de composants.

Alors, Aura fonctionne encore ?#

Oui. Le guide de migration de Salesforce commence lui-même par dire que les composants Aura et LWC peuvent exister dans la même application, et cite trois décisions valables après avoir migré un premier composant :

  • lancer une migration plus large ;
  • utiliser LWC uniquement pour les nouveaux composants ;
  • rester sur Aura pour l'instant.

Autrement dit : il n'y a pas d'échéance pour éteindre Aura. Il y a en revanche une direction très claire. La nouvelle documentation, les exemples et les outils de migration pointent tous vers LWC. Et certains endroits n'acceptent déjà plus Aura : les templates LWR d'Experience Cloud, par exemple, reposent sur le modèle LWC et n'ont pas plusieurs fonctionnalités des templates Aura, comme les événements d'application.

En pratique, Aura est devenu du code legacy encore supporté : il tourne, mais il ne reçoit plus rien de nouveau.

Ce qui change entre Aura et LWC#

Aura a été créé avant que les navigateurs aient des Web Components. C'est pour ça qu'il a son propre modèle pour tout : attributs déclarés en XML, événements maison, un objet global $A pour parler au serveur.

LWC utilise ce que le navigateur sait déjà faire : classes JavaScript, modules avec import, Custom Elements et événements DOM standard. Si vous avez déjà écrit du React, du Vue ou des Web Components, vous lirez un LWC sans être dépaysé.

La structure des fichiers change aussi. Le guide officiel la décrit ainsi :

RessourceAuraLWC
Balisagesample.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 et renderer deviennent un seul fichier. C'est une classe, et les fonctions du helper deviennent ses méthodes.

Le même composant dans les deux modèles#

Un petit exemple, mais avec les pièces qu'on retrouve dans presque tous les vrais composants : il reçoit l'id de l'enregistrement de la page, va chercher des données en Apex à l'ouverture et affiche une liste ou un texte « vide ».

L'Apex (ne change presque pas)#

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
        ];
    }
}

Le guide indique que l'Apex est le même dans les deux modèles. La seule différence apparaît si vous voulez utiliser @wire en LWC : la méthode doit avoir cacheable=true. Une méthode qui écrit des données ne peut pas être cacheable, elle est alors appelée de façon impérative (je le montre plus bas).

En 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);
    }
})

Trois fichiers, un événement init, et l'appel au serveur monté à la main avec setParams, setCallback et $A.enqueueAction.

En 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>

Ce qui a changé, point par point :

  • aura:attribute est devenu une propriété de la classe. @api rend recordId public, et la page le remplit toute seule parce que le composant est sur une page d'enregistrement.
  • Le init a disparu. @wire appelle l'Apex quand le composant arrive à l'écran, puis à nouveau quand recordId change. Le $ devant '$recordId' est ce qui active cette réactivité.
  • L'expression a quitté le HTML. Un template LWC n'accepte pas not(empty(...)). La logique passe dans un getter (hasContacts), et le HTML se contente de lire le résultat.
  • aura:iteration est devenu for:each, avec une key obligatoire sur chaque élément.
  • aura:if est devenu lwc:if / lwc:else. Les anciens if:true et if:false existent encore, mais la documentation indique qu'ils ne sont plus recommandés. Dans du code neuf, utilisez lwc:if, lwc:elseif et lwc:else.

Un détail qui piège ceux qui migrent : @wire renvoie un objet avec data et error. Pendant le chargement, les deux sont vides. Dans un vrai composant, gérez error et affichez un état de chargement.

Et si l'appel ne peut pas passer par @wire ?#

Pour écrire des données, ou pour appeler l'Apex seulement quand l'utilisateur clique, importez la méthode et appelez-la comme une fonction qui renvoie une Promise. Ici, en supposant une méthode saveContact dans le même controller, sans 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' }));
        }
    }
}

Le force:showToast d'Aura est devenu ShowToastEvent, importé depuis lightning/platformShowToastEvent. C'est le schéma de presque tous les événements force: d'Aura : ils deviennent un module que vous importez.

Événements : de fire() à dispatchEvent#

En Aura, l'enfant déclare l'événement dans le balisage (aura:registerEvent), construit l'événement et le déclenche avec fire() :

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

En LWC, il n'y a pas de déclaration. L'enfant crée un CustomEvent, qui vient du navigateur lui-même, et le déclenche avec dispatchEvent :

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

Le parent écoute avec on + le nom de l'événement et lit le contenu dans event.detail :

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

Deux conventions évitent bien des maux de tête : le nom de l'événement s'écrit en minuscules et sans le préfixe on (déclenchez select, écoutez onselect), et une propriété en camelCase dans le JavaScript devient du kebab-case dans le HTML (contactId devient contact-id).

Pour des composants qui ne sont pas parent et enfant, le remplaçant des événements d'application d'Aura est Lightning Message Service (lightning/messageService), qui fonctionne entre composants d'une même page et entre pages différentes.

Table des équivalences#

Les remplacements les plus fréquents, tous tirés du guide officiel de migration :

AuraLWC
<aura:attribute>propriété de la classe (@api si publique)
<aura:iteration>for:each avec key
<aura:if>lwc:if, lwc:elseif, lwc:else
init (aura:valueInit)connectedCallback()
aura:valueRenderrenderedCallback()
aura:valueDestroydisconnectedCallback()
aura:valueChangegetter et setter sur la propriété
component.getEvent() + fire()new CustomEvent() + dispatchEvent()
événement d'applicationLightning Message Service
$A.enqueueAction()@wire ou import de la méthode Apex
force:showToastShowToastEvent
force:navigateToSObject, force:navigateToURL et similairesservice de navigation (lightning/navigation)
force:refreshViewRefreshView API
ltng:requirelightning/platformResourceLoader

Comment les deux cohabitent sur la même page#

La règle la plus importante de toute la migration est celle-ci, tirée directement de la documentation :

  • un composant Aura peut contenir un LWC ;
  • un LWC ne peut pas contenir de composant Aura.
Un LWC peut vivre dans un Aura. Le chemin inverse n'existe pas

Dans un Aura, le LWC s'insère avec le namespace c: et son nom en camelCase. Ses événements s'écoutent comme les autres :

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

Cette règle fixe l'ordre de la migration : vous remplacez les composants de bas en haut. D'abord les feuilles, qui n'ont pas d'enfants. Les parents Aura continuent de fonctionner avec des enfants LWC à l'intérieur. Quand tous les enfants d'un parent sont en LWC, c'est au tour du parent.

À chaque étape, chaque composant Aura n'a que des enfants qu'il sait afficher

Un piège : si le composant Aura reçoit d'autres composants Aura via une facet (un attribut de type Aura.Component[], comme un « slot »), ceux-là doivent aussi être migrés avant, parce que le LWC ne pourra pas les afficher.

Un plan de migration qui ne casse rien#

Le guide officiel propose un ordre, et il fonctionne bien comme feuille de route :

  1. Faites un inventaire. Listez les composants Aura de l'org, qui utilise qui et combien de tests a chacun.
  2. Commencez par un composant purement d'interface, sans dépendances. Utilisez les composants de base (lightning-*) dès qu'un équivalent existe.
  3. Puis les utilitaires sans interface, qui en Aura utilisent aura:method. En LWC, ils deviennent un module JavaScript classique, avec des fonctions exportées.
  4. Puis les composants qui déclenchent des événements.
  5. Puis ceux qui lisent des enregistrements ou appellent des API Salesforce, remplacés par @wire et les modules équivalents.
  6. Les parents en dernier, quand tous leurs enfants sont en LWC.

Et deux conseils qui valent plus que n'importe quel tableau :

  • Migrez des arbres, pas des pièces isolées. Le guide indique que le gain de performance et de productivité apparaît quand vous migrez un arbre entier de composants, pas un composant isolé.
  • Écrivez des tests Jest avant de supprimer l'Aura. LWC a des tests unitaires avec Jest. C'est votre garantie que le nouveau composant fait la même chose que l'ancien.

Et l'IA, elle aide ?#

Salesforce cite désormais des assistants IA dans le guide de migration lui-même. Le serveur MCP de Salesforce DX propose un ensemble d'outils appelé aura-experts, en bêta, qui analyse un composant Aura, rédige une spécification et génère le LWC à partir d'elle. La page de ces outils précise qu'ils ont été remplacés par une skill de migration (experience-aura-lwc-migrate), donc vérifiez la version actuelle avant de la configurer.

C'est utile pour accélérer le travail répétitif. Mais la documentation rappelle elle-même que le résultat est généré par une IA, qu'il peut être faux et que sa relecture est sous votre responsabilité. L'IA traduit très bien la syntaxe. Ce qu'elle ne sait pas, c'est quel ancien comportement était un bug et lequel était une règle métier.

Faut-il migrer maintenant ?#

Ma recommandation, d'après ce que Salesforce dit et ne dit pas :

  • Nouveau composant : toujours en LWC. Il n'y a aucune raison de démarrer quoi que ce soit en Aura aujourd'hui.
  • Vous avez du ui: dans l'org : migrez tout de suite. Il n'a plus de support depuis 2021.
  • Vous créez ou passez un site sur le template LWR : il vous faut du LWC.
  • Vous allez beaucoup modifier un composant Aura : profitez-en pour le migrer. Le coût de le comprendre, vous le payez déjà.
  • Un composant Aura stable auquel personne ne touche : il peut attendre. Réécrire du code qui marche juste pour le réécrire, c'est du risque sans retour. Mettez-le dans l'inventaire et migrez-le quand vous y toucherez.

Checklist#

  • Plus aucun composant ui: dans l'org.
  • Les nouveaux composants naissent en LWC.
  • Inventaire des composants Aura avec dépendances et couverture de tests.
  • Migration des feuilles vers la racine, sans LWC qui essaie de contenir de l'Aura.
  • Facets (Aura.Component[]) migrées avec le composant qui les reçoit.
  • if:true/if:false remplacés par lwc:if/lwc:elseif/lwc:else.
  • Méthodes Apex utilisées avec @wire marquées cacheable=true.
  • Événements nommés en minuscules, sans on, contenu dans detail.
  • Événements d'application remplacés par Lightning Message Service.
  • Tests Jest avant de supprimer le composant Aura.
  • Code généré par l'IA relu ligne par ligne.

Références#

Écrit par

Ingénieure logiciel et designer. J'écris sur ce que je rencontre en créant des apps, des APIs et des produits.

Commentaires

Connectez-vous avec votre compte GitHub pour commenter.