@widergy/eslint-config

Widergy's shared ESLint configuration, supporting JavaScript, TypeScript, React, and React Native.

Prerequisites

[!IMPORTANT] This configuration package only supports ESLint v9 Flat Config. Please ensure you have upgraded to ESLint v9 before implementing this linter.

Installation

1. Install the package:

   npm install -D @widergy/eslint-config eslint

   [!NOTE] Peer dependencies (like prettier, typescript, plugins, etc.) should be added on a per-necessity basis. The linter will fail if a required dependency for your specific configuration is missing. Read the error messages and install the missing packages as needed. This prevents installing unnecessary packages.

2. Verify Prettier Configuration: Ensure your project's .prettierrc file matches the rules configured in this package to avoid conflicts between the linter and the formatter.

   • Reference the Prettier rules in the "Rules Documentation" section below.

Post Installation (Legacy Error Handling)

To handle retrocompatibility with previous errors and avoid blocking the migration, follow these steps:

1. Add lint-suppress script: Add the following script to your package.json:

   "scripts": {
     "lint-suppress": "eslint src --suppress-all"
   }

   • This command suppresses all current errors, allowing you to migrate without fixing everything immediately.
   • Run this once after successful installation to generate the eslint-suppressions.json file.
   • Do not run this daily. Only use it when you change rules and want to ignore new legacy errors.

2. Update lint script: Modify your lint script to prune unused suppressions:

   "scripts": {
     "lint": "eslint src --prune-suppressions"
   }

   • --prune-suppressions: Automatically removes suppressions for rules that are no longer violated.

3. Git Hooks:

   • It is recommended to run the linting process in the prepush hook of your repository.
   • If you are currently using precommit, consider moving it to prepush to avoid slowing down commits.

CircleCI

The linter runs on CircleCI as a dedicated pr-checks pipeline, separate from the main deploy pipeline. It is triggered on demand by commenting run-ci on a pull request — no CI minutes are spent on every push.

Lint job (pr-checks.yml)

Create .circleci/pr-checks.yml. Replace <NODE_VERSION> with the Node.js version your project uses (e.g. 20.19). If your project requires syncing gitignored assets or loading config files before linting (e.g. via yarn sync or yarn loadConfig), add those steps before Run lint.

version: 2.1

commands:
  cache-yarn:
    steps:
      - restore_cache:
          keys:
            - yarn-deps-{{ checksum "yarn.lock" }}
      - run: yarn install --frozen-lockfile
      - save_cache:
          paths:
            - ~/.cache/yarn
          key: yarn-deps-{{ checksum "yarn.lock" }}

jobs:
  lint:
    docker:
      - image: cimg/node:<NODE_VERSION>
    steps:
      - checkout
      - cache-yarn
      - run:
          name: Run lint
          command: yarn lint

workflows:
  pr-checks:
    jobs:
      - lint

CircleCI pipeline setup

Once pr-checks.yml is merged to the default branch, configure a new pipeline in CircleCI using the GitHub App integration:

1. In the CircleCI app, open the project and go to Project Settings → Project Setup.
2. Click Add GitHub Pipeline.
3. Set Config filepath to .circleci/pr-checks.yml (leave Config source and Checkout source as the repo default).
4. Under Trigger on..., click GitHub trigger + and configure:
   • Trigger event: PR comment
   • Comment text: run-ci (exact match)
5. Save.

[!NOTE] This creates a pipeline completely independent from the main config.yml deploy pipeline. It only runs when the exact comment run-ci is posted on a PR. The trigger uses CircleCI's native GitHub App integration — no additional GitHub Actions workflow is needed.

Repositories with CircleCI lint configured

The following repositories have .circleci/pr-checks.yml and the CircleCI pipeline already set up. Update this list when the setup is completed in a new repository.

| Repository | Type | |---|---| | AgentGO-Chat-Web | App | | AgentGO-Backoffice-Web | App | | Customer-Hub-Web | App | | UtilityGO-Office-Mobile | App | | UtilityGO-Office-Web | App | | UtilityGO-Totem-Web | App | | Energy-UI | Library | | Energy-UI-Mobile | Library | | UtilityGO-Smart-Bill-Mobile | Library | | UtilityGO-Smart-Bill-Web | Library | | web-utils | Library |

Usage

Import the specific configuration based on your project type in your eslint.config.js file.

Available Configurations

• @widergy/eslint-config/javascript: JS/TS only repositories (helpers, internal libraries, etc.).
• @widergy/eslint-config/react: React Web projects.
• @widergy/eslint-config/react-native: React Native Mobile projects.

Example (React Project)

import reactConfig from "@widergy/eslint-config/react";

export default [
  ...reactConfig,
  {
    // Custom overrides or specific project settings can be added here
  },
];

Rules Documentation

For detailed information on the rules enabled in this configuration, please refer to the official documentation for each plugin/rule set:

• Base Rules (ESLint): https://eslint.org/docs/latest/rules
• Import Rules: https://github.com/import-js/eslint-plugin-import/tree/main/docs/rules
• Prettier Rules: https://prettier.io/docs/options
• React Rules: https://github.com/jsx-eslint/eslint-plugin-react/tree/master/docs/rules
• React Hooks Rules: https://react.dev/reference/eslint-plugin-react-hooks
• React Native Rules: https://github.com/Intellicode/eslint-plugin-react-native/tree/master/docs/rules
• JSX A11y Rules: https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/tree/main/docs/rules

Contributing

We welcome contributions to improve our shared configuration! To propose a change (add, remove, or modify a rule):

1. Open a GitHub Discussion: Go to the "Discussions" tab in this repository.
2. Create a Poll: Start a new discussion with a poll.
3. Required Information:
   • Title: The name of the rule you want to change.
   • Summary: A brief explanation of the proposed change.
   • Documentation: A link to the official documentation for the rule (use the links in the "Rules Documentation" section).
   • Pros/Cons: If applicable, list the arguments for and against the change for each option in the poll.