Writing JavaScript better and faster using TypeScript TypeChecker, ESLint, JSDoc and Prettier
Here I take you through how to implement the TypeScript TypeChecker, together with ESLint, JSDoc and Prettier to enhance your JavaScript coding environment.
This is the implementation part, I will write why you want to do this and described each component in more detail. For each component we will learn how to install and configure it and I’ll give some tips on using it.
These instructions are for VS Code, but you should be able to implement the same on most popular code editors.
If you’re writing any web code (front- or back-end), then it’s likely that you will be using npm and have a package.json. These instructions assume this is the case.
TL;DR
Below I describe the how to get there, but if you’re impatient can view these settings at this repo: https://github.com/psiphi75/my-js-dev-env
TypeScript
Installation and Configuration
The beauty about using the IntelliSense on VS Code is that it just works out-of-the-box. It’s probably what has helped make VS Code so popular for JavaScript developers.
However, you can still customise it by putting a jsconfig.json
file in the root directory of your project. See here for documentation.
Required VS Code Plugins
None.
Tip #1: Suppressing warnings
TypeScript will sometimes highlight issues that are actually okay, you can suppress these using // @ts-ingore
. Like this:
if (false) {
// @ts-ignore: Unreachable code error
console.log("hello");
}
Note, it’s not possible to ignore specific warnings, you just turn off the warning for the next line.
ESLint
Installation and Configuration
First we need to install the ESLint packages. I use the AirBnB JavaScript style, but only the base package (which excludes React).
npm install --save-dev eslint
npm install --save-dev eslint-config-airbnb-base
npm install --save-dev eslint-plugin-import
npm install --save-dev eslint-plugin-jsdoc
npm install --save-dev eslint-plugin-prettier
The .eslintrc
file contains the following:
Required VS Code Plugins
ESLint works very well.
Tip #1: Suppressing warnings
ESLint is highly configurable and it’s code support is excellent. You can disable warnings by line, next-line, block or file.
Disable a line
alert('hello'); // eslint-disable-line
Disable a line with a specific warning, e.g. the no-alert
warning.
alert('hello'); // eslint-disable-line no-alert
Disable a file or block. Everything from /* eslint-disable */
on-wards is disabled, so you can use it for a block or a whole file.
/* eslint-disable */alert('hello');/* eslint-enable */
Tip #2: Auto-fixing problems
ESLint can auto-fix some issues that are safe to do-so. This can be useful in cases when introducing ESLint to a new project, or when you copy-n-paste your application from Stack Overflow.
In VS Code press [CTRL]+[SHIFT]+P
(in Linux) to bring up the command palette, then type eslint fix
and you will see the “ESLint: Fix all auto-fixable problems” option. You may need to run this command a few times before all auto-fixable issues disappear.
JSDoc
Installation and Configuration
JSDoc actually requires no configuration for it to work with TypeScript. However, if you want to work with ESLint it requires a little configuration. This will run ESLint across your JSDoc.
This configuration was done above by installing the JSDoc plugin for ESLint eslint-plugin-jsdoc
.
Required VS Code Plugins
Optional: Document This is the most popular VS Code plug-in for JSDoc, but has some issues and sometimes fails to create a JSDoc comment block.
Because JSDoc is contained in your comments, it uses a special syntax for creating the documentation, when you start typing /**[ENTER]
then a JSDoc comment section is created.
Tip #1: Creating source documentation
You can use jsdoc
to create documentation for your project. Install jsdoc using npm install --save-dev jsdoc
, then run it using ./node_modules/.bin/jsdoc yourJavaScriptFile.js
. This will create an out/
folder that contains an index.html
file that you can open in your browser and describes your project.
Prettier
Installation and Configuration
Prettier is opinionated and has minimal configuration, which is a good thing.
To install it run the following:
npm install --save-dev prettier
Configuration is found in the .prettierrc
file:
The ESLint plugin (eslint-plugin-prettier
) was installed above.
Required VS Code Plugins
Prettier-vscode by Esben Petersen works well with Prettier.
Tip #1: Migrate an existing code-base
If you start using Prettier on an existing code base, you can run it recursively.
But you should be aware of the changes it will make in your repository. Because there will be a huge set of changes, I suggest using Prettier at the begging of a big code change. Commit all your changes first, run Prettier across your project, then make a new commit which only has the Prettier changes. Your blame history will have a blip from when you ran Prettier.
To run prettier for all .js
files use the following command
./node_modules/prettier/bin-prettier.js --write "{*.js,!(node_modules)**/*.js}"
This excludes node_modules
. You may also run the same command but with .json
files included too.
Conclusion
Implementing the above will make your VS Code editor a true IDE. It will enable to use the powerful editor features, like refactoring, reference lookups, etc. It will also indicate potential issues as you are writing your JavaScript. Like all new toys, it will take some effort to learn how to work with environment and make the most of it, but it’s worth it!