@hubspot/eslint-config-ui-extensions 0.12.0 → 1.1.0

package/README.md

@@ -1,47 +1,191 @@
 # @hubspot/eslint-config-ui-extensions
 
-[eslint shareable configs](https://eslint.org/docs/latest/extend/shareable-configs) for building UI Extensions on HubSpot with React.
+[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
 
-You'll first need to install [ESLint](https://eslint.org/) and alongside this package:
+> **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
 
-## Usage
-
-Create an .eslintrc.js file in the root of your project:
+Create an `eslint.config.js` file in the root of your project:
 
 ```js
-module.exports = {
-  extends: "@hubspot/ui-extensions",
-  ignorePatterns: ["node_modules", "dist"],
-};
+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 ."
+  }
+}
 ```
 
-For those using TypeScript, we'll likely expand this package to include a base setup in the near future, but in the meantime you can start here and follow these steps to get TS support:
+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
 
-- `npm i --save-dev @typescript-eslint/parser @typescript-eslint/eslint-plugin`
-- Adapt your lint script in package.json (if applicable) to make sure you're targeting your source files, perhaps something like `"lint": "npx eslint . --ext .ts,.tsx"`
-- Update your eslintrc config:
+```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
 
-```diff
--extends: ['@hubspot/ui-extensions'],
-+extends: ['@hubspot/ui-extensions', 'plugin:@typescript-eslint/recommended'],
-+plugins: ['@typescript-eslint'],
+```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,
+]);
 ```
 
-Running `npm run lint`, you should now see TypeScript-aware linting in your terminal output and it will likely automatically work inside your editor of choice as well (though some editors may require additional config steps).
+### 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 |
 
-## Rules
+### JavaScript-Only Projects
 
-This config extends the following configs, meaning you can customize the `rules` entry in your project-level config to include any rules from these packages:
+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
 
-- ['eslint:recommended'](https://eslint.org/docs/latest/rules/)
-- ['plugin:react/recommended'](https://www.npmjs.com/package/eslint-plugin-react)
-- ['plugin:react-hooks/recommended'](https://github.com/facebook/react/tree/main/packages/eslint-plugin-react-hooks)
-- ['prettier'](https://www.npmjs.com/package/eslint-config-prettier)
+<!-- 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 -->

package/dist/__tests__/index.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/index.spec.js

@@ -0,0 +1,303 @@
+import { ESLint } from 'eslint';
+import { config } from "../index.js";
+/**
+ * A helper function to lint code with the imported ESLint config.
+ * Returns the linting messages.
+ */
+async function lintCode(code, filePath, cwd) {
+    const eslint = new ESLint({
+        overrideConfigFile: true,
+        overrideConfig: config,
+        ...(cwd && { cwd }),
+    });
+    const results = await eslint.lintText(code, { filePath });
+    return results[0].messages;
+}
+/**
+ * Config regression tests
+ *
+ * These tests ensure we don't accidentally break the exported config by:
+ * - Verifying critical rules are present and fire correctly
+ * - Validating the config structure loads without errors
+ *
+ * For imported rules, we simply want to make sure they are registered correctly.
+ * The maintainer of the ruleset is responsible for testing the actual rule logic.
+ *
+ * When custom rules are added:
+ * - They'll have dedicated test files for in-depth testing
+ * - They should also have a smoke test here to verify they're registered
+ */
+describe('config', () => {
+    describe('custom no-restricted-globals rule', () => {
+        it('should error when using restricted globals', async () => {
+            const code = `
+        const path = location.pathname;
+      `;
+            const messages = await lintCode(code, 'test.js');
+            const customRuleError = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-restricted-globals');
+            expect(customRuleError).toBeDefined();
+            expect(customRuleError?.severity).toBe(2);
+            expect(customRuleError?.message).toContain('location');
+        });
+        it('should allow local variables with restricted names', async () => {
+            const code = `
+        const location = { pathname: '/test' };
+        console.log(location.pathname);
+      `;
+            const messages = await lintCode(code, 'test.js');
+            const customRuleError = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-restricted-globals');
+            expect(customRuleError).toBeUndefined();
+        });
+    });
+    describe('JSX support', () => {
+        it('should parse JSX syntax without errors', async () => {
+            const code = `
+        function App() {
+          return <Button>Click Me</Button>;
+        }
+      `;
+            const messages = await lintCode(code, 'test.tsx');
+            const parseErrors = messages.filter((m) => m.fatal);
+            expect(parseErrors).toHaveLength(0);
+        });
+    });
+    describe('custom no-html-elements rule', () => {
+        it('should error when using unsupported HTML elements', async () => {
+            const code = `
+        const element = <div>Hello</div>;
+      `;
+            const messages = await lintCode(code, 'test.jsx');
+            const customRuleError = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-html-elements');
+            expect(customRuleError).toBeDefined();
+            expect(customRuleError?.severity).toBe(2);
+        });
+        it('should allow usage of supported elements', async () => {
+            const code = `
+        const element = <Button>Click Me</Button>;
+      `;
+            const messages = await lintCode(code, 'test.jsx');
+            const customRuleError = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-html-elements');
+            expect(customRuleError).toBeUndefined();
+        });
+    });
+    describe('custom no-invalid-extension-point-imports rule', () => {
+        it('should error when importing from an invalid extension point', async () => {
+            const code = `
+        import { SettingsComponent } from '@hubspot/ui-extensions/settings';
+      `;
+            const messages = await lintCode(code, 'src/app/cards/MyCard.tsx', '/path/to/project/src/app/cards');
+            const customRuleError = messages.find((m) => m.ruleId ===
+                '@hubspot/ui-extensions/no-invalid-extension-point-imports');
+            expect(customRuleError).toBeDefined();
+            expect(customRuleError?.severity).toBe(2);
+            expect(customRuleError?.message).toContain('Imports from "settings" are not allowed in cards.');
+        });
+        it('should allow valid extension point imports', async () => {
+            const code = `
+        import { useCrmProperties } from '@hubspot/ui-extensions/crm/hooks';
+      `;
+            const messages = await lintCode(code, 'src/app/cards/MyCard.tsx', '/path/to/project/src/app/cards');
+            const customRuleError = messages.find((m) => m.ruleId ===
+                '@hubspot/ui-extensions/no-invalid-extension-point-imports');
+            expect(customRuleError).toBeUndefined();
+        });
+    });
+    describe('custom no-native-http rule', () => {
+        it('should error when using native fetch()', async () => {
+            const code = `
+        function getData() {
+          return fetch('https://api.example.com');
+        }
+      `;
+            const messages = await lintCode(code, 'test.js');
+            const customRuleError = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-native-http');
+            expect(customRuleError).toBeDefined();
+            expect(customRuleError?.severity).toBe(2);
+            expect(customRuleError?.message).toContain('Native fetch()');
+        });
+        it('should allow hubspot.fetch()', async () => {
+            const code = `
+        function getData() {
+          return hubspot.fetch('https://api.example.com');
+        }
+      `;
+            const messages = await lintCode(code, 'test.js');
+            const customRuleError = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-native-http');
+            expect(customRuleError).toBeUndefined();
+        });
+    });
+    describe('custom no-browser-dialogs rule', () => {
+        it('should error when using native alert()', async () => {
+            const code = `
+        function showMessage() {
+          alert('Hello World');
+        }
+      `;
+            const messages = await lintCode(code, 'test.js');
+            const customRuleError = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-browser-dialogs');
+            expect(customRuleError).toBeDefined();
+            expect(customRuleError?.severity).toBe(2);
+            expect(customRuleError?.message).toContain('alert');
+        });
+        it('should allow custom alert functions', async () => {
+            const code = `
+        function showMessage() {
+          const alert = (msg) => actions.addAlert(msg);
+          alert('Hello World');
+        }
+      `;
+            const messages = await lintCode(code, 'test.js');
+            const customRuleError = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-browser-dialogs');
+            expect(customRuleError).toBeUndefined();
+        });
+    });
+    describe('custom no-experimental-imports rule', () => {
+        it('should warn when importing from experimental path', async () => {
+            const code = `
+        import { Grid } from '@hubspot/ui-extensions/experimental';
+      `;
+            const messages = await lintCode(code, 'src/app/cards/Component.tsx', '/path/to/project');
+            const customRuleWarning = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-experimental-imports');
+            expect(customRuleWarning).toBeDefined();
+            expect(customRuleWarning?.severity).toBe(1);
+            expect(customRuleWarning?.message).toContain('experimental');
+        });
+        it('should allow stable @hubspot/ui-extensions imports', async () => {
+            const code = `
+        import { Text, Button } from '@hubspot/ui-extensions';
+      `;
+            const messages = await lintCode(code, 'src/app/cards/Component.tsx', '/path/to/project');
+            const customRuleWarning = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-experimental-imports');
+            expect(customRuleWarning).toBeUndefined();
+        });
+    });
+    describe('custom no-console rule', () => {
+        it('should warn when using console.log()', async () => {
+            const code = `
+        function debug() {
+          console.log('Debug message');
+        }
+      `;
+            const messages = await lintCode(code, 'test.js');
+            const customRuleWarning = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-console');
+            expect(customRuleWarning).toBeDefined();
+            expect(customRuleWarning?.severity).toBe(1);
+            expect(customRuleWarning?.message).toContain('console.log()');
+        });
+        it('should allow custom log functions', async () => {
+            const code = `
+        function debug() {
+          const log = (msg) => logger.debug(msg);
+          log('Debug message');
+        }
+      `;
+            const messages = await lintCode(code, 'test.js');
+            const customRuleWarning = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-console');
+            expect(customRuleWarning).toBeUndefined();
+        });
+    });
+    describe('custom no-dom-access rule', () => {
+        it('should error when accessing document', async () => {
+            const code = `
+        function getElement() {
+          return document.querySelector('.test');
+        }
+      `;
+            const messages = await lintCode(code, 'test.js');
+            const customRuleError = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-dom-access');
+            expect(customRuleError).toBeDefined();
+            expect(customRuleError?.severity).toBe(2);
+            expect(customRuleError?.message).toContain('document');
+        });
+        it('should allow local document variable', async () => {
+            const code = `
+        function parse() {
+          const document = { body: null };
+          return document.body;
+        }
+      `;
+            const messages = await lintCode(code, 'test.js');
+            const customRuleError = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-dom-access');
+            expect(customRuleError).toBeUndefined();
+        });
+    });
+    describe('custom no-parent-imports rule', () => {
+        it('should error when importing from outside extension point directory', async () => {
+            const code = `
+        import { util } from '../shared/utils';
+      `;
+            const messages = await lintCode(code, 'src/app/cards/Component.tsx', '/path/to/project');
+            const customRuleError = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-parent-imports');
+            expect(customRuleError).toBeDefined();
+            expect(customRuleError?.severity).toBe(2);
+            expect(customRuleError?.message).toContain('Imports from outside "cards" will fail at build time');
+            expect(customRuleError?.message).toContain('npm workspaces');
+        });
+        it('should allow imports within extension point directory', async () => {
+            const code = `
+        import { util } from './utils';
+        import { Component } from '../components/Button';
+      `;
+            const messages = await lintCode(code, 'src/app/cards/nested/Component.tsx', '/path/to/project');
+            const customRuleError = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-parent-imports');
+            expect(customRuleError).toBeUndefined();
+        });
+        it('should allow npm package imports', async () => {
+            const code = `
+        import { useState } from 'react';
+        import { Button } from '@hubspot/ui-extensions';
+      `;
+            const messages = await lintCode(code, 'src/app/cards/Component.tsx', '/path/to/project');
+            const customRuleError = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-parent-imports');
+            expect(customRuleError).toBeUndefined();
+        });
+    });
+    describe('custom no-browser-storage rule', () => {
+        it('should error when accessing localStorage', async () => {
+            const code = `
+        function saveData() {
+          localStorage.setItem('key', 'value');
+        }
+      `;
+            const messages = await lintCode(code, 'test.js');
+            const customRuleError = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-browser-storage');
+            expect(customRuleError).toBeDefined();
+            expect(customRuleError?.severity).toBe(2);
+            expect(customRuleError?.message).toContain('localStorage');
+        });
+        it('should error when accessing sessionStorage', async () => {
+            const code = `
+        function loadData() {
+          return sessionStorage.getItem('key');
+        }
+      `;
+            const messages = await lintCode(code, 'test.js');
+            const customRuleError = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-browser-storage');
+            expect(customRuleError).toBeDefined();
+            expect(customRuleError?.severity).toBe(2);
+            expect(customRuleError?.message).toContain('sessionStorage');
+        });
+        it('should allow local localStorage variable', async () => {
+            const code = `
+        function saveData() {
+          const localStorage = { setItem: () => {} };
+          localStorage.setItem('key', 'value');
+        }
+      `;
+            const messages = await lintCode(code, 'test.js');
+            const customRuleError = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-browser-storage');
+            expect(customRuleError).toBeUndefined();
+        });
+        it('should allow local sessionStorage variable', async () => {
+            const code = `
+        function loadData() {
+          const sessionStorage = { getItem: () => null };
+          return sessionStorage.getItem('key');
+        }
+      `;
+            const messages = await lintCode(code, 'test.js');
+            const customRuleError = messages.find((m) => m.ruleId === '@hubspot/ui-extensions/no-browser-storage');
+            expect(customRuleError).toBeUndefined();
+        });
+    });
+});

package/dist/__tests__/rules/no-browser-dialogs.spec.d.ts

@@ -0,0 +1 @@
+export {};