Lightning Web Components and Aura¶

Standards for building a Lightning component, whatever its languages. The JavaScript a component runs is held to the JavaScript standards, and the markup it renders to the HTML and Visualforce standards, Jest tests included (Testing). This page holds what is true of the component itself.

Lightning Web Components Before Aura¶

• Lightning Web Components is the default framework for custom UI. The Aura Components framework is used only where a Lightning web component cannot do the same thing.
• Lightning Web Components performs better and is easier to develop, and the feature gap between Aura and LWC is shrinking (Introducing Aura Components, Aura Development with Salesforce Extensions).
• Lightning Web Components must be used unless a feature that the component needs is supported only in Aura (How to Choose Lightning Web Components or Aura, Use Lightning Web Components instead of Aura Components).
• The Centre of Excellence (CoE) checks the choice between Lightning Web Components and Aura Components at design time, when it approves the design document.
• Aura components are held to these standards all the same. ESLint checks their JavaScript code (Version Control: ESLint), and PMD HTML rules check Aura components as well (Version Control: PMD).

Lightning Web Security¶

Lightning Web Security is the security architecture of Lightning components. It runs the components of each namespace in a JavaScript sandbox of their own, so that a component cannot read or change what belongs to the platform or to a component of another namespace, and it alters the APIs that would let one try: cookies, browser storage, and the globals of the page are partitioned by namespace, and HTML that a component inserts is sanitised (How Lightning Web Security Works). It replaces Lightning Locker, it is on by default in a new org, and it is on or off for the whole org: once a component relies on a feature that only Lightning Web Security offers, the org cannot go back to Lightning Locker (How Lightning Web Security Compares to Lightning Locker, Considerations Before Using LWS-Only Features). The org setting is a standard of the Settings page (Lightning Web Security). The standards below keep a component working under it, and come from Salesforce's own guidance on building components to work with Lightning Web Security.

Strict Mode¶

Lightning Web Security and Lightning Locker enforce JavaScript strict mode everywhere, whether or not the code says "use strict", so an unsafe action that a browser would let pass is an error at run time (JavaScript Strict Mode Enforcement).

• Every variable is declared, with const, let, or var. A variable that is used and never declared blocks the pull request (severity 2). Enforced by no-undef.
• Nothing is assigned to a global, and no top-level declaration becomes one. An assignment to a read-only global blocks the pull request (severity 2), and a top-level declaration that makes a global is reported at severity 3. Enforced by no-global-assign and no-implicit-globals.

Objects the Component Does Not Own¶

A change to an object that the component's namespace does not own is not propagated out of the sandbox, so the code that receives the object sees a property as undefined (Avoid Mutating Objects).

• A function does not add, remove, or change a property of an argument it receives, and a handler does not change the data of an event. Clone the object, change the clone, and pass or dispatch that. A property assigned to a parameter is reported at severity 3. Enforced by no-param-reassign.
• No property is added to a standard JavaScript object or to a DOM element. Data that belongs with an element goes in its dataset (Avoid Custom Properties on Standard JavaScript Objects). A property added to a built-in object blocks the pull request (severity 2). Enforced by no-extend-native.

The Globals top and location¶

Lightning Web Security gives a component top and location through the globals, and rewrites the code that reaches them, so a variable with one of those names makes the rewrite fail (Lightning Web Security Limitations).

• top and location are reached as window.top, window.location, document.location, globalThis.location, or self.location, and no variable shadows or overrides them: const loc = window.location.href, not const location = window.location.href. A variable, parameter, function, class, or import named top or location blocks the pull request (severity 2), and so does a variable that shadows a restricted name such as undefined. Enforced by no-restricted-syntax, with the selectors of the sample ESLint file, and no-shadow-restricted-names.

Aura Globals¶

• A Lightning web component uses no $A, Aura, Sfdc, or sforce. Lightning Web Security blocks them, because they are deprecated or not supported for Lightning web components (Salesforce Global Variables Blocked by LWS). A reference to any of them, or an import of an Aura library, blocks the pull request (severity 2). Enforced by @lwc/lwc-platform/no-aura for $A, no-undef for the other three, and @lwc/lwc-platform/no-aura-libs for an Aura library.

Downloads and Blobs¶

• A download link is made from a Blob, with URL.createObjectURL, and the object URL is revoked once the link has been used. A data: URI in a link is blocked by Lightning Web Security, because it embeds content in the URL with no origin to bind it to (Use Blob Objects for Download Links). No rule checks this. Reviewers do.
• A Blob is created with an explicit MIME type from the list that Lightning Web Security permits, such as text/plain, application/json, or application/octet-stream for any other binary file. Without a type the object is not created with the expected content, and a type outside the list is blocked (Specify a MIME Type for Blob Objects). No rule checks this. Reviewers do.

Input and Inserted HTML¶

Lightning Web Security sanitises the HTML and SVG that a component inserts into the page, and never its input (Lightning Web Security Sanitization).

• A component validates its own input, before it is used and before it is sent to Apex.
• No HTML is set from a string: no innerHTML, outerHTML, or insertAdjacentHTML. The template renders the markup, and lwc:dom="manual" with a sanitised string is the exception a reviewer approves. HTML set from a string blocks the pull request (severity 2). Enforced by @lwc/lwc/no-inner-html.

Scripts and Resources¶

The Content Security Policy of the platform allows a script only from the org, and every other external resource only over HTTPS from the org or from a trusted URL, with no inline script and no inline event handler (Content Security Policy Overview).

• A JavaScript library is uploaded to the org as a static resource and loaded from there. A font, an image, a frame, or a stylesheet from outside the org is loaded over HTTPS from a trusted URL. No script tag and no inline event handler is written in markup. The policy enforces this in the browser. In Aura markup, an event attribute that holds a script, such as onclick="alert('x')", in place of a controller action such as {!c.handleClick}, is reported at severity 3. Enforced by NoInlineEventHandlerAura. A javascript: value is reported by AvoidJavaScriptUrlHtmlLwcAura instead, and a reviewer checks a script tag. For a Visualforce page the same standard is on the HTML and Visualforce page (External Scripts and Stylesheets).

Lightning Web Components¶

Readability¶

Code Style¶

• No trailing comma after the last item of an object literal or an array literal. Prettier removes it (trailingComma is none in the Prettier configuration of these standards), so that every component reads alike. One that remains blocks the pull request (severity 2); enforced by the PMD JavaScript rule AvoidTrailingComma.

Formatting¶

Required Formatting¶

Error Prevention¶

• An event is dispatched with bubbles: false and composed: false, the defaults, and never with both set to true. An event with both set to true crosses every shadow boundary, so it becomes part of the API of every component above it (Events Best Practices).

• An event with both set to true blocks the pull request (severity 2); enforced by AvoidLwcBubblesComposedTrue and no-restricted-syntax, with a selector of the sample ESLint file. Keep both rules: AvoidLwcBubblesComposedTrue also finds options kept in a variable, and the no-restricted-syntax selector also finds an event that is the first statement of a method.

• A component that Lightning Out 2.0 runs needs both, and, after approval, gets a suppression with a documented reason (Handle Lightning Out 2.0 App Events).

Accessibility¶

Salesforce's guidance for accessible Lightning web components is in the Lightning Web Components Developer Guide. It advises following WCAG, and using a base component where one fits, because base components have accessibility built in (Component Accessibility). It advises a label on every control, and aria-label only where no label shows or where a screen reader needs more text than the label gives (Accessibility Attributes). Its base components give images and icons an alternative-text attribute for WCAG 1.1.1 (Base Components Accessibility). The standards for alternative text and for the names of buttons and links are on the General: Accessibility page. The standards for tables, form groups, frames, lists, and media in the markup of a component are on the HTML and Visualforce: Accessibility page. A template tag may sit between a list and its items, and an li at the root of a component's template is not reported, because its list is in the parent component.

Aura¶

• Every Aura component is at API version 40.0 or later. Below 40.0 an Aura component runs with Lightning Locker off, outside the security architecture of the org (AvoidAuraWithLockerDisabled). The API version standard already asks for far more than 40.0; this rule is kept for what the lower number means, and blocks the pull request (severity 1). Enforced by AvoidAuraWithLockerDisabled.
• An Aura application should not be a Lightning Out dependency app, which extends ltng:outApp or ltng:outAppUnstyled. Such an app is Lightning Out (beta), which requires Lightning Locker; Lightning Out 2.0 is recommended for a component in an external app (How Lightning Out 2.0 Compares to Lightning Out (Beta), Lightning Web Security). A Lightning Out dependency app is reported and does not block (severity 3), and an organisation may allow one with a suppression and a documented reason. Enforced by NoLightningOutApplicationAura.

Readability¶

Code Style¶

Formatting¶

Required Formatting¶

• No trailing comma after the last item of an object literal or an array literal in an Aura component: Salesforce requires it (Prettier Code Formatter). One that remains blocks the pull request (severity 2); enforced by the PMD JavaScript rule AvoidTrailingComma.

Error Prevention¶

Accessibility¶

Salesforce's guidance for accessible Aura components starts at Supporting Accessibility. It advises keeping the code that makes a component accessible, such as its aria attributes, when the component is changed, and following WCAG. Its pages cover the accessibility of the base components (Accessibility for Lightning Base Components), informational and decorative images and icons (Using Images and Icons), button labels (Button Labels), and tests that check a rendered component for common faults, such as an image with no alt attribute (Write Aura Component Accessibility Tests). The standards for alternative text and for the names of buttons and links are on the General: Accessibility page. The standards for tables, form groups, frames, lists, and media in the markup of a component are on the HTML and Visualforce: Accessibility page. An aura:iteration or aura:if tag may sit between a list and its items, and an li at the root of an aura:component is not reported, because its list is in the parent component. In an aura:application, an li with no list above it is reported.

An Organisation Without Aura¶

These standards recommend Lightning Web Components over Aura (Lightning Web Components Before Aura). A project that may still get an Aura component keeps every Aura item, so that the first Aura component is checked from its first commit (Version Control: ESLint). An organisation that has moved off Aura, and forbids new Aura components, may:

• Leave out the @salesforce/eslint-plugin-aura package, and the Aura blocks of eslint.config.js.
• Remove the second PMD run that reads Aura markup, which an organisation needs only if it runs PMD without Code Analyzer (Appendix F.2: Aura Markup and PMD Alone).

An organisation forbids Aura by making the Aura component bundle a Tier 0 type, in every Tier 0 layer (Tier 0 Enforcement). An Aura file is then blocked, not just skipped.

• **/aura/ in .forceignore and in .gitignore, so that the Salesforce CLI never deploys or retrieves an Aura bundle, and Git does not stage one.
• '**/aura/**' in the tier0 list of metadata-risk-tiers.yml and in the Tier 0 push ruleset, so that a push or a pull request with an Aura file is rejected.
• AuraDefinitionBundle in the metadataTypes property of ProhibitedMetadataType.

In an organisation that forbids Aura, no Aura bundles are committed. The metadata file of an Aura bundle blocks the pull request (severity 1). Enforced by ProhibitedMetadataType.

Comments¶

The General: Comments standards apply to Lightning web components and Aura components. Each part of a component is read with the files of its kind:

• A Lightning Web Component template and Aura markup are read as markup (HTML and Visualforce: Comments).
• The JavaScript of a Lightning web component or an Aura component is read as JavaScript (JavaScript: Comments).

Rules¶

The rules that this page mentions. The Standard column gives each rule's standard in one line, and the Section column links to the section that mentions the rule; "Not yet written" marks a rule of this page that no section mentions yet. Appendix F.6 holds the full cross-reference.