Lint Lightning Web Components

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.

note: 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.

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:

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

Add ESLint Support for Lightning Web Security

1. On your development system, open a terminal window in your project directory.

2. Install the node project dependencies.

   $ npm install
   

3. Install ESLint 9 and the LWS configuration package from https://www.npmjs.com/package/@locker/eslint-config-locker.

   $ npm install --save-dev eslint @locker/eslint-config-locker
   

4. 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)

     const lockerConfig = require("@locker/eslint-config-locker");
     
     module.exports = [...lockerConfig];
     

   • ES Module format (eslint.config.mjs)

     import lockerConfig from "@locker/eslint-config-locker";
     export default [...lockerConfig];
     

     The default export configures the base rules, which report errors only.

5. 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)

     const lockerRecommended = require("@locker/eslint-config-locker/recommended");
     
     module.exports = [...lockerRecommended];
     

   • ES Module format (eslint.config.mjs)

     import lockerRecommended from "@locker/eslint-config-locker/recommended";
     export default [...lockerRecommended];
     

   tip: 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.

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)

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

• ES Module format (eslint.config.mjs)

  import lockerConfig from "@locker/eslint-config-locker";
  import lockerRecommended from "@locker/eslint-config-locker/recommended";
  export default [...lockerRecommended, ...lockerConfig];
  

  note: 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.

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

1. Install ESLint rules and configurations as described in the Add ESLint Support for Lightning Web Security section.

2. 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:

       # Lint Lightning Web Components
       $ npx eslint force-app/main/default/lwc
     
       # Or lint both LWC and Aura components
       $ 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.

     10:16  error  Document#fullscreen is prohibited in Lightning Web Security  @locker/locker/distorted-document-blocked-properties
     
     ✖ 1 problem (1 error, 0 warnings)
     
     The error Command failed with exit code 1.
     
     

     Resolve the errors and rerun the base rules against your project.