Salesforce Developer Guide

Aura to LWC Migration Guide

Step-by-Step for 2026

I built Delivery Hub — a fully LWC-native AppExchange app — from scratch. Before that, I spent years maintaining Aura codebases. This guide covers everything I wish I knew when I started migrating.

Why Migrate from Aura to LWC?

Initial Render

30-50% faster

Native web standards, smaller runtime

Bundle Size

Up to 60% smaller

No Aura framework overhead, tree-shaking

Testing

Jest support

Unit test locally without deploying to org

Developer Experience

Modern JS

ES modules, async/await, decorators

Tooling

Standard web tools

Chrome DevTools, VS Code IntelliSense

7-Step Migration Process

Audit Your Aura Components

Inventory every Aura component, helper, controller, and event. Categorize by complexity (simple UI, data-bound, event-heavy). Document which components talk to each other via application events vs component events.

Pro tip: Use Salesforce CLI: `sf lightning component list` to get a full inventory. Pair it with your IDE's dependency graph.

Map Aura Patterns to LWC Equivalents

Aura application events become LWC CustomEvent + pub/sub or Lightning Message Service (LMS). Component events become direct parent-child communication via @api properties and CustomEvent. aura:iteration becomes template for:each. aura:if becomes template if:true/if:false.

Pro tip: LMS is your best friend for cross-DOM communication. It replaces all application events cleanly.

Convert Data Layer First

Start with the Apex controllers. Move from @AuraEnabled to wire service where possible. Replace callback-based imperative calls with async/await patterns. LWC wire adapters (getRecord, getFieldValue) eliminate boilerplate for standard CRUD.

Pro tip: Wire service is reactive — the component re-renders automatically when data changes. This alone eliminates tons of manual refresh logic.

Rebuild Components Bottom-Up

Start with leaf components (buttons, inputs, display cards) and work up to container components. Each converted LWC can be consumed by remaining Aura components via <c:lwcComponentName> syntax during the transition.

Pro tip: LWC components work inside Aura containers but not vice versa. Plan your migration order accordingly.

Replace Aura Events with LMS

Create Lightning Message Channels for cross-component communication. Subscribe in connectedCallback, unsubscribe in disconnectedCallback. LMS works across Aura, LWC, and Visualforce — making incremental migration possible.

Pro tip: Define your message channels in force-app/main/default/messageChannels/. They deploy like any other metadata.

Handle Navigation & Routing

Replace force:navigateToSObject, force:navigateToURL, and lightning:navigation with the NavigationMixin. Import NavigationMixin from 'lightning/navigation' and extend your component class.

Pro tip: NavigationMixin is more powerful than Aura navigation — it supports page references, record pages, custom tabs, and external URLs with a consistent API.

Test & Performance Benchmark

Run Lighthouse on your Lightning pages before and after. LWC components typically render 30-50% faster than equivalent Aura components due to the native web component model and smaller framework overhead. Write Jest tests for LWC (not possible with Aura).

Pro tip: Jest testing is one of the biggest wins of LWC. You can finally unit test your Salesforce frontend code locally without deploying.

Common Gotchas

These trip up every team migrating from Aura to LWC. Save yourself the debugging time.

No Two-Way Binding

Aura has two-way binding with `{!v.property}`. LWC is one-way by default. You need to explicitly dispatch events from child to parent. This is better architecture but requires rethinking data flow.

CSS Scope Isolation

LWC uses shadow DOM (synthetic in most orgs). Your CSS is scoped to the component — no more global style leaks, but also no more reaching into child components with CSS selectors. Use CSS custom properties for theming.

Event Propagation Differences

Aura events bubble differently than DOM events. LWC CustomEvents follow standard DOM event behavior — bubbles: false and composed: false by default. If you need events to cross shadow boundaries, set composed: true.

Dynamic Component Creation

Aura's $A.createComponent() has no direct LWC equivalent. Use lwc:dynamic (GA in recent releases) or conditional rendering with template directives. For modal patterns, consider lightning-modal.

Force:hasRecordId & Design Attributes

Aura interfaces like force:hasRecordId become @api recordId in LWC. Design attributes (.design file) are replaced by @api properties exposed in the component's XML metadata file.

Lightning Data Service

Aura's force:recordData becomes LWC wire adapters (getRecord, getFieldValue, updateRecord). The wire approach is more declarative but has a learning curve if you are used to the imperative Aura style.

Case Study: Delivery Hub

Delivery Hub is a Salesforce-native project management app I built entirely in LWC — zero Aura components. It is listed on the AppExchange and used by Salesforce teams to manage deployments, user stories, and sprints without leaving Salesforce.

Building natively in LWC from day one meant: faster page loads, Jest unit tests for every component, clean data flow with wire service, and seamless integration with the Lightning platform. No Aura framework overhead, no legacy event patterns, no tech debt to migrate later.

If you are building a new Salesforce app today, go LWC-native. If you have an existing Aura codebase, use this guide to migrate incrementally.

Need Help Migrating?

I do this for a living. Whether you need a full Aura-to-LWC migration, a new LWC app built from scratch, or just a code review of your migration plan — I can help.

View Consulting Services Try Delivery Hub

Frequently Asked Questions

Is Salesforce deprecating Aura components?

Salesforce has not officially deprecated Aura, but all new development investment goes into LWC. Aura is in maintenance mode — Salesforce fixes bugs but doesn't add new features. New base components, performance improvements, and tooling all target LWC exclusively. The message is clear: migrate when you can.

Can LWC and Aura components coexist?

Yes. LWC components can be embedded inside Aura components, making incremental migration possible. However, Aura components cannot be used inside LWC components. This means you should migrate bottom-up: start with leaf components and work toward containers.

How long does an Aura to LWC migration take?

It depends on the size and complexity of your Aura codebase. A simple component (display card, button group) might take a day. A complex data-entry form with custom validation could take a week. A full app migration typically runs 2-6 months depending on team size and component count. Budget extra time for rewriting tests.

What is Lightning Message Service (LMS)?

Lightning Message Service is the recommended way to communicate between components that don't have a direct parent-child relationship. It works across LWC, Aura, and Visualforce, making it essential during migration. You define message channels as metadata, publish messages from one component, and subscribe from any other.

Should I rewrite from scratch or convert component by component?

For most teams, incremental migration is safer and more practical. Convert one component at a time, starting with the simplest. LWC components can live inside Aura containers during the transition. Only consider a full rewrite if the original Aura architecture has fundamental problems that a 1:1 conversion would preserve.

Get Glen’s Updates

Investing insights, new tools, and whatever I’m building this week. Free. No spam.

Unsubscribe anytime. I respect your inbox more than Congress respects property rights.

Keep Exploring

Guide