There are many tools for ensuring a constant level of code quality is maintained on a project. Different tools do different things in different ways. This handbook covers some of those tools.
If you have already read this section of the Handbook and are here just for the config files, jump ahead (+ editor files).
Git hooks
Git hooks allow us to run scripts during various git
commands. This verification step can be used to run various tools which ensure that the code satisfies some conditions before it is added to the repository. If the verification fails, the git command will abort.
No matter which code quality tools we use, git hooks are a great way to run those tools. There are multiple ways to add git hooks. For JavaScript projects, we recommend using husky. Husky scripts are configured in package.json
. Here is a basic example which runs test
before any code is pushed to the repository:
// package.json
{
"husky": {
"hooks": {
"pre-push": "npm test"
}
}
}
In this example, if you try pushing and the tests fail, code will not get pushed to the remote. We do not necessarily recommend running tests on push, it is just an example (there are better ways to run automated tests using a proper CI/CD set-up).
Most of our code quality tools are run on either pre-commit
or pre-push
hooks, so using git hooks is kind of a prerequisite for the rest of the Code quality handbook section.
Lint-staged
Lint-staged works hand-in-hand with commit hooks - pre-commit hook in particular. It allows us to run scripts only on those files which were staged for committing. This makes hooks run faster since they only need to run on a subset of project files instead of all of them. The assumption is that code quality tools have to be run only on modified code while the code that was untouched should already have been checked.
Similarly to husky
, lint-staged
is also configured in package.json
. It uses glob
patterns which allow you to run different scripts on different file types/patterns.
Here is an example which runs eslint
and prettier
on all staged .js
and .ts
files, and stylelint
on all staged .scss
files via a pre-commit hook:
// package.json
{
"husky": {
"hooks": {
"pre-commit": "lint-staged"
}
},
"lint-staged": {
"**/*.{js,ts}": [
"eslint",
"prettier --write"
]
"**/*.scss": [
"stylelint --syntax=scss"
]
}
}
What lint-staged
does is it matches files to glob
patterns and passes the list of files as an argument to scripts. Tooling developers should ensure that their scripts can receive the list of files in the correct format. Most common tools like eslint, tslint, stylelint and others are compatible with the way lint-staged
passes the list of files.
It is important to note that lint-staged
matches files to glob
patterns in parallel and runs tasks on those matched groups in parallel as well. Within one matched group, the commands are executed in-order. There is an option to force lint-staged
to process groups sequentially if you need to. In the above example .scss
files will be processed in parallel with .js
and .ts
files. For .js
and .ts
files eslint
will be executed first and only after it is done will prettier
be executed.
Check the following chapters for specifics about Prettier, ESLint and Stylelint.
Automatic code formatting with Prettier and IDE settings
Source: XKCD
Many people are very passionate about the way they format their code. While we appreciate everyone's opinion, we believe it is best to leave this bikeshedding to automated tooling. It might not format the code in a way that is satisfying to everyone, but it will be consistent across projects and, more importantly, it will format the code written by different people in the same way. This also eliminates discussions around formatting.
Prettier is one of the most popular tools for this job. It is very opinionated and not very configurable. It might not be perfect, but it is a good way to ensure consistency when it comes to formatting and it format multiple different file types.
Here is our recommended Prettier configuration:
// .prettierrc.json
{
"$schema": "http://json.schemastore.org/prettierrc",
"printWidth": 120,
"endOfLine": "lf",
"useTabs": true,
"arrowParens": "always",
"quoteProps": "as-needed",
"bracketSpacing": true,
"singleQuote": true,
"semi": true,
"trailingComma": "es5",
}
If you are using Angular, make sure to add an override for templates parser:
// addendum to the above .prettierrc.json
{
...
"overrides": [{
"files": "*.component.html",
"options": {
"parser": "angular"
}
}]
}
If you just added Prettier to an existing codebase, you should probably run it once and let it format the whole codebase. This will probably create a lot of modifications which you can skim through and if it checks out you can commit the changes.
It is possible that some things might break after Prettier is run. In particular, we noticed some issues with the way Prettier formats SCSS, so you might want to exclude SCSS from Prettier in case you notice issues:
# .prettierignore
# It sometimes breaks SCSS (https://github.com/prettier/prettier/issues/6092)
*.scss
If you do not notice issues with Prettier and SCSS, we recommend keeping Prettier on for SCSS files as well.
Developers should set up their code editors to run Prettier whenever they save a file. This is not a bullet-proof solution because some editors might not have support for this (either natively or via plug-ins). Going one step further, we recommend running Prettier via the pre-commit hook. This ensures that the committed code is formatted even if the developer who wrote it did not have his editor set up to format on file save.
// package.json
{
"husky": {
"hooks": {
"pre-commit": "prettier --write"
}
}
}
To ensure editor settings are in-line with prettier settings, create a workspace .vscode
settings and .editorconfig
files:
// .vscode/settings.json
{
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.formatOnSave": true,
"editor.insertSpaces": false,
"editor.detectIndentation": true
"[scss]": {
"editor.formatOnSave": false
}
}
# .editorconfig
root = true
[*]
charset = utf-8
indent_style = tab
indent_size = 2 # GitHub uses this value for indentation size when showing code on the Web
insert_final_newline = true
trim_trailing_whitespace = true
ESLint and TSLint
Even though TSLint is deprecated, it is still used on some projects for legacy reasons. The main reason being that some custom rules packages have not yet migrated to ESLint. If your project does not use custom TSLint rules or you do not use TS, use ESLint.
Infinum created various rulesets for ESLint and TSLint which you can check out here. We encourage you to use some of these presets, as per your needs:
Stylelint
If you have no issues with prettier SCSS formatting and you decide to use Prettier, it is recommended to install stylelint-prettier plugin and preset.
Putting it all together
Here is the complete example which runs TypeScript compilation check on all files, prettier, tslint and stylelint on an Angular (v10) project:
// package.json
{
"scripts": {
"lint:ng": "ng lint",
"tsc": "concurrently \"npm run tsc:app\" \"npm run tsc:spec\"",
"tsc:app": "tsc --noEmit -p ./src/tsconfig.app.json",
"tsc:spec": "tsc --noEmit -p ./src/tsconfig.spec.json"
},
"husky": {
"hooks": {
"pre-commit": "npm run tsc && lint-staged"
}
},
"lint-staged": {
"**/*.{json,md,html}": [
"prettier --write"
],
"**/*.ts": [
"prettier --write",
"ng-lint-staged lint:ng --tsConfig=./tsconfig.base.json --"
],
"**/*.scss": [
"stylelint --syntax=scss"
"prettier --write" // add or remove this line depending on whether you run stylelint on SCSS
]
}
}
// tslint.json
{
"extends": ["@infinumjs/tslint-config-angular", "tslint-config-prettier"],
"rules": {
// remember to replace `app` with your selector
"directive-selector": [true, "attribute", "app", "camelCase"],
"component-selector": [true, "element", "app", "kebab-case"]
}
}
// .stylelintrc.json
{
"plugins": ["stylelint-prettier"],
"rules": {
"prettier/prettier": true
}
}
For this example, you will have to install the following devDependencies
:
npm i -D concurrently husky lint-staged ng-lint-staged stylelint stylelint-prettier prettier tslint-config-prettier @infinumjs/tslint-config-angular
Some notes:
- it is important to run
tsc
on all files because changes in staged files can affect compilation of unmodified files tsc
is run on both the applicationtsconfig
files and teststsconfig
filesconcurrently
speeds up things by runningtsc
checks in parallelprettier --write
is run separately for.ts
and other files in order to prevent any possible race conditions before running TSLint (vialint:ng
) and Prettierng-lint-staged
is required becauseng lint
does not accept the list of files as provided bylint-staged
, so some transformations are necessary