Learn the Process for Developing Aura Components
- Create a harness app for viewing and testing Lightning components under development.
- Create a development app for hosting your components in Lightning Experience.
In your production org, My Domain lets you create a subdomain unique to your organization. With My Domain, you replace the instance URL that Salesforce assigns you, such as https://na17.lightning.force.com, with your chosen subdomain, for example, https://mydomainname.lightning.force.com.
My Domain is required to create custom Lightning components and set up single sign-on (SSO) in an org. To learn more about My Domain, check out this knowledge article. To learn how to activate it in your production org, see the User Authentication module.
There’s no simple way to preview an Aura component during development. You can’t click a button or go to a URL to see individual components. This difference can take some getting used to for Visualforce developers, because Visualforce makes it so easy to create a new page, and to reload it as you make changes.
The Aura Components programming model is quite different. We talk about how and why in the Aura Components Core Concepts module. For now, let’s focus on how to quickly load and view your component during development.
We’re going to describe two ways that you can set up a “preview” environment for your components under development. These two methods have different purposes. The first, using a harness app, is easy to set up, and works well for learning the basics of Aura components. It’s also useful long-term if you want to build components that live “outside” of Salesforce. (See the Resources for some details on what that means.)
The second, creating a development context inside Lightning Experience, is more involved to set up, and reloading your component is slower. But you can’t develop components that integrate with Lightning Experience while testing outside of Lightning Experience. Long-term, this is probably what you’ll use most frequently.
Developer Console and VS Code
In this unit, you set up your preview environment in the Developer Console, and your development environment in VS Code. To do this, you need to install VS Code, Salesforce CLI and Salesforce Extension Pack as instructed in the previous unit.
Create a “Harness” App
Let’s start simple, with the lightest weight way to develop and preview an Aura component—inside a “harness” app, a stand-alone “my.app” that contains only your component.
The harness app (1) is a stand-alone Lightning application that exists only to be a shell with a directly accessible URL. It contains only one thing, the top-level component you’re working on. In the illustration, that’s a My Expenses component (2) for creating a new expense. (You might recognize it from the Aura Components Basics module, where we build it from scratch.)
Here’s how to create a harness app.
- Open the Developer Console, and select .
- In the New Lightning Bundle panel, enter harnessApp for the app name, and click Submit.
We know we said you should use VS Code for development, and you should. Here we’re using the Developer Console for one thing only: that Preview button. When you click it, a new (and for now, blank) window opens. This is the window where you can reload your component to see changes while developing it.
Wait a minute! Didn’t we just say that there’s no button you can click to see a component under development? What exactly is that Preview button?!?
The Preview button lets you see a Lightning application, not a component. The two are different because, well, reasons. You put components into an app, as you’ll do in the next section.
Create a Top-Level Component
We use the terms “app” and “component” a lot in Salesforce. Let’s talk about how the terms apply to what you’re doing here. You just created a stand-alone Lightning application in the Developer Console, which we’ve called a harness app. That “application” is just a shell—it’s going to have very little code in it— just a reference to the component you’re about to create.
The component you’ll put in it is the real “app,” the top level thing you can add to Lightning Experience, or the Salesforce app, or wherever. All of the real code for your feature goes into this component or its child components. You can call it a widget, or a top-level component, or a lot of things. But it’s better to not call it an app, because “app” has some specific meanings in Lightning components and Lightning Experience.
Confused? Let’s do something concrete. We’re going to build a component in VS Code and deploy it to your org.
- Start VS Code.
- In Visual Studio code, press Command + Shift + P on a Mac or Ctrl + Shift + P on Windows or Linux to open the Command Palette.
- Type SFDX:Create Project.
- Give the project the name MyComponent, Press Enter.
- Navigate to a folder you want and click Create Project to save the project.
- Open the Command Palette again, and type SFDX:Create Lightning Component.
- Give the new component the name myFirstComponent, and press Enter.
- Press Enter again to accept the location
Now, under the force-app/main/default/aura directory, you should see a myFirstComponent directory containing several files.
You’ll also see a force-app/main/default/lwc directory. The lwc directory can contain Lightning web component files. You have two programming models for creating Lightning components: the Aura programming model or the Lightning Web Components programming model. This module focuses on Aura components.
- In the myFirstComponent directory, notice that one file extension is “.cmp”. In the
myFirstComponent.cmp file, replace the contents with the following markup and save the
Follow these steps to authorize your org with VS Code and deploy your Aura component.
- Open the Command Palette and type SFDX:Authorize an Org and press
See the Trailhead Playground Management module to get your username and password.
- Press Enter again to accept the default login option.
- Press Enter again to accept the default alias for this connection.
- When the browser opens, log in to your org and allow access if prompted. After successfully logging in, return to VS Code.
- Right-click on the default directory and select SFDX:
Deploy This Source to Org.
VS Code should indicate that the deployment successfully ran. If you don’t see the SFDX: Deploy This Source to Org command, you haven’t authorized your org with VS Code. Try again.
Now, go back to the Developer Console in your org. If the harness app isn’t already open, click, open the c:harnessApp folder, select APPLICATION and click Open Selected.
- Add the component to the harness app. Replace the contents of harnessApp.app with the
<aura:application> <c:myFirstComponent/> </aura:application>
- Save the file (File > Save).
- Select Preview (or Update Preview if the Preview button was recently used).
This is your development process for working with Aura components in stand-alone mode. Create a harness app for your preview window. Then build your feature or widget inside a component, which you add to the harness app. To see changes, reload the preview for the harness app. Much faster than reloading all of Lightning Experience for each change!
Here are a couple things to keep in mind.
This process isn’t as simple or automatic as with Visualforce. You have to create components yourself—there’s no “quick fix” link to create a stub version for you. And you need to manually reload the harness app—it won’t reload automatically.
Second, and more important, the stand-alone app (often called “my.app”) runs just the component framework and your component. It reloads faster because it doesn’t load Lightning Experience. But if your component depends on Lightning Experience services, such as providing the current record ID or handling navigation events, then it won’t work outside of Lightning Experience. (We talk about why in the Aura Components Core Concepts module.)
That’s a pretty big omission for most Lightning components developers. Most of the time, you’re building something that runs inside of, and integrates with, Lightning Experience (or the Salesforce app). So, let’s create a similar, if less lightweight test environment in Lightning Experience, which will let you access all of the services provided by that (very much larger) “harness” app.
The following steps create an “In Development” Lightning app that you can use to access Lightning components (and other things like Lightning and Visualforce pages) from within Lightning Experience while they’re still under development.
Create the “In Development” App
This step creates a Lightning app to hold your components while they’re under development.
- From Setup, enter Apps in the Quick Find box, then select
You should see the Lightning Experience App Manager.
- Click New Lightning App, and then create a custom app for your
components while they’re in development.
- App Name: In Development
- The Developer Name is automatically asssigned.
- Description: Components and pages under development.
- Click Next.
- Click Next again to accept the defaults for App Options.
- Click Next to accept the defaults for Utility Items.
- Click Next to accept the defaults for Navigation Items.
- For User Profiles, consider restricting your app to only System Administrators, or a profile you’ve created for developers in your organization. You don’t need your users to see your pages before they’re added to their permanent place in the user interface.
- Click Save & Finish to create the app.
Add the In Development App to the App Menu
This step adds your app to the navigation menu, so that it’s easy to get to.
- From Setup, enter App Menu in the Quick Find box, then select
You should see the App Menu page.
- Make sure your In Development app is set to Visible in App Launcher. While you’re at it, you might want to rearrange items, and even hide apps you don’t use.
Create a Lightning Component Tab
This step creates a new tab that displays a Lightning component, and adds it to the In Development app.
- From Setup, enter Tabs in the Quick Find box, then select
You should see the Custom Tabs page.
- Click New in the Lightning component tabs section, and then
create a custom tab for the page currently in development.
- Lightning Component: c:myFirstComponent
- Tab Label: My First Component
- Tab Name is automatically assigned.
- Choose a Tab Style you like.
- Description: A simple component.
- Make the tab visible only to your System Administrator profile.
- From Setup, enter Apps in the Quick Find box, then select App Manager.
- In the dropdown menu to the right of your In Development app, select Edit.
- In the Navigation Items panel, add the My First Component tab to the Selected Items list.
- Click Save.
- Click Back in the top right of the page to return to Setup.
To add more tabs to your app, you only have to repeat this last process.
Now you can view your component in Lightning Experience by clicking the App Launcher and selecting your In Development app. Once your app is available, the My First Component tab is the first item in the app’s tab bar. Whenever you make changes to your component, reload Lightning Experience using your browser’s Reload command.
Adding a component to a tab is one way you can integrate a Lightning component into Lightning Experience. It’s useful if your feature has a general context—that is, it’s not tied to a specific object type, like an account, or intended to be used with individual records.
You can create components that do do those things, but you’ll need to follow a different process to add them to the right place in Lightning Experience. For example, if your component needs to work with a specific account record, you could add it to the account page layout, or as a quick action on the account object.
If your component needs to be accessed elsewhere in Lightning Experience, see the Resources to find the appropriate steps to add it to the user interface, including code you’ll need to add to your component.
In the Aura Components Core Concepts module, we cover details about the Aura Components programming model and map concepts from Visualforce to similar features in Aura components. Before you head there, though, keep the following in mind.
Aura Components Is Newer than Visualforce
Visualforce has been around longer than the Aura Components programming model. That means we’re still developing it. Set your expectations appropriately, and look forward to the features we’re adding all the time.
Don’t Over-Spec a “Solution”
Start small when you develop your first few Aura components. You might be an expert Visualforce developer, but if you run too far ahead of your Aura components expertise, you’ll probably have to re-do some of your work.
Don’t Write Visualforce Code in Aura Components Form
The design and architecture for good Lightning components code looks nothing like most good Visualforce code. You can force a Visualforce design into an Aura component, but that’s smashing a square peg into a round hole. It’s harder, and you’ll eventually throw the work away. It’s better to put your effort into learning The Aura Components Way.
Remember the Alamo
We mean this a little differently than a Texan might. Some battles are unwinnable, and you’re better off surrendering. If you find yourself beating your head against the Aura components wall, it might be time to withdraw from the field, and re-marshall your forces.
Dedicate a day to working through the Aura Components Basics module or the Lightning Web Components Basics module. Learn the fundamentals of what is, after all, a very different framework from Visualforce. A strategic retreat with a plan to return when you’re better prepared is not a loss. It’s a path to victory.