eslint-config-maxiv

Description

Linting rules for Max IV frontend code.

Installation & Config

1. Install the npm package npm install --save-dev @max-iv/eslint-config-maxiv

2. Extend the config in your local .eslint.config.js or equivalent:

   // eslint.config.js
   import maxiv from "@max-iv/eslint-config-maxiv";
   
   export default [
     ...maxiv,
     // Overrides can go here
     {
       rules: {...}
     }
   ];

3. Extend your local prettier.config.js with the config included in this package:

   // prettier.config.js
   import { prettierConfig } from '@max-iv/eslint-config-maxiv';
   export default prettierConfig;

4. It is a good idea to have the scripts ready in your package.json file:

     "scripts": {
       "format": "prettier --write .",
       "format:check": "prettier --check .",
       "lint": "eslint . --ext .js,.jsx,.ts,.tsx"
     },

   Please note the --ext flag in the lint script. It is needed for the linter to execute on Typescript files as well.

5. When everything is set up to your liking, run the formatter and then the linter by executing the following commands (it will format and lint the code, and automatically fix some of the issues found by the linter):

     npm run format
     npm run lint -- --fix

Recommended Setup

In order for this config package to make any effects in your codebase it needs to be setup in your environment.

It is recommended that you set up the linter/formatter to run whenever there is a change in the codebase. The best way of doing this is to set up it up in your CI-pipelines. Run the npm run format:check command added above to validate that the code is formatted correctly in your pipeline.

It is also strongly recommended to have the formatter and linter running in your IDE. If set up correctly the code you write will be formatted automatically when saving and any linting issues will be visible directly.

Debugging

There are a lot of things to keep in mind when setting up your eslint configs. Rules can easily override each other if imported in the wrong order.

Fortunately there is a useful tool for debugging your setup provided by eslint, namely the Config Inspector.

Run it by navigating to the root of your project, typically where you keep the config files and execute this command:

npx eslint --inspect-config

It will bring up a small web server and point your browser to an interface where all the active rules are listed. There are symbols and tree views showing how the different parts of the config affects the end ruleset.

Visual Studio Code

Install the Prettier and eslint plugins and configure your IDE to use them on save.

1. Open the settings and search for 'Formatter', select Prettier in the dropdown

2. Open the json settings file and add the following lines to configure eslint to check for non-conforming code on the fly:

   {
     "eslint.workingDirectories": [{ "mode": "auto" }],
     "eslint.validate": [
       "css",
       "html",
       "javascript",
       "javascriptreact",
       "typescript",
       "typescriptreact",
     ],
   }

3. Restart the linting system in VSCode, for instance by opening the command palette and running the ESLint: Restart ESLint Server command. This needs to be done every time a change has been done to the ESLint configurations, otherwise the plugin won't give correct reports.

If you do not get errors marked with red wavy underlines in your code:

• Make sure your eslint executable is configured correctly. Best way to avoid this is perhaps to do npm install eslint -g to install it globally.
• Check the output log and look for errors from eslint.

Rule Motivations

Here you can find motivations behind some of the rules in this config package.

Single Quotes

Prettier: singleQuote: true / eslint: '@stylistic/quotes': ['error', 'single']

Single quotes has a few advantages in javascript. Here are some of the main motivations to use this rule:

• Consistency to other JS style guides. Google, Airbnb, Standard JS all use single quotes
• Easier to type, no need for the shift key
• Increased readability and reducing need for escaping, especially in HTML-
• Helps to differentiate js from JSON, since JSON requires double quotes it is a good way of identifying what file is what at a glance

Line Width 1oo / 80

Prettier: printWidth: 100 / eslint '@stylistic/max-len': ... { code: 120, comments: 80 }

Keeping code and comments in shorter lines increases readability. The motivation behind allowing longer rows for the code is that it does not discourage devs from using descriptive naming of methods and variables.

Publishing New Versions

In order for the eslint config to be shared it is published to NPM. For this to work smoothly there is a script in the ./.gitlab-ci.yml file that triggers a publish job every time a tag is added. This setup does not allow for the version to be updated in the package.json file. It is set to 0.0.0 to mark that it is not updated.

When a change is merged back to the main branch, please update the npm version by tagging the commit with the desired version, and push the tag to git. The Gitlab tag interface can be used to add your tags directly. From there it is easy to see the latest version tag and create a new one on the main branch.

Alternatively you can follow these steps to do it from the terminal or your favourite git client:

1. Find the current version number, either by looking at the latest git tag, or by asking npm for the current version, npm show @max-iv/eslint-config-maxiv

2. Make sure to check out the main branch and pull the latest changes

   git checkout main
   git pull

3. Add a git tag with git tag -a x.y.z. Remember to increment the correct number compared to the currently published npm version. For smaller changes patch version should be incremented.

4. Push the tag to git, make sure the pipeline do not fail, git push --tags

Token

The CI setup is quite simple, it uses the Trusted Publisher and OICD token for publishing to NPM. More information can be found in the NPM docs.

Version History

v1.4.0

Fixing an issue with the order of the imports causing some rules to negate each other.

v1.3.0

Typescript configuration added to ESLint config

v1.2.0

Better handling of Prettier rules, adding Prettier plugin to get linting errors

v1.1.0

Adding Eslint Plugin React Hooks rules

v1.0.0

First "official" release

v0.1.0

Initial setup

License

GPL-3.0-or-later

Copyright

Copyright Lund University