@woltapp/eslint-plugin-browserbug

> Lint rules for documenting, and eventually removing, browser bug workarounds.

Motivation

As a web frontend codebase grows, it accumulates codepaths that work around
specific browser bugs, quirks, and implementation details. These workarounds are
often a pragmatic choice, in order to get things to work or look correct.

Over a long period of time, these browser bug workarounds end up looking
mysterious at best, and scary at worst. It often seems better to "leave them
be", or risk things breaking. This accumulation of workarounds can make
codepaths less efficient, leads to larger bundle sizes, and makes the codebase
less inviting.

To tackle this problem, these lint rules offer a way to document such browser
bugs and their versions, and to warn you when the browser versions change.

The rules are backed by your project's
browserslist config.
Browserslist is commonly used by similar tools, such as automated code
transpilation via Babel, SWC, and PostCSS. Thus, you are prompted to change
things _at a pace dictated by your project's browser support_, instead of
arbitrary version numbers.

While automated tools and code transpilation go a long way, there are categories
of bugs, workarounds and manual feature detection, that require some manual
intervention. These lint rules tackle this space.

$3

Imagine you are feature-detecting a specific browser API. When your support
targets change, the linter will notify you to re-evaluate, and change either the
code or the annotation.

``tsx
// @browserbug safari last-checked 17.2, chrome last-checked 120 -- Does not support {focusVisible} option
if (!supportsFocusVisibleOption()) {
/ complex workaround /
} else {
element.focus({ focusVisible: true });
}
`

Usage

$3

`sh
npm i @woltapp/eslint-plugin-browserbug --save-dev
`

$3

Add browserbug to your
ESLint configuration file.

If you use the recommended config:

`js
import browserbug from '@woltapp/eslint-plugin-browserbug';

export default [
browserbug.configs.recommended,
{
rules: {
// customise any rules here
'browserbug/no-outdated': 'error',
},
},
];
`

This sets you up with the recommended set of rules. You can configure the rules
you want to use under the rules section.

Alternatively, you can specify only the plugin, and set each rule separately

`js
import browserbug from '@woltapp/eslint-plugin-browserbug';

export default [
{
plugins: {
browserbug: browserbug.plugin,
},
rules: {
'browserbug/no-outdated': 'error',
},
},
];
`

Note: for the rules to practically work, you must also specify a
browserslist config in you repository. Any of the
supported browserslist methods would work, for example a browserslist entry in
package.json.

$3

The plugin works via code comments.

Comments are prefixed as @browserbug, and include a list of descriptors.
Descriptors can be comma separated. A comment can follow the list of
descriptors, starting with --.

`ts
// The no-outdated rule will report an error if the specified range is no longer supported.
//
// @browserbug safari lower-than-or-equal 15.4 -- Some comment here
// @browserbug safari lte 15.4
// @browserbug safari lower-than 16.0
// @browserbug safari lt 16.0
// @browserbug chrome equal 117
// @browserbug chrome between 117 120 -- Inclusive range
//
// These descriptors are equivalent to 'equal' and 'between' for the purposes of no-outdated.
// Additionally, the last-checked-updated rule will report an error if there is a newer version of the specified versions available.
//
// @browserbug chrome last-checked 121
// @browserbug chrome last-checked-between 117 121 -- Same as last-checked, but documents when a workaround started
`

Configurations

| | Name |
| :-- | :------------ |
| ✅ | recommended |

Rules

💼 Configurations enabled in.\
✅ Set in the recommended configuration.

| Name        | Description | 💼 |
| :--------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :-- |
| no-outdated | Ensures that no browser workarounds exist, if browserslist support for that browser is outside the specified range. | ✅ |

Running locally in another repository

At the moment, the package is not published on any registry. Thus, you must
clone the repo and link the package on your machine. This is also useful if you
are contributing to the development, and want to test with a real codebase.

(The following is adapted from
typescript-eslint's excellent guide on local linking)

The general strategy is:

1. Global linking: Use your package manager's global link
command to make the eslint-plugin-browserbug packages available as a global
symlink.
2. Repository linking: Use your package manager's link
command to reference that global symlink in the local downstream repository.
3. Usage: Test your local rules and plugins by enabling them in the
local downstream repository.

$3

To make eslint-plugin-browserbug available globally, run the link command from
the package root (i.e. packages/eslint-plugin-browserbug). The command
depends on your package manager:

- npm:
npm link
- pnpm: pnpm link --global
- Yarn v1 / classic:
yarn link
- Yarn v2 / v3 / berry:
_skip this step altogether_

$3

Now that the package is available locally, you can link to it in the local
downstream repository.

Run that repository's package manager's link command:

- npm: npm link @woltapp/eslint-plugin-browserbug
- pnpm: pnpm link --global @woltapp/eslint-plugin-browserbug
- Yarn v1 / classic: yarn link @woltapp/eslint-plugin-browserbug
- Yarn v2 / v3 / berry:
yarn link /path/to/your/browserbug/packages/eslint-plugin-browserbug
- This will add a resolutions entry for each package in the local downstream
repository's package.json

Now, you should be able to run ESLint in the local downstream repository as you
normally would, and have it reference the local
@woltapp/eslint-plugin-browserbug` package.