salesforce-lightning-cli

Salesforce Lightning CLI

The Salesforce Lightning CLI is a code review tool that lets you scan your code for Lightning-specific issues. This tool is extremely useful for preparing your Lightning code for the forthcoming LockerService addition to the Lightning Platform.

Lightning CLI is a linting tool based on the open source ESLint project. Like ESLint, it flags issues it finds in your code. Lightning CLI alerts you to specific issues related to LockerService. Issues that are flagged include incorrect Lightning components code, use of unsupported or private Lightning APIs, and a number of general JavaScript coding issues. Lightning CLI is bundled with the Salesforce CLI, installs into the Heroku Toolbelt, and is used on the command line.

Installation

Lightning CLI is bundled with the Salesforce CLI and sfdx force:lightning:lint is the prefered way to run the Lightning CLI.

Alternatively, the Lightning CLI can be installed in the Heroku Toolbelt. Make sure you have the heroku command installed correctly. More information about Heroku Toolbelt is available here:

https://devcenter.heroku.com/articles/getting-started-with-nodejs#set-up

After getting Heroku Toolbelt up and running, install the Lightning CLI plug-in using the following command:

heroku plugins:install salesforce-lightning-cli

Once installed, the plugin will be updated whenever you update the Heroku Toolbelt using the heroku update command. Do this every week or so to make sure you've got the latest Lightning CLI rules.

Usage

Lightning CLI is run just like any other lint command line tool. The only trick is invoking it through the sfdx command. Results are output to your shell window.

Normal Use

You can run the Lightning CLI linter on any folder that contains Lightning components:

sfdx force:lightning:lint ./path/to/lightning/components/

Note: The Lightning CLI runs only on local files. Download your component code to your machine using the Metadata API, or a tool such as the Force.com IDE, the Force.com Migration Tool, or any of a number of third-party options.

Filtering Files

Sometimes you just want to scan a particular kind of file. The --files argument allows you to set a pattern to match files against.

For example, the following command allows you to scan controllers only:

sfdx force:lightning:lint ./path/to/lightning/components/ --files **/*Controller.js

Include Warnings

By default only errors will be output from the Lightning CLI. The --verbose argument will also output any warning message during the linting process.

Custom "House Style" Rules

It's common that different organizations or projects will adopt different JavaScript rules. The Lightning CLI tool is here to help you get ready for LockerService, not enforce salesforce.com coding conventions. To that end, the Lightning CLI rules are divided into two sets, security rules and style rules. The security rules can't be modified, but you can modify or add to the style rules.

Use the --config argument to provide a custom rules configuration file. A custom rules configuration file allows you to define your own code style rules, which affect the style rules used by the Lightning CLI tool.

The Lightning CLI default style rules are defined in lib/code-style-rules.js inside this package. Make a copy of that file, and modify it to match your existing ESLint style rules. Alternatively, you can use your existing ESLint rule configuration file directly. For example:

sfdx force:lightning:lint ./path/to/lightning/components/ --config ~/.eslintrc

Note: Not all ESLint rules can be added or modified using --config. Only rules that we consider benign or neutral in the context of Lightning Platform are activated by Lightning CLI. And again, you can't override the security rules.

Results

When you run Lightning CLI on your Lightning components code, the tool outputs results for each file scanned.

error     secure-document    Invalid SecureDocument API
Line:109:29
        scrapping = document.innerHTML;
                             ^

warning   no-plusplus   Unary operator '++' used
Line:120:50
        for (var i = (index+1); i < sibs.length; i++) {
                                                 ^

error    secure-window  Invalid SecureWindow API
Line:33:21
        var req = new XMLHttpRequest();
                  ^

error  default-case  Expected a default case
Line:108:13
            switch (e.keyCode) {
            ^

Issues are displayed, one for each warning or error. Each issue includes the line number, severity, and a brief description of the issue. It also includes the rule name, which you can use to look up a more detailed description of the issue in the Lightning CLI documentation or ESLint documentation, as well as possible resolutions and options for further reading.

Your mission is to review each issue, examine the code in question, and to revise it to eliminate all of the genuine problems.

While no automated tool is perfect, we expect that most errors and warnings generated by Lightning CLI will point to genuine issues in your code, which you should plan to fix before using it with LockerService enabled.

Getting Help

Lightning CLI also provides some built-in help, which you can access at any time with the following commands:

sfdx force:lightning --help
sfdx force:lightning:lint --help

License

The Salesforce Developer MSA governs your use of the Lightning CLI.