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

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

2. Install the node project dependencies.

3. Install ESLint 9 and the LWS configuration package from https://www.npmjs.com/package/@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)

   • ES Module format (eslint.config.mjs)

     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)

   • ES Module format (eslint.config.mjs)

   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)

• ES Module format (eslint.config.mjs)

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

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:

     The output returns violations found on your components.

     Here’s an example of an LWS error message in some sample CLI output.

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