@hybrbase/eslint-config/README.md

A shareable eslint base configuration for projects.

# Shareable ESLint Config Bases

## 📄 About

Composable eslint config bases for [hybrbase projects](https://github.com/hybrbase) and others.

### → Purpose

The purpose of the package is to provide composable and monorepo friendly [eslint](https://eslint.org/) configurations for JavaScript based projects. It includes features such as performance optimization and the ability to extend pre-defined base configs.

- **Workspace-specific Configuration:** This package enables each workspace in a monorepo to have its own configuration.
- **Configurable:** You can easily create your workspace ESLint config by composing it from pre-defined bases.
- **Convenient:** The use of [@rushstack/eslint-patch] ensures that you don't have to install plugins for each workspace, giving you peace of mind.
- **Efficient:** The performance of the package is improved by enabling plugins based on file naming conventions.

<br>

## 💿 Installation

To install `@hybrbase/eslint-config`, add it as a dev-dependency to your monorepo workspaces and in your root `package.json`:

```bash
# Install as dev-dependency into monorepo root
$ pnpm add -wD \
  @hybrbase/eslint-config \
  npm-run-all

# Install as dev-dependency per workspace (app or package)
$ pnpm --filter=my-first-app add -D @hybrbase/eslint-config
$ pnpm --filter=my-first-package add -D @hybrbase/eslint-config
```

Assuming that you have the following structure:

```bash
.
├── package.json (root)
├── apps
│   └── my-first-app
│       ├── package.json
│       └── ... (other app files)
└── packages
    └── my-first-package
        ├── package.json
        └── ... (other package files)
```

<br>

> PS: if you use graphql rules, add the `@graphql-eslint/eslint-plugin` as well (not done by default as it comes with many transitive deps you might not need)

<br>

### → Scripts

Here are some example scripts you can add to your root `package.json`:

```bash
# Runs md, js and secrets linters
$ pnpm pkg set scripts.lint="run-p lint:turbo lint:md lint:html lint:css lint:secrets format:package-json"

# Runs lint command using turbo (affects all */packages) with auto-fix and sorts package.json after
$ pnpm pkg set scripts.format="turbo run format && pnpm format:package-json"

# Runs lint only on *.md files
$ pnpm pkg set scripts.lint:md="markdownlint --fix **/*.md --ignore '**/node_modules/**' --ignore '**/CHANGELOG.md'"

# Sorts package.json in project
$ pnpm pkg set scripts.format:package-json="sort-package-json package.json apps/*/package.json packages/*/package.json"

# Searches only for secrets
$ pnpm pkg set scripts.lint:secrets="secretlint **/*"

# Runs lint command over all packages using turbopack
$ pnpm pkg set scripts.lint:turbo="turbo lint"
```

You can also manually add commands to your workspaces, located in `apps/*` and `packages/*`. For example:

```json
{
  "scripts": {
    "lint": "eslint --ext .ts,.js,.cjs,.mjs --cache --cache-location ../../.cache/eslint/eslint-config.eslintcache",
    "format": "eslint --ext .ts,.tsx,.js,.jsx,.mjs,.cjs,.mts,.cts --fix --cache --cache-location ../../.cache/eslint/eslint-config.eslintcache"
  }
}
```

<br>

## 💻 Usage

To create your workspace-specific ESLint configuration, create a file `./apps/my-first-app/.eslintrc.js` or `./apps/my-first-app/.eslintrc.cjs` that extends any of the existing base configs.

For example, if you have a Next.js application, your `.eslintrc.js` would look something like this:

```javascript
// Next line only required if you're using a monorepo
// Workaround for https://github.com/eslint/eslint/issues/3458 (re-export of @rushstack/eslint-patch)
require("@hybrbase/eslint-config/patch/modern-module-resolution");

module.exports = {
  root: true,
  parserOptions: {
    tsconfigRootDir: __dirname,
    project: 'tsconfig.json',
  },
  ignorePatterns: [...getDefaultIgnorePatterns(), '.next', '.out', '/storybook-static'],
  extends: [
    '@hybrbase/eslint-config/typescript',
    '@hybrbase/eslint-config/regexp',
    '@hybrbase/eslint-config/sonar',
    '@hybrbase/eslint-config/jest',
    '@hybrbase/eslint-config/rtl',
    '@hybrbase/eslint-config/react',
    '@hybrbase/eslint-config/react-query,
    '@hybrbase/eslint-config/tailwind',
    '@hybrbase/eslint-config/mdx',
    // '@hybrbase/eslint-config/graphql-schema',
    // '@hybrbase/eslint-config/storybook',
    // '@hybrbase/eslint-config/playwright',

    // Add specific rules for your framework if needed.
    // ie:
    'plugin:@next/next/core-web-vitals',
    // '@remix-run/eslint-config',
    // ...

    // Post configure the prettier base and run prettier
    // without conflicts thx to eslint-plugin-prettier
    "@hybrbase/eslint-config/prettier-plugin",
    // Alternatively to the above if you're already running prettier
    // we can get a speed up by using on eslint-prettier-config
    // "@hybrbase/eslint-config/prettier-config",
  ],
  rules: {
    // Specific global rules for your app or package
    // https://github.com/vercel/next.js/discussions/16832
    '@next/next/no-img-element': 'off',
    // For the sake of example
    // https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/anchor-is-valid.md
    'jsx-a11y/anchor-is-valid': 'off',
    '@typescript-eslint/no-unused-vars': 'off',
  },
  overrides: [
    // Specific file rules for your app or package
    {
      files: ['src/pages/\\_*.{ts,tsx}'],
      rules: {
        'react/display-name': 'off',
      },
    },
    {
      files: ['src/stories/*.ts'],
      rules: {
        '@typescript-eslint/naming-convention': 'off',
      },
    },
  ],
}
```

> **Tip:**
>
> - **Prettier**: `@hybrbase/eslint-config/prettier-plugin` and `@hybrbase/eslint-config/prettier-config` are
>   mutually exclusives. Choose one. The `prettier-config` suppose that you run prettier independently. The `prettier-plugin`
>   will run prettier for you. Easiest the `prettier-plugin`, fastest `prettier-config` (this mostly depends
>   if you set up and persist caches as well)
>
> - **Performance**: Some rules are known to be slow (ie: `import/namespace`...). Slowest identified rules are disabled depending
>   on context (ie: `*.test.tsx?` might not need everything). Depending on project
>   it's possible to disable entirely some slow rules (ie: `'import/namespace': 'off'`). A good tip
>   run eslint with the `TIMING=1` to identify slow rules.

<br>

## 🛠️ Base Configs

You can find the bases in [./src/bases](./src/bases).

| Base                                              | Match convention                  | Scope                                                           |
| :------------------------------------------------ | :-------------------------------- | :-------------------------------------------------------------- |
| [typescript](./src/bases/typescript.js)           | _all_                             | Naming conventions, consistent imports, import sorting...       |
| [sonar](./src/bases/sonar.js)                     | `*.{js,jsx,ts,tsx}`               | Keep levels of code complexity sane. (excl test and stories)    |
| [regexp](./src/bases/regexp.js)                   | `*.{js,jsx,jsx,tsx}`              | Keep regexp consistent and safer.                               |
| [react](./src/bases/react.js)                     | `*.{jsx,tsx}`                     | Recommendations for react, react-hooks and jsx projects.        |
| [react-query](./src/bases/react-query.js)         | `**/?(*.)+(test).{js,jsx,ts,tsx}` | Enforce "recommended" react-query usage.                        |
| [jest](./src/bases/jest.js)                       | `**/?(*.)+(test).{js,jsx,ts,tsx}` | Catch inconsistencies or error in jest tests.                   |
| [rtl](./src/bases/rtl.js)                         | `**/?(*.)+(test).{js,jsx,ts,tsx}` | Potential errors / deprecations in react-testing-library tests. |
| [graphql-schema](./src/bases/graphql-schema.js)   | `*.graphql`                       | Ensure validity of graphql schema files.                        |
| [storybook](./src/bases/storybook.js)             | `*.stories.{ts,tsx,mdx}`          | Potential errors / deprecations in stories.                     |
| [playwright](./src/bases/playwright.js)           | `**/e2e/**/*.test.{js,ts}`        | Keep "recommended" playwright usage.                            |
| [prettier-plugin](./src/bases/prettier-plugin.js) | _all_                             | Post configure eslint for prettier compatibility.               |

<br>

> **Notes**:
>
> - The order is important. Some bases will disable or tune previously defined
>   rules. For example the [react base](./src/bases/react.js) will tune the naming conventions
>   for function components and increase recommended cognitive complexity. The [typescript base](./src/bases/typescript.js)
>   will also relax conventions for javascript files.
>
> - Based on filename conventions some rules are relaxed or disabled to avoid false positives and
>   keep a good level of performance. For example the [sonar base](./src/bases/sonar.js) won't run on
>   test and storybook files. If you work on different conventions the patterns must be updated.

<br>

## 🧹 Prettier integration

Two ways to work with prettier.

- `@hybrbase/eslint-config/prettier-plugin` — eslint will run prettier under the hood (**default**)
- `@hybrbase/eslint-config/prettier-config` — eslint will just disable some conflicting rules (so you'll need to run prettier after)

The first method is recommended for simplicity. For best perf use the cache option to run eslint.

Tune the behaviour by creating a config, named `.prettierrc.js` in root directory of project and in each package or app.

<br>

### → Example Structure

```bash
.
├── .prettierrc.js (root)
├── package.json (root)
├── apps
│   └── my-first-app
│       ├── .prettierrc.js
│       ├── package.json
│       └── ... (other app files)
└── packages
    └── my-first-package
        ├── .prettierrc.js
        ├── package.json
        └── ... (other package files)
```

<br>

### → `.prettierrc.js` for root of monorepo

```javascript
// @ts-check

const { prettier } = require('@hybrbase/eslint-config/configs')

/**
 * @type {import('prettier').Config}
 */
module.exports = {
  ...prettier,
  overrides: [
    ...overrides,
    ...[
      {
        files: '*.md',
        options: {
          singleQuote: false,
          quoteProps: 'preserve',
        },
      },
    ],
  ],
}
```

> **Tip**: You can tune the provided [prettier.base.config](./src/prettier.base.config.js) for your own needs.

<br>

## 📝 Notes

### → Typescript

Generic typescript project, mostly based on

| Type/Plugin                                                                                      | Comment                                                                      |
| :----------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- |
| [eslint:recommended](https://eslint.org/docs/rules/)                                             | The basics for code linting.                                                 |
| [@typescript-eslint/recommended](https://typescript-eslint.io/rules/)                            | The basics for typescript.                                                   |
| [@typescript-eslint/consistent-type](https://typescript-eslint.io/rules/consistent-type-imports) | Use TS 3.8+ imports/exports, helps with [esbuild](https://esbuild.github.io) |
| [@typescript-eslint/naming-convention](https://typescript-eslint.io/rules/naming-convention)     |                                                                              |
| [eslint-plugin-import](https://github.com/import-js/eslint-plugin-import)                        | Order imports                                                                |

### → Sonarjs

| Type/Plugin                                                                               | Comment                      |
| :---------------------------------------------------------------------------------------- | :--------------------------- |
| [eslint-plugin-sonarjs/recommended](https://github.com/SonarSource/eslint-plugin-sonarjs) | Help to keep complexity sane |

### → React

| Type/Plugin                                                                                                             | Comment                                  |
| :---------------------------------------------------------------------------------------------------------------------- | :--------------------------------------- |
| [eslint-plugin-react/recommended](https://github.com/yannickcr/eslint-plugin-react)                                     |                                          |
| [eslint-plugin-react-hooks/recommended](https://github.com/facebook/react/tree/main/packages/eslint-plugin-react-hooks) |                                          |
| [eslint-plugin-jsx-a11y/recommended](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y)                              | Helps to produce accessibility-ready jsx |

### → Jest

| Type/Plugin                                                                            | Comment                     |
| :------------------------------------------------------------------------------------- | :-------------------------- |
| [eslint-plugin-jest/recommended](https://github.com/jest-community/eslint-plugin-jest) | Jest recommended practices. |

### → React Testing Library

| Type/Plugin                                                                                                   | Comment                               |
| :------------------------------------------------------------------------------------------------------------ | :------------------------------------ |
| [eslint-plugin-testing-library/recommended](https://github.com/testing-library/eslint-plugin-testing-library) | Ease when using react-testing-library |

### → Regexp

| Type/Plugin                                                                           | Comment                                                              |
| :------------------------------------------------------------------------------------ | :------------------------------------------------------------------- |
| [eslint-plugin-regexp/recommended](https://github.com/ota-meshi/eslint-plugin-regexp) | ESLint plugin for finding regex mistakes and style guide violations. |

### → MDX

| Type/Plugin                                                                                      | Comment                                                                                                               |
| :----------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- |
| [mdx-js/eslint-mdx](https://github.com/mdx-js/eslint-mdx/tree/master/packages/eslint-plugin-mdx) | [ESLint](https://eslint.org/) Parser/Plugin for [MDX](https://github.com/mdx-js/mdx), helps you lint all ES syntaxes. |

### → HTML

| Type/Plugin                                                        | Comment                        |
| :----------------------------------------------------------------- | :----------------------------- |
| [html-eslint/recommended](https://github.com/yeonjuan/html-eslint) | ESLint plugin for linting HTML |