Credit: Ross Belmont

Converting Visualforce Pages to Lightning

If you’ve got an app on the Salesforce AppExchange, it’s only a matter of time before you’ll embark on the journey of making it Lightning Ready; hundreds of apps already are. Those who investigate it will quickly find that while changes to Apex code will be minimal, the front-end Visualforce pages will require major — if not complete — overhauls. So where do you begin?

While converting the first few pages of an enterprise-scale recruiting app to match the Lightning Experience, we noticed a pattern in our workflow. This pattern helped us define a process for the conversion, in which we:

  1. Sketch some ideas for the new page layout
  2. Match each front-end component to their Lightning counterpart (“What can I use from the Lightning Design System [SLDS] to replace this element?”)
  3. Build a functioning HTML/CSS prototype
  4. Assess the effectiveness of the new layout (“Does this page still serve its original purpose?”)
  5. Apply the new markup to the existing Visualforce pages
  6. Demo the page and request feedback from the app’s stakeholders and users
  7. Prepare the page for testing (manual and automated), packaging, and release


We begin by sketching a basic layout for the new page. Since the Lightning Experience has some new UI patterns, we look at how our current page can be revised to fit the new, unified design language. Often times, we consider multiple options before choosing one.

Credit: Ross Belmont


We then review the new layout and determine which of the components in SLDS can best replace the elements on the existing page. Choosing these replacements is usually a simple task and involves digging through the SLDS docs for candidates.


At this point, the front-end developers begin working with SLDS’s CSS library to implement the design. While the library itself has a bit of a learning curve, we developed Lightning-themed markup quickly once we had a solid grasp of its concepts. Prior experience with Block, Element, Modifier (BEM) conventions is recommended for working with SLDS.


With the newly developed layout, we take a step back and study the visuals. Will the original user flows remain in tact? Will each persona still be able to meet their objectives? These are questions we ask ourselves as we run through the original scenarios for the feature.


Developers would then take the front-end code and apply it to the existing Visualforce page. This process is usually fairly straightforward if the overall experience hasn’t deviated from the original designs. Front-end interactions with the back-end also remain untouched; initial page loads pull the same data and Remote Actions stay in tact.

What to Expect: Defining a Path to the SLDS Static Resource
SLDS icons are retrieved by URL paths in a <use> tag. When working in a Visualforce page, you will have to define the path to the Static Resource in order for icons to appear. This can be done several ways, depending on where the markup is written.
The standard markup for retrieving an icon from SLDS’s collection
Referencing the Static Resource directly with a Merge Field if the markup is inside of the Visualforce page
Defining the path to the Static Resource as a variable if you’re using a JavaScript framework that leverages templating
What to Expect: Debugging Broken JavaScript
Changes to the HTML will likely disrupt existing JavaScript on the page. New markup means new structures (classes, relationships, etc.), and these new structures will require new methods of targeting the proper elements for your scripts.
What to Expect: Finding Suitable Replacements for Your Plugins
In the past, we’ve turned to jQuery plugins to achieve specific UI interactivity. While SLDS provides components to replace a majority of these plugins, it also introduces the challenge of adding custom jQuery/JavaScript to the static markup. Our solution was to build our own library of plugins, which we eventually released as an open-source project called Appiphony Lightning JS (ALJS).


Once the working Visualforce page is complete, we demo the page to the app’s stakeholders, and some current users (if possible). We gather feedback and revise the page like we normally would.


As a feature takes shape (usually in the form of back-end code and several Visualforce pages), we prepare a package for the QA team to test. A few revisions and QA packages later, we create a release package for the AppExchange.

What to Expect: Reworking Your Automated Testing
Manually testing the new layout will rarely differ from testing the old layout. Automated testing scripts, however, will likely need to be rewritten entirely. Developers should work closely with the QA team to determine new methods of targeting elements and to update classes for the new markup. QA should also be aware that scripts that navigate between URLs will need to be reworked, as Lightning uses new base64-encoded URL parameters.

The app’s ‘New Requisition’ page before Lightning conversion
The app’s ‘New Requisition’ page after Lightning conversion

We are discovering new challenges each week, so our process is constantly evolving. We’re interested in hearing from other teams about what pitfalls they’ve come across and the solutions they’ve used, so share your stories with us. We’ll be writing more about our journey converting apps to be Lightning Ready in the weeks ahead.