Salesforce Lightning Migration Guide

Salesforce Lightning Migration — Step-by-Step Guide for 2026

If your organization is still running Salesforce Classic in 2026, you are operating on borrowed time. Salesforce has been systematically reducing investment in the Classic interface for years. New features ship exclusively in Lightning Experience. Critical security updates prioritize Lightning. The talent pool of developers willing to maintain Visualforce pages and JavaScript buttons shrinks with every graduating class of Salesforce professionals who learned nothing but Lightning Web Components.

Yet migrating from Classic to Lightning is not a simple UI toggle. Organizations that treat it as a cosmetic upgrade discover that their JavaScript buttons break, their Visualforce pages render poorly in Lightning containers, their custom CSS conflicts with the Lightning Design System, and their users revolt because workflows they depended on for years now require extra clicks. A poorly executed Salesforce Lightning migration can reduce productivity for months and create lasting user resistance to the platform.

At ESS ENN Associates, we have migrated dozens of Salesforce orgs from Classic to Lightning across industries. This guide walks through the complete migration process — from initial assessment through go-live and beyond — with the technical depth that actual migration projects require.

Why You Cannot Afford to Stay on Classic

The business case for Lightning migration goes beyond aesthetics. Salesforce has been building on the Lightning platform exclusively since 2019. Every major feature release — Dynamic Forms, Dynamic Actions, In-App Guidance, Enhanced Related Lists, Lightning App Builder enhancements — is Lightning-only. Organizations on Classic are missing productivity features that their competitors already use.

Performance improvements. Lightning Experience, particularly with Lightning Web Components (LWC), offers significantly better performance than Classic. LWC uses native browser APIs and modern JavaScript standards, resulting in faster page loads and more responsive interactions. Salesforce's own engineering team has moved entirely to LWC for new platform development, meaning Classic gets progressively less optimization attention.

Mobile-first design. The Salesforce mobile app is built on Lightning. Classic does not translate to mobile interfaces. If your sales team needs mobile CRM access — and in 2026, they absolutely do — Lightning is the only path.

Einstein AI features. Salesforce Einstein features including predictive lead scoring, opportunity insights, recommended actions, and Einstein Copilot are available exclusively in Lightning Experience. As AI becomes central to CRM effectiveness, Classic users are locked out of the platform's most impactful capabilities.

Talent availability. New Salesforce developers learn LWC. New administrators learn Lightning App Builder. Finding talent willing to work on Classic Visualforce pages at competitive rates becomes harder every year. Staying on Classic means paying a premium for increasingly rare skills while missing the innovations that the broader ecosystem is building.

Step 1: Lightning Readiness Assessment

Before writing a single line of migration code, you need to understand exactly what you are working with. The assessment phase identifies every element in your Classic org that requires attention during migration.

Run the Lightning Experience Readiness Check. Start with Salesforce's built-in assessment tool under Setup. It generates a report covering feature gaps, unsupported customizations, and Visualforce pages that need review. This report is a useful starting point, but it is not comprehensive. It will miss nuanced issues like embedded JavaScript in Visualforce pages, complex CSS overrides, and user experience patterns that technically work in Lightning but provide a degraded experience.

Inventory all JavaScript buttons and links. This is typically the largest migration task. JavaScript buttons are completely unsupported in Lightning. Every JavaScript button in your org needs to be cataloged, its business logic documented, and a Lightning-equivalent replacement planned. Common replacements include Flows, Quick Actions, Lightning Web Components, and custom Lightning Actions. For complex JavaScript buttons that call external APIs or perform multi-step operations, the replacement is usually a Lightning Web Component backed by an Apex controller.

Audit Visualforce pages. Visualforce pages fall into three categories during Lightning migration. Pages that use the standard Salesforce look and feel often work acceptably in Lightning with minimal changes — they render inside an iframe within the Lightning container. Pages with heavy custom CSS typically need styling updates to align with the Lightning Design System (SLDS). Pages that rely on JavaScript remoting, complex DOM manipulation, or Classic-specific APIs require significant rework or complete replacement with LWC.

Review custom Apex code. Most Apex code works identically in Classic and Lightning because it runs server-side. The exceptions are Apex controllers that reference Classic-specific page parameters, controllers tightly coupled to Visualforce page structure, and test classes that assert on Classic-specific behaviors. Review your Apex codebase for Classic dependencies, but expect this to be a smaller effort than the JavaScript and Visualforce work.

Identify integration touchpoints. If integrations embed Classic URLs, reference Classic page layouts, or use Classic-specific API patterns, they may need updates. Check OAuth callback URLs, embedded links in external systems, and any integration that constructs Salesforce URLs programmatically. For comprehensive integration guidance, see our Salesforce integration services guide.

Step 2: Migration Planning and Architecture Decisions

With the assessment complete, you now have visibility into the migration scope. The planning phase translates that scope into an executable project plan with clear architecture decisions.

Aura vs Lightning Web Components: The Framework Decision

If you are migrating in 2026, the answer is straightforward: build everything new in Lightning Web Components (LWC). Aura is Salesforce's first-generation Lightning component framework, and while it still works, Salesforce has clearly signaled that LWC is the future. LWC builds on web standards (HTML custom elements, Shadow DOM, modern JavaScript), delivers better performance, has a smaller bundle size, and aligns with how the broader web development community builds components.

The practical implications for your migration are significant. Any Visualforce page or JavaScript button you replace should be rebuilt as a Lightning Web Component, not an Aura component. If you have existing Aura components from a partial previous migration, you do not need to rewrite them immediately — Aura and LWC coexist — but new development should be exclusively LWC.

The key architectural differences that matter for migration planning: LWC components can be embedded inside Aura components, but Aura components cannot be embedded inside LWC components. This means LWC should be your leaf-level components, with Aura wrappers only where necessary for compatibility with existing Aura-based pages. Over time, as you convert Aura containers to LWC, you achieve a fully modern component architecture.

Page Layout Strategy with Lightning App Builder

Lightning App Builder is the declarative tool for creating Lightning record pages, home pages, and app pages. During migration, you need to decide whether to recreate your Classic page layouts directly in Lightning or redesign them to take advantage of Lightning-specific capabilities like Dynamic Forms and Dynamic Actions.

Dynamic Forms decouple field placement from the page layout, allowing you to place individual fields or field sections anywhere on a Lightning record page with visibility rules. Dynamic Actions do the same for buttons and actions. These features eliminate the need for multiple page layouts based on record type in many cases, replacing them with a single page with conditional visibility rules.

Our recommendation: use the migration as an opportunity to implement Dynamic Forms and Dynamic Actions for your most-used objects (Account, Contact, Opportunity, Case). The upfront investment in redesigning these pages pays off immediately in reduced page layout maintenance and better user experiences. For less-used objects, a direct translation of Classic layouts to Lightning is acceptable as a starting point.

Step 3: Build and Convert

The build phase is where you execute the conversion work identified during assessment and planned during architecture. This is the longest phase of the migration and benefits from a structured sprint-based approach.

Sprint 1-2: Foundation work. Enable Lightning Experience in a full-copy sandbox. Create Lightning apps using Lightning App Builder. Configure Lightning record pages for core objects. Set up the Lightning navigation and utility bar. This foundation work gives you a working Lightning environment that you can iterate on in subsequent sprints.

Sprint 3-5: JavaScript button replacement. Convert JavaScript buttons to Lightning alternatives in priority order — starting with buttons used daily by the most users. For each button, document the original business logic, implement the replacement (usually a Flow or LWC), test thoroughly in sandbox, and validate with business users. Track conversion progress on a shared dashboard so stakeholders can see migration momentum.

Sprint 5-8: Visualforce page conversion. Convert Visualforce pages to Lightning Web Components or Lightning-compatible Visualforce (using the lightningStylesheets attribute and SLDS classes). Pages that are used infrequently or are slated for retirement can be left as Visualforce running in iframes within Lightning — this is an acceptable short-term compromise that reduces migration scope without blocking go-live.

Sprint 8-10: Custom component development. Build any net-new Lightning components identified during the migration planning phase. This includes custom Lightning components that replace complex Classic workflows, dashboard components that leverage Lightning's richer visualization capabilities, and utility bar components for frequently-accessed tools.

Throughout the build phase, maintain a detailed issue log. Every migration surfaces unexpected compatibility issues, edge cases in business logic, and user experience decisions that were not apparent during planning. A well-maintained issue log becomes the testing checklist for QA.

Step 4: Testing Strategy

Testing a Lightning migration requires a multi-layered approach because you are simultaneously testing new components, compatibility of existing functionality, and the overall user experience in a new interface paradigm.

Unit testing for LWC. Lightning Web Components use the Jest testing framework. Every custom LWC should have unit tests that cover its rendering logic, event handling, and Apex wire adapter integration. Aim for 80%+ code coverage on LWC JavaScript, and test both happy-path and error scenarios. LWC testing is particularly important because client-side JavaScript errors in Lightning are harder to diagnose in production than server-side Apex errors.

Integration testing. Verify that all integrations function correctly in the Lightning context. Pay special attention to integrations that embed Salesforce pages in external systems (these may reference Classic URLs), external systems that call Salesforce APIs with Classic-specific parameters, and single sign-on flows that redirect to Classic URLs.

User acceptance testing (UAT). The most critical testing phase. Recruit representative users from each role (sales rep, sales manager, service agent, administrator) and have them perform their complete daily workflows in the Lightning sandbox. Document every point of friction, confusion, or failure. UAT frequently reveals that technically correct migrations still produce poor user experiences because of changed navigation patterns, moved buttons, or different click sequences for common tasks.

Performance testing. Compare page load times between Classic and Lightning for your most-used pages. Lightning should be faster for most interactions, but complex record pages with many related lists or heavy custom components can be slower if not optimized. Use Chrome DevTools and Salesforce's Lightning Performance Analysis tool to identify bottlenecks.

Step 5: User Adoption and Change Management

Technical migration is the easier half of a Lightning migration. The harder half is getting users to embrace the new interface and abandon their Classic workflows. User adoption failures are the number one reason Lightning migrations are considered unsuccessful, even when the technical migration is flawless.

Champion network. Identify 2-3 power users in each department and involve them early in the migration process. These champions should participate in UAT, provide feedback on page layouts, and serve as first-line support for their colleagues after go-live. Champions who feel ownership over the new interface become your strongest adoption advocates.

Role-based training. Generic Lightning training is almost useless. Create training materials specific to each role showing exactly how to perform their daily tasks in Lightning. Record short video walkthroughs (2-3 minutes each) for the 10 most common workflows per role. Make these videos accessible from within Salesforce using In-App Guidance, which is a Lightning-only feature that delivers contextual help directly in the interface.

Transition period with Classic fallback. Allow users to switch back to Classic for a defined transition period of 4-8 weeks. Monitor who switches back and why — this data tells you exactly which Lightning gaps need immediate attention. After the transition period, disable Classic access for everyone. Extending the transition period indefinitely removes the urgency to resolve Lightning issues and creates a permanent support burden of maintaining both interfaces.

Quick wins and visible improvements. Within the first week of Lightning rollout, deploy features that provide immediate visible value: personalized home pages with relevant dashboards, Kanban view for opportunity management, enhanced list views with inline editing, and the Lightning utility bar with frequently used tools. When users see that Lightning does things Classic cannot, adoption resistance decreases.

Step 6: Rollback Plan

Every Lightning migration needs a documented rollback plan, even if you never use it. The rollback plan provides a safety net that reduces organizational anxiety about the migration and gives stakeholders confidence that the project is managed responsibly.

A Lightning rollback is simpler than many system rollbacks because Salesforce maintains both Classic and Lightning interfaces simultaneously. Rolling back means reverting users to Classic — your data, customizations, and integrations are unaffected. However, any changes made exclusively for Lightning (such as Lightning record pages, LWC components, and Dynamic Forms configurations) remain in the org and simply become invisible to Classic users.

Define rollback triggers before go-live: specific scenarios that would cause you to revert to Classic. These might include critical business process failures that cannot be resolved within 48 hours, integration failures that prevent order processing or billing, or system performance degradation exceeding defined thresholds. Having pre-defined triggers prevents emotional decision-making during the stressful post-go-live period.

Post-Migration Optimization

Go-live is not the end of your Lightning migration — it is the beginning of Lightning optimization. In the weeks following go-live, focus on monitoring user adoption metrics in Salesforce's Lightning Usage App, addressing the top 10 user-reported friction points, optimizing page performance for slow-loading record pages, expanding Lightning features (Kanban boards, Path, Einstein Activity Capture) that were not included in the initial migration, and converting remaining Visualforce pages to LWC on a prioritized schedule.

For organizations building custom applications on the Lightning platform, our Salesforce custom app development guide covers advanced LWC patterns, Apex best practices, and CI/CD with Salesforce DX. And if your Lightning migration is part of a broader Salesforce implementation project, the migration should be scoped as a defined workstream within the larger implementation plan.

Frequently Asked Questions

For organizations planning broader Salesforce modernization alongside Lightning migration, our guides on data migration best practices and integration services provide complementary technical depth on adjacent workstreams.

At ESS ENN Associates, our Salesforce consulting team has guided organizations through Lightning migrations ranging from simple UI switches to complex enterprise transformations involving hundreds of Visualforce pages and thousands of users. If your Classic org needs a migration plan that accounts for both technical complexity and user adoption, contact us for a free assessment.