Install ESLint Rules for Lightning Web Security

ESLint rules help you develop code that works with Lightning Web Security (LWS). You can install them on your development machine and run them on your source code.

The ESLint rules are available as an npm package that you install locally, and use in an IDE command line.

The ESLint rules are documented in this GitHub Repository.

The new architecture was developed under the Locker name before the brand change to Lightning Web Security. You can see locker used in code and in the npm package names. However, the lint rules support Lightning Web Security, not the current Lightning Locker.

Note

The LWS ESLint rules require ESLint 9 or later and use ESLint’s flat configuration format (an eslint.config.js file in your project root). The legacy .eslintrc configuration format is no longer supported.

If you previously configured LWS ESLint rules using .eslintrc:

Delete your .eslintrc or .eslintrc.json file.
Remove ESLINT_USE_FLAT_CONFIG=false from your environment, if set.
Create a new eslint.config.js file as shown in the examples.

Add ESLint Support for Lightning Web Security

On your development system, open a terminal window in your project directory.
Install the node project dependencies.
1$ npm install
Install ESLint 9 and the LWS configuration package from https://www.npmjs.com/package/@locker/eslint-config-locker.
1$ npm install --save-dev eslint @locker/eslint-config-locker
Create an ESLint flat configuration file at the root of your project. These files can be CommonJS (eslint.config.js) or ES modules (eslint.config.mjs) format as shown in these examples.
- Common JS format (eslint.config.js)
  1const lockerConfig = require("@locker/eslint-config-locker"); 2 3module.exports = [...lockerConfig];
- ES Module format (eslint.config.mjs)
  1import lockerConfig from "@locker/eslint-config-locker"; 2export default [...lockerConfig];
  The default export configures the base rules, which report errors only.
If you want notification of warnings in addition to errors, use the recommended configuration instead of the default. The ESLint warnings can be helpful for debugging specific issues, but generate extra information that isn’t necessary for everyday use.
- Common JS format (eslint.config.js)
  1const lockerRecommended = require("@locker/eslint-config-locker/recommended"); 2 3module.exports = [...lockerRecommended];
- ES Module format (eslint.config.mjs)
  1import lockerRecommended from "@locker/eslint-config-locker/recommended"; 2export default [...lockerRecommended];
To focus only on warnings and errors related to LWS, spread only @locker/eslint-config-locker/recommended and omit other lint configurations. The Lightning Web Component (LWC) rules in @salesforce/eslint-config-lwc/recommended can generate extraneous output and make it hard to see violations that are specific to LWS.
Tip

If you also lint your components with @salesforce/eslint-config-lwc, note that version 4.0.0 and later supports flat-configuration only and requires eslint@9 (use @salesforce/eslint-config-lwc@3.x for earlier versions of ESLint). Combine both recommended and @salesforce/eslint-config-lwc as flat-configuration arrays as shown here.

Common JS format (eslint.config.js)

1const lwc = require("@salesforce/eslint-config-lwc");
2const lockerRecommended = require("@locker/eslint-config-locker/recommended");
3
4module.exports = [...lwc.configs.recommended, ...lockerRecommended];

ES Module format (eslint.config.mjs)
1import lockerConfig from "@locker/eslint-config-locker"; 2import lockerRecommended from "@locker/eslint-config-locker/recommended"; 3export default [...lockerRecommended, ...lockerConfig];
When your org upgrades to a new Salesforce release, run npm update so your ESLint rules match the LWS distortions in the release. For a list of distortions added in a release, see the Salesforce Release Notes.
Note

Use ESLint Rules in VS Code

Use Visual Studio Code (VS Code) with the Salesforce Extensions for VS Code to develop Lightning components. The ESLint rules for errors against Lightning Web Security are displayed in VS Code where your code violates them. The rules map to distortions that affect your code. The popup for a rule violation includes a link to documentation for the rule.

Run Base Rules Against Your Project

Install ESLint rules and configurations as described in the Add ESLint Support for Lightning Web Security section.
Run your usual command for linting your code.
- For a Salesforce DX project, run your configured lint script, such as npm run lint or yarn lint.
- If you’re not using a Salesforce DX project, you can run the eslint command on your LWC and Aura components. ESLint 9 automatically discovers the eslint.config.js file in your project root, so no configuration flags are required. For example, if your components are in the standard Salesforce DX path, run this command:
  1# Lint Lightning Web Components 2 $ npx eslint force-app/main/default/lwc 3 4 # Or lint both LWC and Aura components 5 $ npx eslint force-app/main/default/lwc force-app/main/default/aura
  The output returns violations found on your components.
  
  Here’s an example of an LWS error message in some sample CLI output.
  110:16 error Document#fullscreen is prohibited in Lightning Web Security @locker/locker/distorted-document-blocked-properties 2 3✖ 1 problem (1 error, 0 warnings) 4 5The error Command failed with exit code 1.
  Resolve the errors and rerun the base rules against your project.

Release Preview

This release is in preview. Features described here don't become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, we can't guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.