eslint-config-stack

A shared eslint config for the GP Stack.

The naming of this package follows the eslint rules rather than the Stack's own package naming conventions. This is to ensure that things work as expected when extending this shared config.

Setting up the shared config linting

This section describes how to change a project or a stack pack that currently uses liting provided via @gp-technical/stack-pack-standard@2 to use the shared config linting.

Upgrading projects

All steps apply to both the api and app directories:

1. yarn remove @gp-technical/stack-pack-standard
2. now follow the common steps outlined below.

Upgrading stack packs

1. yarn upgrade @gp-technical/stack-pack-standard --latest
2. change the 2 build scripts to run the linting before the build.

"build:debug": "yarn lint && sp-build-debug",
"build": "yarn lint && sp-build"

3. now follow the common steps outlined below.

Steps common to both projects and stack packs

1. yarn add @gp-technical/eslint-config-stack --dev
2. Copy the following files from this project: .eslintignore, .huskyrc.js, lint-staged.config.js. The snippet below might be useful assuming the path to this project is correct.

  cp ../../stack-pack/eslint-config-stack/{.eslintignore,.huskyrc.js,lint-staged.config.js} .

3. create a .eslintrc.js with the following contents (on *nix-like command interpreters you should be able to simply copy and paste the snippet below):

cat << END > .eslintrc.js
module.exports = {
  extends: '@gp-technical/eslint-config-stack'
}
END

4. within package.json change the lint script to:

  "lint": "eslint --ext .js,.jsx .",

5. within package.json remove the line:

  "precommit": "sp-lint-staged",

6. within package.json remove the line:

  "standard-engine": "@gp-technical/stack-pack-standard",

7. rm save-commands.json (if this exists)
8. done

If the above steps have worked, when you commit you should see the pre-commit hooks activating and messages appearing on the terminal that indicate that the linters are running against the files in the commit. This should prevent you from committing any files that contain lint errors.

If you find that even after going through the process above you can still commit files that contain lint errors try removing and re-installing the packages. On *nix:

rm -rf node_modules && yarn

If you are still able to commit a file that contains lint errors please ask for help.

Files in detail

Each project should have a .eslintrc.js that extends the one provided here. This should look exactly like:

module.exports = {
  extends: '@gp-technical/eslint-config-stack'
}

You need one of these in each directory that contain a package.json file so for an application that will mean one in each of the api and app directories. The same goes for the other config files detailed below.

Other formats for the eslint config are possible but the advantage of using JavaScript is that the config file itself can then be linted.

The linting config includes prettier as a linter so there is no need to run prettier separately on JavaScript files and running eslint with the --fix option will fix prettier issues as well as other fixable linting issues.

Now that the eslint config is within a project its simpler to just add the linting directly within the project rather than providing that via another package as was done previously.

Each project should have an npm script within package.json that looks like:

"scripts": {
  "lint": "eslint --ext .js,.jsx ."
}

This will lint the entire project and is used by other scripts. Note that to get linting on files with .jsx extensions you must tell eslint to include those files when targetting a directory. Do not forget the extension argument (--ext .js,.jsx) or your jsx files will not be linted.

To restrict the scope of the linting run eslint using npx and specify whatever arguments that you need. npx is a tool included with node that runs executables from within node_modules/.bin without having to fully specify the path.

Here are some examples all executed from the command line:

npx eslint --ext .js,.jsx .

Lints the full project. Exactly the same as the npm script above.

npx eslint src/service/foo

Lints all the JavaScript (*.js only, not *.jsx) files in in the given directory.

npx eslint src/component --ext .js,.jsx --fix

Lints all the JavaScript files (both *.js and *.jsx) in the given directory and autofixes errors where possible.

yarn lint --fix

Lints the full project and autofixes errors where possible.

In general if you are specifying a directory as a target you probably want to include the extension argument otherwise eslint will only lint files with the .js extension.

Files

In addition each project should include the following files:

.eslintignore
.huskyrc.js
lint-staged.config.js

These files work in conjunction with the packages included in this package to provide linting from the command line and on commits. The fact that the eslint config now lives within the project means that any editor should be able to provide in-editor linting using the Stack's linting standards.

Content of the config files

.eslintignore

!.*.js
build/*

By default eslint doesn't lint files that start with a .. This ensures that such files are also linted so that JavaScript config files get linted in the same way as other JavaScript files.

.huskyrc.js

module.exports = {
  hooks: {
    'pre-commit': 'lint-staged'
  }
}

Husky is the package that the Stack uses to handle git hooks. This config file sets ups the pre-commit hook to run lint-staged.

lint-staged.config.js

module.exports = {
  '**/*.{js,jsx}': ['eslint --fix', 'git add'],
  '**/*.{css,scss,json,md}': ['prettier --write', 'git add']
}

Note that the file name doesn't start with a dot.

This tells lint-staged to run eslint (including the prettier eslint rules) on all JavaScript files and prettier on a number of other file types. Both tools are run in a way that results in many errors being autofixed and the fixed files are then added to the git commit.

Editors

Now that the eslint config lives in this shared package it should be possible to enable in-editor linting in all the most popular editors just by adding the eslint extension to the editor. Most editors will support running eslint's fix feature when files are saved.

Some editor specific steps are noted here.

Atom

Set the eslint package's Fix errors on save to true. It doesn't seem possible to autofix an unsaved file with Atom's eslint package so setting the package to fix on save appears to be the best that can be done.

VS Code

Code's in-editor linting (using the eslint extension) doesn't pick up the dot file settings from the project. To get the equalivalent behaviour add these to your eslint settings within Code:

"eslint.options": {
  "ignorePattern": [
      "!.*.js",
      "build/*"
  ]
}

You might also want to set the eslint extension's Enable autofix on save to true in settings and add a keybinding for the eslint autofix command:

{
  "key": "ctrl+alt+f",
  "command": "eslint.executeAutofix"
}

That combination fixes on save but also gives the option of fixing the buffer between saves.

Depending on how you load directories into VS Code you might find that VS Code lints some projects but not others. The problem happens in some versions of VS Code if you load an application into the VS Code workspace. The issue is that VS Code fails to find the lint config which lives in the api and app directories. To fix this try adding the following to your settings:

"eslint.workingDirectories": [
    ".",
    "./api",
    "./app"
]

This tells VS Code to check the named directories for the lint config and should let the linting work correctly for both applications and node packages.

Sublime

Unfortunately Sublime's linting doesn't appear to support running eslint's fix feature. The closest solution seems to be adding the Eslint Formatter package then configuring that to fix the file on save:

"format_on_save": true