Migrating from eslint-plugin-react

import eslintReact from "@eslint-react/eslint-plugin";
import eslintReactKit from "@eslint-react/kit";
import { defineConfig } from "eslint/config";
import {
  booleanPropNaming,
  checkedRequiresOnchangeOrReadonly,
  forbidComponentProps,
  forbidDomProps,
  forbidElements,
  functionComponentDefinition,
  jsxBooleanValue,
  jsxFragments,
  jsxHandlerNames,
  jsxMaxDepth,
  jsxNoBind,
  jsxNoDuplicateProps,
  jsxNoLiterals,
  jsxPascalCase,
  jsxPropsNoSpreadMulti,
  jsxPropsNoSpreading,
  noAdjacentInlineElements,
  noMultiComp,
} from "@examples/react-dom-with-custom-rules";

export default defineConfig([
  {
    files: ["**/*.{ts,tsx}"],
    extends: [
      eslintReact.configs["recommended-typescript"],
      eslintReactKit()
        .use(booleanPropNaming, { rule: "^(is|has|should)[A-Z]([A-Za-z0-9]?)+" })
        .use(checkedRequiresOnchangeOrReadonly)
        .use(forbidComponentProps, { forbidden: ["className", "style"] })
        .use(forbidDomProps, { forbidden: ["style", "className"] })
        .use(jsxFragments)
        .use(jsxHandlerNames, { eventHandlerPrefix: "handle", eventHandlerPropPrefix: "on" })
        .use(jsxMaxDepth, { max: 3 })
        .use(jsxNoDuplicateProps)
        .use(jsxNoLiterals, { noStrings: true, allowedStrings: ["allowed"] })
        .use(jsxPascalCase)
        .use(jsxPropsNoSpreadMulti)
        .use(noAdjacentInlineElements)
        .use(noMultiComp)
        .use(forbidElements, {
          forbidden: new Map([
            ["button", "Use <Button> from '@/components/ui' instead."],
            ["input", "Use <Input> from '@/components/ui' instead."],
          ]),
        })
        .use(functionComponentDefinition)
        .use(jsxBooleanValue)
        .use(jsxNoBind)
        .use(jsxPropsNoSpreading)
        .getConfig(),
    ],
  },
]);

import { type RuleFunction, merge } from "@eslint-react/kit";
import { ESLintUtils } from "@typescript-eslint/utils";
import ts from "typescript";

// ── Options ───────────────────────────────────────────
export type BooleanPropNamingOptions = {
  /** A regular expression that boolean prop names must match. */
  rule?: string;
};

// ── Constants ─────────────────────────────────────────
const DEFAULT_RULE = "^(is|has|should)[A-Z]([A-Za-z0-9]?)+";
const BOOLEAN_LIKE = ts.TypeFlags.Boolean | ts.TypeFlags.BooleanLiteral;

// ── Type Utils ────────────────────────────────────────
const flattenTypes = (type: ts.Type): ts.Type[] =>
  type.isUnion() ? type.types.flatMap(flattenTypes) : [type];

const isBooleanType = (type: ts.Type): boolean =>
  flattenTypes(type).some(t => !!(t.getFlags() & BOOLEAN_LIKE));

// ── Rule ──────────────────────────────────────────────
/** Enforce boolean prop naming convention. */
export function booleanPropNaming(
  options?: BooleanPropNamingOptions,
): RuleFunction {
  const { rule = DEFAULT_RULE } = options ?? {};
  const regex = new RegExp(rule);

  // ── Listener ────────────────────────────────────────
  return (context, { collect }) => {
    const srv = ESLintUtils.getParserServices(context, false); // parser services
    const chk = srv.program.getTypeChecker();                  // type checker
    const { query, visitor } = collect.components(context);    // component utils

    return merge(visitor, {
      "Program:exit"(prog) {
        const comps = query.all(prog);

        // ── Each component ────────────────────────────
        for (const comp of comps) {
          const [propsParam] = comp.node.params;
          if (propsParam == null) continue; // no props

          const tsNode = srv.esTreeNodeToTSNodeMap.get(propsParam);
          const propsType = chk.getTypeAtLocation(tsNode);
          const declaredProps = propsType.getProperties();

          // ── Each prop ───────────────────────────────
          for (const prop of declaredProps) {
            const propType = chk.getTypeOfSymbolAtLocation(prop, tsNode);
            if (!isBooleanType(propType)) continue; // non-boolean
            if (regex.test(prop.name))    continue; // valid name

            const decls = prop.getDeclarations();
            if (decls == null)            continue; // no declarations

            const [decl] = decls;
            if (decl == null)             continue; // empty

            const declNode = srv.tsNodeToESTreeNodeMap.get(decl);
            if (declNode == null)         continue; // no estree node

            const node = "key" in declNode ? declNode.key : declNode;

            context.report({
              data: { name: prop.name, rule },
              message: `Boolean prop "{{name}}" should match "{{rule}}".`,
              node,
            });
          }
        }
      },
    });
  };
}

import type { RuleFunction } from "@eslint-react/kit";

/** Require `onChange` or `readOnly` when using `checked` on `<input>`. */
export function checkedRequiresOnchangeOrReadonly(): RuleFunction {
  return (context) => ({
    JSXOpeningElement(node) {
      const name = node.name.type === "JSXIdentifier" ? node.name.name : null;
      if (name !== "input") return;
      const attrs = new Set<string>();
      for (const attr of node.attributes) {
        if (attr.type === "JSXAttribute" && attr.name.type === "JSXIdentifier") {
          attrs.add(attr.name.name);
        }
      }
      if (!attrs.has("checked")) return;
      if (!attrs.has("onChange") && !attrs.has("readOnly")) {
        context.report({
          node,
          message: "`checked` requires `onChange` or `readOnly`.",
        });
      }
    },
  });
}

import type { RuleFunction } from "@eslint-react/kit";

/** Options for {@link forbidComponentProps}. */
export type ForbidComponentPropsOptions = {
  /** Prop names that are not allowed on React components. */
  forbidden: string[];
};

/** Forbid certain props on React components (not DOM elements). */
export function forbidComponentProps(options: ForbidComponentPropsOptions): RuleFunction {
  const { forbidden } = options;
  return (context) => ({
    JSXAttribute(node) {
      const propName = node.name.type === "JSXIdentifier" ? node.name.name : null;
      if (propName == null || !forbidden.includes(propName)) return;
      const parent = node.parent;
      if (parent?.type !== "JSXOpeningElement") return;
      const elemName = parent.name.type === "JSXIdentifier" ? parent.name.name : null;
      // Only report on components (PascalCase names), not DOM elements
      if (elemName == null || elemName[0] !== elemName[0]?.toUpperCase()) return;
      context.report({
        node,
        message: `Prop "${propName}" is forbidden on components.`,
      });
    },
  });
}

import type { RuleFunction } from "@eslint-react/kit";

/** Options for {@link forbidDomProps}. */
export type ForbidDomPropsOptions = {
  /** Prop names that are not allowed on DOM elements. */
  forbidden: string[];
};

/** Forbid certain props on DOM elements (not React components). */
export function forbidDomProps(options: ForbidDomPropsOptions): RuleFunction {
  const { forbidden } = options;
  return (context) => ({
    JSXAttribute(node) {
      const propName = node.name.type === "JSXIdentifier" ? node.name.name : null;
      if (propName == null || !forbidden.includes(propName)) return;
      const parent = node.parent;
      if (parent?.type !== "JSXOpeningElement") return;
      const elemName = parent.name.type === "JSXIdentifier" ? parent.name.name : null;
      // Only report on DOM elements (lowercase names), not components
      if (elemName == null || elemName[0] !== elemName[0]?.toLowerCase()) return;
      context.report({
        node,
        message: `Prop "${propName}" is forbidden on DOM elements.`,
      });
    },
  });
}

import type { RuleFunction } from "@eslint-react/kit";

/** Options for {@link forbidElements}. */
export type ForbidElementsOptions = {
  /** A map from element name to the error message reported when that element is used. */
  forbidden: Map<string, string>;
};

/** Forbid specific JSX elements. */
export function forbidElements(options: ForbidElementsOptions): RuleFunction {
  const { forbidden } = options;
  return (context) => ({
    JSXOpeningElement(node) {
      const name = node.name.type === "JSXIdentifier" ? node.name.name : null;
      if (name != null && forbidden.has(name)) {
        context.report({ node, message: forbidden.get(name)! });
      }
    },
  });
}

import type { RuleFunction } from "@eslint-react/kit";
import { merge } from "@eslint-react/kit";

/** Enforce arrow function definitions for function components. */
export function functionComponentDefinition(): RuleFunction {
  return (context, { collect, hint }) => {
    const { query, visitor } = collect.components(context, {
      hint: hint.component.Default & ~hint.component.DoNotIncludeFunctionDefinedAsObjectMethod,
    });
    return merge(
      visitor,
      {
        "Program:exit"(program) {
          for (const { node } of query.all(program)) {
            if (node.type === "ArrowFunctionExpression") continue;
            context.report({
              node,
              message: "Function components must be defined with arrow functions.",
              suggest: [
                {
                  desc: "Convert to arrow function.",
                  fix(fixer) {
                    const src = context.sourceCode;
                    if (node.generator) return null;
                    const prefix = node.async ? "async " : "";
                    const typeParams = node.typeParameters ? src.getText(node.typeParameters) : "";
                    const params = `(${node.params.map((p) => src.getText(p)).join(", ")})`;
                    const returnType = node.returnType ? src.getText(node.returnType) : "";
                    const body = src.getText(node.body);

                    // function Foo(params) { ... } -> const Foo = (params) => { ... };
                    if (node.type === "FunctionDeclaration" && node.id) {
                      // dprint-ignore
                      return fixer.replaceText(node, `const ${node.id.name} = ${prefix}${typeParams}${params}${returnType} => ${body};`);
                    }

                    // const Foo = function(params) { ... } -> const Foo = (params) => { ... }
                    if (node.type === "FunctionExpression" && node.parent.type === "VariableDeclarator") {
                      // dprint-ignore
                      return fixer.replaceText(node, `${prefix}${typeParams}${params}${returnType} => ${body}`);
                    }

                    // { Foo(params) { ... } } -> { Foo: (params) => { ... } }
                    if (node.type === "FunctionExpression" && node.parent.type === "Property") {
                      // dprint-ignore
                      return fixer.replaceText(node.parent, `${src.getText(node.parent.key)}: ${prefix}${typeParams}${params}${returnType} => ${body}`);
                    }

                    return null;
                  },
                },
              ],
            });
          }
        },
      },
    );
  };
}

import type { RuleFunction } from "@eslint-react/kit";

/** Enforce shorthand for boolean JSX attributes. */
export function jsxBooleanValue(): RuleFunction {
  return (context) => ({
    JSXAttribute(node) {
      const { value } = node;
      if (value?.type !== "JSXExpressionContainer") return;
      if (value.expression.type !== "Literal" || value.expression.value !== true) return;
      context.report({
        node,
        message: "Omit the value for boolean attributes.",
        fix: (fixer) => fixer.removeRange([node.name.range[1], value.range[1]]),
      });
    },
  });
}

import type { RuleFunction } from "@eslint-react/kit";
import type { TSESTree } from "@typescript-eslint/types";

/** Options for {@link jsxFragments}. */
export type JsxsFragmentsOptions = {
  /** The mode to enforce: "syntax" (default, shorthand) or "element" (standard form). */
  mode?: "syntax" | "element";
};

/** Enforce shorthand or standard form for React fragments. */
export function jsxFragments(options: JsxsFragmentsOptions = {}): RuleFunction {
  const { mode = "syntax" } = options;
  return (context) => {
    function reportSyntaxPreferred(node: TSESTree.JSXOpeningElement, pattern: "React.Fragment" | "Fragment") {
      const hasAttributes = node.attributes.length > 0;
      if (hasAttributes) return;
      context.report({
        node,
        message: `Use shorthand fragment syntax '<>...</>' instead of '<${pattern}>...</${pattern}'.`,
        fix(fixer) {
          const closing = node.parent?.closingElement;
          if (!closing) return null;
          return [fixer.replaceText(node, "<>"), fixer.replaceText(closing, "</>")];
        },
      });
    }

    return {
      JSXOpeningElement(node) {
        const name = node.name;

        // Handle standalone <Fragment> (JSXIdentifier)
        if (name.type === "JSXIdentifier" && name.name === "Fragment") {
          if (mode === "syntax") {
            reportSyntaxPreferred(node, "Fragment");
          }
          return;
        }

        // Handle <React.Fragment> (JSXMemberExpression)
        if (name.type !== "JSXMemberExpression") return;
        if (name.object.type !== "JSXIdentifier" || name.object.name !== "React") return;
        if (name.property.type !== "JSXIdentifier" || name.property.name !== "Fragment") return;

        if (mode === "syntax") {
          reportSyntaxPreferred(node, "React.Fragment");
        }
      },
      JSXFragment(node) {
        if (mode === "element") {
          context.report({
            node,
            message: "Use '<React.Fragment>...</React.Fragment>' instead of shorthand '<>...</>'.",
            fix(fixer) {
              return [
                fixer.replaceText(node.openingFragment, "<React.Fragment>"),
                fixer.replaceText(node.closingFragment, "</React.Fragment>"),
              ];
            },
          });
        }
      },
    };
  };
}

import type { RuleFunction } from "@eslint-react/kit";

/** Options for {@link jsxHandlerNames}. */
export type JsxHandlerNamesOptions = {
  /** Prefix for event handler functions (default: "handle"). */
  eventHandlerPrefix?: string;
  /** Prefix for event handler props (default: "on"). */
  eventHandlerPropPrefix?: string;
  /** Whether to check inline functions (default: false). */
  checkInlineFunction?: boolean;
};

/** Enforce naming convention for JSX event handlers. */
export function jsxHandlerNames(options: JsxHandlerNamesOptions = {}): RuleFunction {
  const {
    eventHandlerPrefix = "handle",
    eventHandlerPropPrefix = "on",
    checkInlineFunction = false,
  } = options;
  const EVENT_HANDLER_REGEX = new RegExp(`^${eventHandlerPropPrefix}[A-Z]`);
  const HANDLER_FUNC_REGEX = new RegExp(`^${eventHandlerPrefix}[A-Z]`);

  return (context) => ({
    JSXAttribute(node) {
      if (node.name.type !== "JSXIdentifier") return;
      const propName = node.name.name;
      if (!EVENT_HANDLER_REGEX.test(propName)) return;

      const value = node.value;
      if (!value) return;

      if (value.type === "JSXExpressionContainer") {
        const expression = value.expression;

        if (expression.type === "Identifier") {
          const handlerName = expression.name;
          if (!HANDLER_FUNC_REGEX.test(handlerName)) {
            context.report({
              node: expression,
              message: `Handler function "${handlerName}" should be named "${eventHandlerPrefix}${
                propName.slice(eventHandlerPropPrefix.length)
              }..."`,
            });
          }
          return;
        }

        if (expression.type === "ArrowFunctionExpression" || expression.type === "FunctionExpression") {
          if (checkInlineFunction) {
            context.report({
              node: expression,
              message:
                `Inline function handlers are not allowed for "${propName}". Extract it to a named "${eventHandlerPrefix}${
                  propName.slice(eventHandlerPropPrefix.length)
                }" function.`,
            });
          }
          return;
        }
      }
    },
  });
}

import type { RuleFunction } from "@eslint-react/kit";

/** Options for {@link jsxMaxDepth}. */
export type JsxMaxDepthOptions = {
  /** Maximum allowed depth for JSX elements. */
  max: number;
};

/** Enforce JSX maximum depth. */
export function jsxMaxDepth(options: JsxMaxDepthOptions): RuleFunction {
  const { max } = options;
  return (context) => ({
    JSXElement(node) {
      let depth = 0;
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      let parent: any = node.parent;
      while (parent) {
        if (parent.type === "JSXElement") {
          depth++;
        }
        parent = parent.parent;
      }
      if (depth > max) {
        context.report({
          node,
          message: `JSX element exceeds maximum depth of ${max} (found ${depth}).`,
        });
      }
    },
  });
}

import type { RuleFunction } from "@eslint-react/kit";

/** Prevent inline functions and `.bind()` in JSX props. */
export function jsxNoBind(): RuleFunction {
  return (context) => ({
    JSXAttribute(node) {
      const value = node.value;
      if (value?.type !== "JSXExpressionContainer") return;
      switch (true) {
        case value.expression.type === "ArrowFunctionExpression":
        case value.expression.type === "FunctionExpression":
          context.report({ node, message: "JSX props should not use inline functions." });
          break;
        case value.expression.type === "CallExpression"
          && value.expression.callee.type === "MemberExpression"
          && value.expression.callee.property.type === "Identifier"
          && value.expression.callee.property.name === "bind":
          context.report({ node, message: "JSX props should not use .bind()." });
          break;
      }
    },
  });
}

import type { RuleFunction } from "@eslint-react/kit";

/** Options for {@link jsxNoDuplicateProps}. */
export type JsxNoDuplicatePropsOptions = {
  /** Whether to ignore case when checking for duplicate props. */
  ignoreCase?: boolean;
};

/** Disallow duplicate properties in JSX. */
export function jsxNoDuplicateProps(options: JsxNoDuplicatePropsOptions = {}): RuleFunction {
  const { ignoreCase = false } = options;
  return (context) => ({
    JSXOpeningElement(node) {
      const seen = new Map<string, string>();
      for (const attr of node.attributes) {
        if (attr.type !== "JSXAttribute") continue;
        if (attr.name.type !== "JSXIdentifier") continue;
        const name = ignoreCase ? attr.name.name.toLowerCase() : attr.name.name;
        if (seen.has(name)) {
          context.report({
            node: attr,
            message: `Duplicate prop "${attr.name.name}" found.`,
          });
        } else {
          seen.set(name, attr.name.name);
        }
      }
    },
  });
}

import type { RuleFunction } from "@eslint-react/kit";

/** Options for {@link jsxNoLiterals}. */
export type JsxNoLiteralsOptions = {
  /** Enforces no string literals used as children, wrapped or unwrapped. */
  noStrings?: boolean;
  /** An array of unique string values that would otherwise warn, but will be ignored. */
  allowedStrings?: string[];
  /** When `true` the rule ignores literals used in props. */
  ignoreProps?: boolean;
};

/** Disallow usage of string literals in JSX. */
export function jsxNoLiterals(options: JsxNoLiteralsOptions = {}): RuleFunction {
  const { noStrings = false, allowedStrings = [], ignoreProps = true } = options;
  const allowedSet = new Set(allowedStrings);
  return (context) => ({
    Literal(node) {
      if (typeof node.value !== "string") return;
      const text = node.value.trim();
      if (text === "" || allowedSet.has(text)) return;

      const parent = node.parent;
      if (!parent) return;

      if (parent.type === "JSXAttribute") {
        if (!ignoreProps) {
          context.report({
            node,
            message: `String literals are not allowed in JSX props. Use {'${text}'} instead.`,
          });
        }
        return;
      }

      if (parent.type === "JSXExpressionContainer") return;

      if (parent.type === "JSXElement" || parent.type === "JSXFragment") {
        if (noStrings) {
          context.report({
            node,
            message: `String literals are not allowed as JSX children.`,
          });
        } else {
          context.report({
            node,
            message: `String literals should be wrapped in JSX expression: {'${text}'}`,
          });
        }
      }
    },
    JSXText(node) {
      const text = node.value.trim();
      if (text === "" || allowedSet.has(text)) return;

      if (noStrings) {
        context.report({
          node,
          message: `String literals are not allowed as JSX children.`,
        });
      } else {
        context.report({
          node,
          message: `String literals should be wrapped in JSX expression: {'${text}'}`,
        });
      }
    },
  });
}

import type { RuleFunction } from "@eslint-react/kit";

/** Options for {@link jsxPascalCase}. */
export type JsxPascalCaseOptions = {
  /** Allow all-uppercase component names like `<XML />`. */
  allowAllCaps?: boolean;
  /** Allow leading underscores in component names like `<_Component />`. */
  allowLeadingUnderscore?: boolean;
};

/** Enforce PascalCase for user-defined JSX components. */
export function jsxPascalCase(options: JsxPascalCaseOptions = {}): RuleFunction {
  const { allowAllCaps = false, allowLeadingUnderscore = false } = options;
  // Check PascalCase: first letter uppercase, rest can be mixed but no underscores
  const pascalCaseRegex = /^[A-Z][a-zA-Z0-9]*$/;
  return (context) => ({
    JSXOpeningElement(node) {
      const name = node.name;
      if (name.type !== "JSXIdentifier") return;

      const componentName = name.name;

      // Check for leading underscore (before lowercase check since "_".toLowerCase() === "_")
      if (componentName.startsWith("_")) {
        if (!allowLeadingUnderscore) {
          context.report({
            node: name,
            message: `Component name "${componentName}" should not start with an underscore.`,
          });
        }
        return;
      }

      // Ignore DOM elements (lowercase first letter)
      const firstChar = componentName[0];
      if (firstChar === undefined) return;
      if (firstChar === firstChar.toLowerCase()) return;

      // Check for all caps
      if (componentName === componentName.toUpperCase()) {
        if (!allowAllCaps) {
          context.report({
            node: name,
            message: `Component name "${componentName}" should use PascalCase, not all uppercase.`,
          });
        }
        return;
      }

      if (!pascalCaseRegex.test(componentName)) {
        context.report({
          node: name,
          message: `Component name "${componentName}" should be in PascalCase.`,
        });
      }
    },
  });
}

import type { RuleFunction } from "@eslint-react/kit";

/** Disallow JSX prop spreading the same identifier multiple times. */
export function jsxPropsNoSpreadMulti(): RuleFunction {
  return (context) => ({
    JSXOpeningElement(node) {
      const seen = new Set<string>();
      for (const attr of node.attributes) {
        if (attr.type !== "JSXSpreadAttribute") continue;

        let spreadKey: string;
        if (attr.argument.type === "Identifier") {
          spreadKey = attr.argument.name;
        } else {
          spreadKey = context.sourceCode.getText(attr.argument);
        }

        if (seen.has(spreadKey)) {
          context.report({
            node: attr,
            message: `Spreading the same expression "${spreadKey}" multiple times is not allowed.`,
          });
        } else {
          seen.add(spreadKey);
        }
      }
    },
  });
}

import type { RuleFunction } from "@eslint-react/kit";

/** Disallow JSX props spreading. */
export function jsxPropsNoSpreading(): RuleFunction {
  return (context) => ({
    JSXSpreadAttribute(node) {
      context.report({
        node,
        message: "Props spreading is not allowed.",
      });
    },
  });
}

import type { RuleFunction } from "@eslint-react/kit";
import type { TSESTree } from "@typescript-eslint/types";

/** Disallow adjacent inline elements not separated by whitespace. */
export function noAdjacentInlineElements(): RuleFunction {
  /** Set of inline HTML elements. */
  const INLINE_ELEMENTS = new Set([
    "a",
    "abbr",
    "acronym",
    "b",
    "bdi",
    "bdo",
    "big",
    "br",
    "cite",
    "code",
    "dfn",
    "em",
    "i",
    "img",
    "input",
    "kbd",
    "label",
    "map",
    "object",
    "q",
    "samp",
    "script",
    "select",
    "small",
    "span",
    "strong",
    "sub",
    "sup",
    "textarea",
    "time",
    "tt",
    "var",
  ]);

  return (context) => ({
    JSXElement(node) {
      const children = node.children;
      for (let i = 0; i < children.length - 1; i++) {
        const current = children[i];
        const next = children[i + 1];

        if (current?.type !== "JSXElement") continue;
        if (current.openingElement.name.type !== "JSXIdentifier") continue;
        const currentName = current.openingElement.name.name;
        if (!INLINE_ELEMENTS.has(currentName)) continue;

        if (next?.type !== "JSXElement") continue;
        if (next.openingElement.name.type !== "JSXIdentifier") continue;
        const nextName = next.openingElement.name.name;
        if (!INLINE_ELEMENTS.has(nextName)) continue;

        context.report({
          node: current,
          message: `Adjacent inline elements "${currentName}" and "${nextName}" should be separated by whitespace.`,
        });
      }
    },
  });
}

import type { RuleFunction } from "@eslint-react/kit";
import { merge } from "@eslint-react/kit";

/** Prevent defining more than one component per file. */
export function noMultiComp(): RuleFunction {
  return (context, { collect }) => {
    const { query, visitor } = collect.components(context);
    return merge(visitor, {
      "Program:exit"(program) {
        const components = query.all(program);
        for (const { node, name } of components.slice(1)) {
          context.report({
            node,
            message: `Declare only one component per file. Found extra component "${name ?? "anonymous"}".`,
          });
        }
      },
    });
  };
}