eslint-plugin-sfgov

This is the shared eslint configuration for the SF Digital Services team.

Usage

0. Upgrade npm (optional, but strongly recommended):

   npm --version

   If you're running npm version 6.x or earlier, you're going to have issues with shared eslint rule dependencies. You can upgrade npm to the latest version with:

   npm i -g npm@latest

1. Install eslint and eslint-plugin-sfgov as dev dependencies:

   npm install --save-dev eslint@8 eslint-plugin-sfgov@latest

2. Set up your eslint configuration, either in a standalone config file, e.g. .eslintrc.json:

   {
     "plugins": [
       "sfgov"
     ],
     "extends": [
       "plugin:sfgov/recommended"
     ]
   }

   or paste the above JSON into the eslintConfig key of your package.json.

3. Configure additional eslint overrides or environments in your project, if necessary. See the list of available configurations for more info.

4. Test it! Run npx eslint to lint all of the known JS files in your project, or pass specific file paths a la npx eslint src/**/*.js.

   ℹ️ If the issues that your new eslint config surfaces are overwhelming, you can use eslint-nibble to get an overview and focus on specific rules.

   Assuming your JavaScript is committed to git, and depending on the nature of your rule violations, it may also be possible to fix many of them by running eslint with the --fix flag.

5. Add a lint or lint-js entry in the scripts field of your package.json that runs eslint on all of the relevant files in your project.

6. Call npm run lint in your CI workflow to fail builds with malformed code.

Available configurations

Each of the configurations below can be included in the extends array of your eslint configuration.

plugin:sfgov/recommended

This is the "base" configuration that includes:

• standard formatting rules
• An override for the semi rule that rejects semicolons except when they're necessary to avoid pitfalls with automatic semicolon insertion
• eslint:recommended rules
• Import support and the plugin:import/recommended configuration
• Promise support and the plugin:promise/recommended configuration
• Setting parserOptions.ecmaVersion to 9 (ECMAScript 2018)

These rules should work in any environment.

plugin:sfgov/node

This configuration is intended for JavaScript that runs directly in Node, and includes:

• Node support and the plugin:node/recommended configuration
• Disabling of the node/no-unpublished-require rule

plugin:sfgov/babel

This configuration is intended for JavaScript that will be compiled with Babel, and includes:

• Setting ESLint's parser to @babel/eslint-parser
• Setting parserOptions.sourceType to module
• Setting parserOptions.ecmaVersion to 2020

plugin:sfgov/jest

This configuration includes:

• Jest support and the its plugin:jest/recommended configuration
• An override that disables promise/always-return to account for testing scenarios in which promises don't need to return anything, e.g. when using supertest

Why a plugin?

You may have noticed that this package is published as an eslint plugin rather than a "config" (i.e. eslint-config-sfgov). One challenge with shareable configs is that they can't reference their own plugins, which means that you (a consumer of this configuration) have to install all of them in your project. Popular configurations like Airbnb's suggest npx and/or shell one-liners to install all of their peer dependencies in your own package.json, which stinks. This configuration comes with the batteries included, and adds a single dev dependency to your package.json.