Microsoft finally replaced the long-deprecated TSLint with ESLint in the SharePoint Framework (SPFx) v1.15 release of June 2022. This also involved revamping the default coding rules applied to all new SPFx projects. However, many of the rule configurations are quite opinionated and, in my view, oppressive.
This change has raised questions from many developers and students of my courses, including Michael K, one of my newsletter subscribers, who responded with some challenges he faced in one of his projects. In this article, I offer guidance on how to approach build-time errors triggered by ESLint. I also explain how to modify the rules in your project and selectively disable rules within specific parts of your project.
Let’s begin by understanding linters in SPFx projects.
Understanding linters in SPFx projects
The TypeScript compiler enforces certain rules, including noImplicitAny, noUnusedParameters, and noUnusedLocals. Linters were originally created to improve code quality and catch errors before compilers could perform many of the checks. Nowadays, they’re more commonly used to establish coding standards.
Linters work by applying rules to your project using a configuration file. Some rules support configurations, such as adjusting the settings for the rule or specifying whether it should be treated as an error or a warning.
If an enabled rule produces an error or finds a match in your code, ESLint will throw an error exit code. In the SharePoint Framework, the build toolchain first runs ESLint, followed by the TypeScript compiler. The compiler takes precedence over ESLint.
So, how should you handle ESLint rule warnings and errors?
How should you approach or handle ESLint rules?
First, identify whether you are seeing a linting warning or error, or if it is a TypeScript compiler error.
Linting findings look like this:
# this code...
# console.log(this.properties["aikey"]);
# ...triggers the ESLint rule "dot-notation":
Warning - lint - src/webparts/../HelloWorldWebPart.ts(56,21):
error dot-notation: ["app_name"] is better written in dot notation.
Notice the Warning - lint in the message text.
Where a compiler error is going to look like this.
# this code...
# private _isNotUsed: string = '';
# ...triggers this:
[10:56:21] Error - [tsc] src/webparts/../HelloWorldWebPart.ts(39,11):
error TS6133: '_isNotUsed' is declared but its value is never read.
Take note of the TSC mentioned in the message.
There is a difference between the two messages: the first one (dot-notation) is from ESLint while the second one (TS6133) is from the TypeScript compiler (also known as tsc).
To learn more about linting and compiler errors or warnings, simply search for them on Google. For the two examples mentioned above, you can learn more about the dot-notation rule on the TypeScript ESLint website and about TS6133 by searching on Google.
What if you don’t agree with a rule? What if you have your own standards for your organization? Well, you can customize the rules.
To configure the TypeScript compiler settings, use the included tsconfig.json file located in the root of the project.
But how do you configure ESLint?
Configure & control ESLint
Let’s examine the ESLint configuration and manage the various scopes in which it is found.
Customize ESLint for an entire project
All rule configurations for SharePoint Framework projects are defined in the .eslintrc.json file.
To configure the rules for an entire project, make changes to the .eslintrc.json file. This makes it easy for organizations to maintain specific coding standards across all their projects. By using a CI/CD process, you can ensure that every project follows the same standards.
As an example, the configuration for the dot-notation rule in the above text is:
"dot-notation": [ 1, { "allowPattern": "^_" } ]
The first item in the array refers to the
rule severity
. In this case, a severity level of 1 means the rule should be treated as a warning, while a level of 2 indicates an error, and a level of 0 disables the rule.
The second item in the array contains the configuration of the rule. In this case, the allowPattern is an optional regular expression string that permits the use of bracket notation for property names that match a specific pattern. In the given example, the warning could have been avoided if the property aikey had been prefixed with an underscore.
This approach works well for a project, but what if you need to selectively disable rules within your project?
Selectively disabling rules
Perhaps you want a rule to apply to your entire project, but there is one specific case within a file where you prefer the rule not to apply. This can be accomplished using special code comments.
To disable rules for a file within a project, add the following comment at the top of the file:
/* eslint-disable dot-notation */
You can disable a rule for an entire code block by using a special TypeScript comment to disable and re-enable the rule:
/* eslint-disable dot-notation */
console.log(this.properties['aikey']);
/* eslint-enable dot-notation */
And then, you can disable a rule using just a single comment before the line…
/* eslint-disable-next-line dot-notation */
console.log(this.properties['aikey']);
… or on the line you want to disable:
console.log(this.properties['aikey']); // eslint-disable-line dot-notation
So how should you approach linting rules & warnings?
Recommendations for linting warnings & rules
First of all, ☝️don’t panic and don’t treat rules as absolute. Just because you fail a rule doesn’t necessarily mean that you have to fix your code. Perhaps your code is fine as it is, and the rule is being too specific.
Or maybe the rule simply doesn’t work for your particular scenario. ☝️ You need to determine whether or not you’re doing the right thing. It’s also important to ☝️ distinguish between compiler errors and linting errors and warnings.
☝️ Remember: the default rule configurations are set up for a reason. Someone decided that they represent a generally accepted coding standard, or one that they believed was important.
☝️ Don’t treat Microsoft’s ESLint rule configuration as the ultimate authority. You have the final say, and you can define what’s acceptable for your project, team, or organization.
Take the time to develop your own personal, team, or organizational standards, and define them in your own .eslintrc.json files. Make sure that these standards are used for all of your projects going forward.