As part of Salesforce’s Spring ‘19 release, we were introduced to Lightning Web Components (LWC). Lightning Web Components is a new programming model developers can use to build Lightning components on the Salesforce Platform. Lightning Web Components has a modern and fast tech stack, which boosts developer productivity when building components. Lightning Web Components can integrate with Lightning Data Service and Salesforce APIs with very minimal boilerplate code. Even better, you can start using Lightning Web Components in Lightning Communities today!
You can have both custom Aura components and custom Lightning Web Components within the same Lightning community. Additionally, Lightning Web Components respect the Content Security Policy set by the community. For more info around CSP in Communities, check out this blog.
You are probably asking yourself why you or your business should start using Lightning Web Components? Lightning Web Components was built with two main goals in mind:
These are huge wins for both businesses and developers. With the improved performance of Lightning Web Components and the increased developer productivity, it means quicker deployment of new features and happier customers.
Let’s dive into the advantages of Lightning Web Components:
For a high-level overview of how Lightning Web Components was built, check out this blog.
In this section, we will go over how to create a simple button with Lightning Web Components that displays text coming from what the admin inputs in the Community Builder Property Editor. Thus, the final result will have a button in your Community with configurable text via the Community Builder Property Editor.
Tip: We recommend using Visual Studio Code with the Salesforce DX Visual Studio Code extension. However, the steps below will be editor agnostic (sfdx commands in the terminal).
Follow the first module outlined in Quick Start: Lightning Web Components
If you want to use an existing project such as your own project or a sample, you can skip this step. Otherwise, input these commands into your terminal:
If your org is on a My Domain subdomain, modify the sfdcLoginUrl in sfdx-project.json to your My Domain login URL before authorizing your org. For more details, check out the Salesforce DX Developer Guide.
Enter your org credentials in the opened browser window. After logging in, click “Allow”.
-a sample_project specifies the alias to your scratch org. Feel free to put your own alias.
app_dir is probably force-app, unless you changed the name.
A directory called myLightningWebComponent will be created in the lwc folder. Inside the directory, there will be three files: JavaScript, HTML, and XML.
The button will have configurable text from the Community Builder Property Editor and log a message when clicked on.
Open the JavaScript file (myLightningWebComponent.js). You should see a class called MyLightningComponent. It extends LightningElement. This will let the Lightning Web Components framework know that this class is a Lightning web component.
We want to display the button text dynamically based on input from the Community Builder Property Editor. At the component level, we will need a property to bind to the HTML, so that every time the property changes, the HTML is updated.
Create a property called buttonText in the class to control text of the button.
export default class MyLightningWebComponent extends LightningElement { buttonText; }
Import api from the lwc module and add @api in front of the property. This makes the property to be settable from the outside, such as a parent component or in our case the Community Builder Property Editor.
import { LightningElement, api } from 'lwc'; export default class MyLightningWebComponent extends LightningElement { @api buttonText; }
For more documentation on @api, check out Public Properties in the Salesforce Developer Guide.
Add a click handler in the class for when the button gets clicked on.
handleClick() { console.log("Button Clicked!"); }
Your final JavaScript file should look similar to this:
import { LightningElement, api } from 'lwc'; export default class MyLightningWebComponent extends LightningElement { @api buttonText; handleClick() { console.log("Button Clicked!"); } }
Then open the HTML file (myLightningWebComponent.html). We want to display a button with text rendered from the property in our JavaScript file. We also want to bind the click event of the button to our custom handler. To do both of these, we can use curly braces.
<template> <button onclick={handleClick}>{buttonText}</button> </template>
To do this, we’ll create a new .css file in the same directory as your component with the same name as the other files.
Open the file and add some CSS properties to the component:
button { color: black; background-color: aqua; text-align: center; border: none; font-size: 14px; border-radius: 10px; padding: 5px 50px 5px 50px; }
Notice how simple our CSS selector is. With the benefit of the Shadow DOM, we don’t need obscure, complicated CSS selectors because we know that this CSS will be self-contained in this component.
If you want to use CSS variables from Aura design tokens or Communities standard design tokens, use the syntax laid out in the Salesforce Developer Guide.
Open your <component>.js-meta.xml file, (ex. myLightningWebComponent.js-meta.xml) and
set isExposed to true. This will expose the component in all orgs and in Lightning App Builder and Community Builder.
Add the targets field in the LightningComponentBundle root with lightningCommunity__Page as a target.
<targets> <target>lightningCommunity__Page</target> </targets>
Targets define what type of page you want your component to be added to. lightningCommunity__Page allows the component to be shown on a Community Page. Without this tag, your component would not appear in the Community Builder. For all supported tags, look at Configuration File Tags in the Salesforce Developer Guide.
Specify what properties the Community Builder can set. First, add another target called lightningCommunity__Default in .js-meta.xml file.
Below the targets, add the following:
<targetConfigs> <targetConfig targets="lightningCommunity__Default"> <property name="buttonText" type="String" default="defaultText" /> </targetConfig> </targetConfigs>
Inside targetConfig, we can configure what the Community Builder Property Editor can set in the component. For our component, you’ll notice we added the text of the button to be set by the Community Builder Property Editor.
Note: The property name must match the name of the @api property in the JavaScript file. For specifications of property fields, see the Configuration File Tags in the Salesforce Developer Guide.
Add a masterLabel, if you want to have a specified name for your component in the Community Builder.
Your final .js-meta.xml file should look similar to this:
<?xml version="1.0" encoding="UTF-8"?> <LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata" fqn="myLightningWebComponent"> <apiVersion>45.0</apiVersion> <isExposed>true</isExposed> <masterLabel>My Lightning Web Component</masterLabel> <targets> <target>lightningCommunity__Page</target> <target>lightningCommunity__Default</target> </targets> <targetConfigs> <targetConfig targets="lightningCommunity__Default"> <property name="buttonText" type="String" default="defaultText" /> </targetConfig> </targetConfigs> <LightningComponentBundle>
If you want an icon other than the default to appear next to your component in the Community Builder component palette, add your own SVG file titled the same name as the other files (ex. myLightningWebComponent.svg).
If you are new to Communities, check out this help article or this Trailhead module to learn how to create a community in Salesforce.
Lightning Web Components can coexist on a page in Communities with an Aura component. You can also create an Aura component that includes Lightning Web Components. However, you can not create a Lightning web component that includes Aura Components. Check out the Salesforce Developer Guide if you want to know how to add a Lightning web component inside an Aura component.
To communicate between parent and child Lightning Web Components, use custom events that are built from standard DOM Events supported in each browser. If you need to communicate between components that aren’t in the same component hierarchy, you can use a publish-subscribe module.
To fire standard Aura events from Lightning Web Components, such as for page navigation, please consult the table listed in section Migrate Standard Aura Events.
To help kick-start your development with Lightning Web Components, you can check out the samples on the Trailhead Sample Gallery. I have also built a Community-specific sample featuring examples of Lightning Web Components in Communities. Some important callouts in the components in the sample:
For all Lightning Web Components specific documentation, head over to the Salesforce Developer Guide (Which is likely already in your bookmarks by now). For more practice and guided steps, check out all the Lightning Web Components modules on Trailhead.
Lightning Web Components is a revolutionary programming model for Salesforce. Let the innovation begin 🌟. Thanks for reading this blog and feel free to ask any questions you have in the comments here!
Kenan Mesic is a full stack Software Engineer on Community Cloud at Salesforce. He is a JavaScript guru and has experience in multiple JavaScript frameworks. Feel free to connect with him on Twitter at @dev__ken.
Haris Ikram is a Senior Director of Product Management on Community Cloud.
Ronak Shah is an Engineering Manager on Community Cloud.