@nexusui/eslint-config/README.md

nexus eslint config

# NexusUI ESLint Config

This is a [Shareable Configuration](https://eslint.org/docs/latest/developer-guide/shareable-configs.html#publishing-a-shareable-config) for ESLint. This is the configuration used in all NexusUI packages and contains linting rules that we recommend for all NexusUI applications.
> This ESLint configuration is based off of the [airbnb](https://www.npmjs.com/package/eslint-config-airbnb-base) base rules and [@typescript-eslint](https://typescript-eslint.io/) recommended rules. It covers `javascript`, `typescript`, `jsx-a11y`, `react`, `react-hooks`, `jest` and `testing-library`.

## Installation

1) First, add the necessary peer dependencies to your project's `devDependencies`:

```sh
# With yarn
yarn add --dev eslint

# With npm
npm install --save-dev eslint
```

2) Second, add the NexusUI eslint config library as a `devDependency` to your project:

```sh
# With yarn
yarn add --dev @nexusui/eslint-config

# With npm
npm install --save-dev @nexusui/eslint-config
```

3) Third, if add [eslint-config-prettier](https://www.npmjs.com/package/eslint-config-prettier) and [eslint-plugin-prettier](https://www.npmjs.com/package/eslint-plugin-prettier) which will disable ESLint rules that conflict with prettier rules (prettier rules will take precedence over ESLint) if combining `eslint` and `prettier`. Otherwise, it is optional.

```sh
# With yarn
yarn add --dev eslint-config-prettier eslint-plugin-prettier

# With npm
npm install --save-dev eslint-config-prettier eslint-plugin-prettier
```

## Usage

### 1. Flat Config (eslint.config.mjs, recommended for modern projects)

@NexusUI/eslint-config now supports [ESLint Flat Config](https://eslint.org/docs/latest/use/configure/configuration-files-new), which is suitable for modern frontend projects such as Vite and Next.js.

#### Update `eslint.config.mjs` at your project root:

```js
import nexusConfig from '@nexusui/eslint-config/flat';

export default [
  ...nexusConfig,
  // You can add custom ignores or rules here
];
```

- React recommended configs are already included.
- Unified style for TypeScript/JS/React.

---

### 2. Traditional extends approach (compatible with .eslintrc.js/.json)

Create a configuration file `.eslintrc.json` in the root directory and fill in the details here.

#### Basic

In the simplest case, you can simply extend the `@nexusui` eslint config:

```json
{
  "env": {
    "browser": true,
    "jest": true,
    "es2021": true
  },
  "extends": ["@nexusui"],
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "project": ["tsconfig.json"]
  },
}
```

#### Popular Rule Extensions

You may wish to define your own additional rules or tweak some of the recommended settings. Some popular additions are shown below:

* Combine with prettier， add `prettier-config` and `prettier` to disable ESLint rules that conflict with prettier rules.
* Override the necessary rules for your project.

```json
{
  "env": {
    "browser": true,
    "jest": true,
    "es2021": true
  },
  "extends": ["@nexusui", "prettier"],
  "plugins": ["prettier"],
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "project": ["tsconfig.json"]
  },
  "rules": {
    "prettier/prettier": [
      "warn",
      {
        "endOfLine": "auto"
      }
    ]
  },

  "overrides": [
    {
      "files": ["*.test.ts", "*.test.tsx", "e2e/**/*.ts", "test-utils.tsx", "msw-server.ts", "setupTests.ts", "log.ts"],
      "rules": {
        "no-console": "off",
        "no-await-in-loop": "off",
        "class-methods-use-this": "off",
        "@typescript-eslint/no-unused-expressions": "off",
        "@typescript-eslint/no-unused-vars": "off",
        "@typescript-eslint/no-restricted-imports": "off"
      }
    },
    {
      "files": ["*.stories.tsx"],
      "rules": {
        "@typescript-eslint/no-unused-expressions": "off",
        "@typescript-eslint/no-unused-vars": "off",
        "@typescript-eslint/no-restricted-imports": "off"
      }
    }
  ]
}
```

#### Scripts
Update the `package.json` file to add `eslint` scripts.

```json
// package.json
"scripts": {
  "lint": "eslint .",
  "lint-and-fix": "eslint . --fix"
}
```

## Migration Guide

### 2.X.X -> 3.0.0

If you were using version 2.x.x before and plan to upgrade to version 3.0.0, please read the update below carefully.

#### 1) Replaced `eslint-config-airbnb-typescript` with official TypeScript ESLint packages

We've replaced `eslint-config-airbnb-typescript` with the official TypeScript ESLint packages (`@typescript-eslint/eslint-plugin` and `@typescript-eslint/parser`) for better TypeScript support and long-term maintenance. This change brings:

- Improved TypeScript integration
- Better type-aware linting rules
- More granular control over TypeScript-specific rules

Key changes:
- Added TypeScript as a peer dependency
- Updated TypeScript-specific rules
- Enhanced type checking in linting

To migrate:
1. Update your `eslint.config.mjs` to import and use the NexusUI eslint config as shown in the "Update eslint.config.mjs" section.
3. Review any TypeScript-specific rules in your project's ESLint config

### 1.X.X -> 2.0.0

If you were using version 1.x.x before and plan to upgrade to version 2.0.0, please read the update below carefully.

#### 1) `eslint-config-react-app` dependency was removed

If you want to continue to use the `react-app` rules, you can add the `eslint-config-react-app` package to your project's `devDependencies` and extend it in your `.eslintrc.json` file.

```sh
# With yarn
yarn add --dev eslint-config-react-app
```

```tsx
// .eslintrc.json
{
    "env": {
        "browser": true,
        "jest": true,
        "es2021": true
    },
    "extends": ["@nexusui", "react-app", "react-app/jest", "prettier"]
    "plugins": ["prettier"],
    "parser": "@typescript-eslint/parser",
    "parserOptions": {
        "project": ["tsconfig.json"]
    },
    "rules": {
        // Your rules

        // Enforce a convention in module import order.
        "import/order": "off", // It's annoying
        // Ensure consistent use of file extension within the import path.
        "import/extensions": "off", // Not necessary in most case
        // Prefer a default export if module exports a single name or multiple names.
        "import/prefer-default-export": "off", // Not necessary
        // Forbid anonymous values as default exports.
        "import/no-anonymous-default-export": "off", // Should allow
    }
}

```


### 0.X.X -> 1.0.0

If you were using version 0.x.x before and plan to upgrade to version 1.0.0, please read the update below carefully.

#### 1) `google` lint was removed

#### 2) `prettier` lint was removed

We removed `eslint-config-prettier` and `eslint-plugin-prettier` from package. As prettier config is often used as the last item to disable ESLint rules that conflict with prettier rules. Putting it in the package loses the flexibility of expansion, so it needs to be used at the app layer now.

### 3） `airbnb` and `airbnb-typescript` lint were added
We replaced [google](https://github.com/google/eslint-config-google) lint to [airbnb](https://github.com/google/eslint-config-airbnb-base) lint, as `google` lint archived on Jan 11, 2023. `airbnb` lint includes full ECMAScript 6+ rules and it's a popular and continuously maintained rule base.


```tsx
// before (0.x.x)
{
  "env": {
    "browser": true,
    "jest": true,
    "es2021": true
  },
  "extends": ["@nexusui"],
  "rules": {
    // Your rules
  }
}

// after (1.0.0)
{
  "env": {
    "browser": true,
    "jest": true,
    "es2021": true
  },
  "extends": ["@nexusui", "prettier"],
  "plugins": ["prettier"],
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "project": ["tsconfig.json"]
  },
  "rules": {
    // Your rules
  }
}
```

## Related Packages

[@nexusui/prettier-config](https://www.npmjs.com/package/@nexusui/prettier-config) is a complementary package that includes recommended prettier [Shareable Configuration](https://prettier.io/docs/en/configuration.html#sharing-configurations) for NexusUI projects.