eslint.config.mjs

import js from '@eslint/js';
import globals from 'globals';
import tseslint from 'typescript-eslint';

import reactHooksPlugin from 'eslint-plugin-react-hooks';
import importPlugin from 'eslint-plugin-import';
import sortDestructureKeysPlugin from 'eslint-plugin-sort-destructure-keys';
import reactPlugin from 'eslint-plugin-react';
import vitestPlugin from '@vitest/eslint-plugin';

// `stream-chat` re-exported the state store until v10 extracted it into its own package, so the
// old specifier still reads as correct and typechecks nowhere CI looks (test files are outside
// `yarn types`). It resolves to `undefined` at runtime — "StateStore is not a constructor".
// `@stream-io/state-store` is the single source for this API; see CLAUDE.md.
const stateStoreFromStreamChat = {
  name: 'stream-chat',
  importNames: [
    'StateStore',
    'MergedStateStore',
    'isPatch',
    'Patch',
    'ValueOrPatch',
    'Handler',
    'Unsubscribe',
    'RemovePreprocessor',
    'Preprocessor',
  ],
  message:
    "`stream-chat` does not export the state store — it lives in `@stream-io/state-store`. Import it from there (a value import from 'stream-chat' resolves to undefined at runtime).",
};

export default tseslint.config(
  {
    ignores: [
      'dist',
      'src/@types',
      '*.{js,ts}',
      '.yarn',
      'examples/*/dist',
      'examples/*/node_modules',
      'examples/*/docs-playwright',
    ],
  },
  {
    name: 'default',
    extends: [
      js.configs.recommended,
      ...tseslint.configs.recommended,
      reactPlugin.configs.flat.recommended,
    ],
    files: ['src/**/*.{js,ts,jsx,tsx}', 'examples/*/src/**/*.{js,ts,jsx,tsx}'],
    languageOptions: {
      ecmaVersion: 2020,
      globals: globals.browser,
    },
    plugins: {
      'react-hooks': reactHooksPlugin,
      import: importPlugin,
      'sort-destructure-keys': sortDestructureKeysPlugin,
    },
    settings: {
      react: {
        version: 'detect',
      },
    },
    rules: {
      camelcase: 'off',
      semi: ['warn', 'always'],
      eqeqeq: ['error', 'smart'],
      'array-callback-return': 'error',
      'arrow-body-style': 'error',
      'comma-dangle': 'off',
      'default-case': 'error',
      'jsx-quotes': ['error', 'prefer-single'],
      'linebreak-style': ['error', 'unix'],
      'no-console': 'off',
      'no-mixed-spaces-and-tabs': 'warn',
      'no-self-compare': 'error',
      'no-underscore-dangle': [
        'error',
        { allow: ['_internalState'], allowAfterThis: true },
      ],
      'no-use-before-define': 'off',
      'no-useless-concat': 'error',
      'no-var': 'error',
      'no-script-url': 'error',
      'no-continue': 'off',
      'object-shorthand': 'warn',
      'prefer-const': 'warn',
      'require-await': 'error',
      'sort-destructure-keys/sort-destructure-keys': ['error', { caseSensitive: false }],
      'sort-imports': [
        'error',
        {
          allowSeparatedGroups: true,
          ignoreCase: true,
          ignoreDeclarationSort: true,
          ignoreMemberSort: false,
          memberSyntaxSortOrder: ['none', 'all', 'multiple', 'single'],
        },
      ],
      'sort-keys': ['error', 'asc', { caseSensitive: false, minKeys: 2, natural: false }],
      'valid-typeof': 'error',
      'max-classes-per-file': 'off',
      'no-unused-expressions': 'off',
      'import/prefer-default-export': 'off',
      'import/extensions': 'off',
      'import/no-extraneous-dependencies': [
        'error',
        {
          devDependencies: true, // TODO: set to false once React is in the dependencies (not devDependencies)
          optionalDependencies: false,
          peerDependencies: false,
        },
      ],
      'no-unused-vars': 'off',
      '@typescript-eslint/no-unused-vars': [
        'warn',
        { ignoreRestSiblings: false, caughtErrors: 'none' },
      ],
      '@typescript-eslint/no-unsafe-function-type': 'error',
      '@typescript-eslint/consistent-type-imports': 'error',
      '@typescript-eslint/no-wrapper-object-types': 'error',
      '@typescript-eslint/no-non-null-assertion': 'error',
      'no-empty-function': 'off',
      '@typescript-eslint/no-empty-function': 'warn',
      '@typescript-eslint/no-require-imports': 'off', // TODO: remove this rule once all files are .mjs (and require is not used)
      'react/prop-types': 'off',
      'react/react-in-jsx-scope': 'off',
      'react/display-name': 'warn',
      'react/jsx-sort-props': [
        'error',
        {
          callbacksLast: false,
          ignoreCase: true,
          noSortAlphabetically: false,
          reservedFirst: false,
          shorthandFirst: false,
          shorthandLast: false,
        },
      ],
      'react-hooks/rules-of-hooks': 'warn',
      'react-hooks/exhaustive-deps': 'error',
    },
  },
  {
    // Forbid patterns that silently break on React 17 or 18. Approved alternatives:
    // - useId → src/utils/useStableId.ts
    // - useSyncExternalStore → use-sync-external-store/shim
    // - useEffectEvent, use() → not allowed; SDK supports React 17+.
    // - ref as a regular prop → wrap the component with React.forwardRef
    name: 'react-compat',
    files: ['src/**/*.{ts,tsx}'],
    ignores: [
      'src/components/UtilityComponents/useStableId.ts',
      'src/**/__tests__/**',
      'src/mock-builders/**',
    ],
    rules: {
      'no-restricted-imports': [
        'error',
        {
          paths: [
            {
              name: 'react',
              importNames: ['useId', 'useSyncExternalStore', 'useEffectEvent', 'use'],
              message:
                'React 18+/19-only API. Use useStableId from src/utils/useStableId, useSyncExternalStore from use-sync-external-store/shim. useEffectEvent and use() are not allowed: SDK supports React 17+.',
            },
            stateStoreFromStreamChat,
          ],
        },
      ],
      'no-restricted-syntax': [
        'error',
        {
          selector:
            "MemberExpression[object.name='React'][property.name=/^(useId|useSyncExternalStore|useEffectEvent|use)$/]",
          message:
            'React 18+/19-only API. Use useStableId / use-sync-external-store/shim instead of React.<api>.',
        },
        {
          selector: "TSPropertySignature[key.name='ref']",
          message:
            '`ref` declared as a regular prop. React 17 and 18 only deliver `ref` to components wrapped in `React.forwardRef` — declare the component with `forwardRef` instead of putting `ref` in the prop type.',
        },
        {
          selector:
            ":matches(FunctionDeclaration, FunctionExpression, ArrowFunctionExpression) > ObjectPattern > Property[key.name='ref']",
          message:
            '`ref` destructured from props. React 17 and 18 only deliver `ref` to components wrapped in `React.forwardRef` — use `React.forwardRef((props, ref) => …)` and take `ref` as the second parameter instead.',
        },
      ],
    },
  },
  {
    // The `react-compat` block above ignores tests, but the state store specifier is wrong
    // everywhere — and a test is where the wrong one actually reached CI.
    name: 'state-store-single-source',
    files: ['src/**/__tests__/**', 'src/mock-builders/**'],
    rules: {
      'no-restricted-imports': ['error', { paths: [stateStoreFromStreamChat] }],
    },
  },
  {
    name: 'vitest',
    files: ['src/**/__tests__/**', 'src/mock-builders/**'],
    plugins: { vitest: vitestPlugin },
    languageOptions: {
      globals: vitestPlugin.environments.env.globals,
    },
    rules: {
      'vitest/expect-expect': 'off',
      'vitest/no-conditional-expect': 'off',
      'vitest/prefer-inline-snapshots': 'off',
      'vitest/prefer-lowercase-title': 'off',
      'vitest/prefer-expect-assertions': 'off',
      'vitest/no-hooks': 'off',
      'vitest/prefer-spy-on': 'warn',
      '@typescript-eslint/no-empty-function': 'off', // explicitly disable for tests
      '@typescript-eslint/no-explicit-any': 'off', // test mocks frequently need any
      '@typescript-eslint/no-non-null-assertion': 'off', // DOM queries in tests commonly use !
      '@typescript-eslint/consistent-type-imports': [
        'error',
        { disallowTypeAnnotations: false },
      ], // allow typeof import() in vi.mock importOriginal
    },
  },
  {
    // Example apps inherit the SDK's plugins + recommended rules but relax
    // the cosmetic style rules that don't add value in demo code. Real bug
    // patterns (react-hooks deps, no-unknown-property for SVG, undeclared
    // imports, etc.) stay on.
    name: 'examples',
    files: ['examples/*/src/**/*.{js,ts,jsx,tsx}'],
    rules: {
      'sort-keys': 'off',
      'sort-destructure-keys/sort-destructure-keys': 'off',
      'react/jsx-sort-props': 'off',
      '@typescript-eslint/no-non-null-assertion': 'off',
    },
  },
);