# @hubspot/eslint-config-ui-extensions

[ESLint shareable config](https://eslint.org/docs/latest/extend/shareable-configs) for building UI Extensions on HubSpot with React.

This package provides ESLint rules specifically designed for the HubSpot UI Extensions environment. It catches common issues like using unavailable browser APIs, incorrect imports, and other patterns that won't work in the sandboxed web worker context.

## Installation

> **Upgrading from v0.x?** See the [Migration Guide](./MIGRATION.md) for step-by-step instructions.

Install [ESLint](https://eslint.org/) 9+ alongside this package:

```sh
npm i --save-dev eslint @hubspot/eslint-config-ui-extensions
```

## Basic Usage

Create an `eslint.config.js` file in the root of your project:

```js
import { config } from '@hubspot/eslint-config-ui-extensions';

export default [
  ...config,
  // Your project-specific overrides
];
```

Make sure your `package.json` has `"type": "module"` set, then add a lint script:

```json
{
  "type": "module",
  "scripts": {
    "lint": "eslint ."
  }
}
```

Run `npm run lint` to check for linting issues.

## Recommended Setup

The basic config above only includes HubSpot UI Extensions-specific rules. For a production-ready setup, we recommend adding standard ESLint rules, TypeScript support, React Hooks linting, Prettier compatibility, and unused import detection.

### Install Additional Dependencies

```sh
npm i --save-dev @eslint/js typescript-eslint eslint-plugin-react eslint-plugin-react-hooks eslint-config-prettier eslint-plugin-unused-imports
```

### Full Recommended Config

```js
import { defineConfig } from 'eslint/config';
import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import react from 'eslint-plugin-react';
import reactHooks from 'eslint-plugin-react-hooks';
import unusedImports from 'eslint-plugin-unused-imports';
import prettier from 'eslint-config-prettier';
import { config as uiExtensionsConfig } from '@hubspot/eslint-config-ui-extensions';

export default defineConfig([
  // Standard ESLint recommended rules
  js.configs.recommended,

  // TypeScript support with stylistic rules
  tseslint.configs.recommended,
  tseslint.configs.stylistic,

  // React recommended rules + JSX runtime support (React 17+)
  react.configs.flat.recommended,
  react.configs.flat['jsx-runtime'],
  {
    settings: {
      react: { version: 'detect' },
    },
  },

  // HubSpot UI Extensions rules
  ...uiExtensionsConfig,

  // React Hooks rules
  reactHooks.configs.flat['recommended-latest'],

  // Unused imports detection (auto-fixable with --fix)
  {
    plugins: {
      'unused-imports': unusedImports,
    },
    rules: {
      'no-unused-vars': 'off',
      '@typescript-eslint/no-unused-vars': 'off',
      'unused-imports/no-unused-imports': 'error',
      'unused-imports/no-unused-vars': [
        'warn',
        {
          vars: 'all',
          varsIgnorePattern: '^_',
          args: 'after-used',
          argsIgnorePattern: '^_',
        },
      ],
    },
  },

  // Prettier compatibility (must be last to override other configs)
  prettier,
]);
```

### What Each Addition Provides

| Package | Purpose |
| :------ | :------ |
| `@eslint/js` | ESLint's built-in recommended rules for catching common JavaScript issues |
| `typescript-eslint` | TypeScript parsing and linting rules (`stylistic` adds consistent code style enforcement) |
| `eslint-plugin-react` | React-specific rules; `jsx-runtime` config is for React 17+ (no need to import React in every file) |
| `eslint-plugin-react-hooks` | Enforces [Rules of Hooks](https://react.dev/reference/rules/rules-of-hooks) and verifies dependency arrays |
| `eslint-config-prettier` | Disables ESLint rules that conflict with Prettier formatting |
| `eslint-plugin-unused-imports` | Auto-fixable detection and removal of unused imports |

### JavaScript-Only Projects

If you're not using TypeScript, you can simplify the config:

```js
import { defineConfig } from 'eslint/config';
import js from '@eslint/js';
import react from 'eslint-plugin-react';
import reactHooks from 'eslint-plugin-react-hooks';
import unusedImports from 'eslint-plugin-unused-imports';
import prettier from 'eslint-config-prettier';
import { config as uiExtensionsConfig } from '@hubspot/eslint-config-ui-extensions';

export default defineConfig([
  js.configs.recommended,
  react.configs.flat.recommended,
  react.configs.flat['jsx-runtime'],
  {
    settings: {
      react: { version: 'detect' },
    },
  },
  ...uiExtensionsConfig,
  reactHooks.configs.flat['recommended-latest'],
  {
    plugins: {
      'unused-imports': unusedImports,
    },
    rules: {
      'no-unused-vars': 'off',
      'unused-imports/no-unused-imports': 'error',
      'unused-imports/no-unused-vars': [
        'warn',
        {
          vars: 'all',
          varsIgnorePattern: '^_',
          args: 'after-used',
          argsIgnorePattern: '^_',
        },
      ],
    },
  },
  prettier,
]);
```

## Rules

<!-- begin auto-generated rules list -->

🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).

| Name                                                                                   | Description                                                                                                                                                                   | 🔧 |
| :------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :- |
| [no-browser-dialogs](docs/rules/no-browser-dialogs.md)                                 | Prevent usage of native browser dialog APIs (alert, confirm, and prompt) in UI Extensions.                                                                                    |    |
| [no-browser-storage](docs/rules/no-browser-storage.md)                                 | Prevent usage of browser storage APIs (localStorage and sessionStorage) in UI Extensions, which run in a sandboxed web worker environment where these APIs are not available. |    |
| [no-console](docs/rules/no-console.md)                                                 | Prevent usage of console methods in UI Extensions in favor of the SDK logger utility.                                                                                         |    |
| [no-dom-access](docs/rules/no-dom-access.md)                                           | Prevent access to the DOM (document object) in UI Extensions, which run in a sandboxed web worker without DOM access.                                                         |    |
| [no-experimental-imports](docs/rules/no-experimental-imports.md)                       | Warn when importing from the experimental path of @hubspot/ui-extensions.                                                                                                     |    |
| [no-html-elements](docs/rules/no-html-elements.md)                                     | Disallow usage of unsupported HTML elements in UI Extensions.                                                                                                                 |    |
| [no-invalid-extension-point-imports](docs/rules/no-invalid-extension-point-imports.md) | Prevent importing components from unsupported extension points.                                                                                                               |    |
| [no-invalid-image-src](docs/rules/no-invalid-image-src.md)                             | Only allow valid image URLs in the src attribute of Image components from @hubspot/ui-extensions.                                                                             | 🔧 |
| [no-native-http](docs/rules/no-native-http.md)                                         | Prevent usage of native browser HTTP APIs (fetch and XMLHttpRequest) in UI Extensions.                                                                                        |    |
| [no-parent-imports](docs/rules/no-parent-imports.md)                                   | Prevent importing files from outside the extension point root directory                                                                                                       |    |
| [no-restricted-globals](docs/rules/no-restricted-globals.md)                           | Prevent usage of browser globals that are not available in the sandboxed web worker environment.                                                                              |    |

<!-- end auto-generated rules list -->