JSX AST Utilities

Common errors

• TypeError: Cannot read properties of undefined (reading 'attributes')

  cause This error occurs when attempting to access the `attributes` property on an AST node that is not a `JSXOpeningElement`. The `attributes` property is specific to JSX opening tags.
  fix Before accessing `node.attributes` or passing a node to `jsx-ast-utils` functions expecting JSX attributes, ensure that `node.type === 'JSXOpeningElement'` (or a similar check for relevant JSX node types).

• ReferenceError: require is not defined in ES module scope

  cause This typically happens when you are using CommonJS `require()` syntax within an ECMAScript module (ESM) environment (e.g., in a Node.js project with `"type": "module"` in `package.json` or in a modern browser context).
  fix Switch to ESM import syntax: `import { hasProp } from 'jsx-ast-utils';` for named exports.

• TypeError: hasProp is not a function

  cause This error often indicates an incorrect import or destructuring when using CommonJS. Common mistakes include `require('jsx-ast-utils')` without subsequently accessing `.hasProp`, or attempting `require('jsx-ast-utils/hasProp')` assuming a default export from a subpath.
  fix For CommonJS, ensure you are correctly destructuring the named export: `const { hasProp } = require('jsx-ast-utils');`.

Warnings

• breaking In `v2.0.0`, the internal `propName` utility (and consequently functions like `getProp`) was changed to always return a value, where previously it might have returned `undefined` or thrown an error for certain cases. If your code relied on this previous behavior, it constitutes a breaking change.
  Fix: Review any code that interacts with `getProp` or related utilities to ensure it correctly handles the guaranteed return of a value, even if the prop is not found or malformed. Adjust checks from `if (!prop)` to `if (prop === undefined)` if strict non-existence handling is needed.
• gotcha The `hasProp`, `hasAnyProp`, and `hasEveryProp` utilities default `spreadStrict` to `true`. This means if a prop is supplied via a JSX spread attribute (`{...props}`), the utility will report that the specific prop does NOT exist.
  Fix: To correctly check for props that might be included through spread attributes, explicitly set `spreadStrict: false` in the options object: `hasProp(attributes, 'myProp', { spreadStrict: false })`.
• gotcha The `hasProp`, `hasAnyProp`, and `hasEveryProp` utilities default `ignoreCase` to `true`. This means they will find a prop like 'onClick' if you search for 'onclick'.
  Fix: If strict case-sensitive matching is required for a prop, you must implement a manual check. This can involve iterating through the `node.attributes` array and performing a case-sensitive comparison on `attribute.name.name`.
• breaking Support for TypeScript AST node types was officially added in `v2.1.0`. Older versions might not correctly parse or analyze TSX/TypeScript-specific AST nodes, leading to incorrect results or runtime errors when processing TypeScript codebases.
  Fix: Upgrade to `jsx-ast-utils@^2.1.0` or newer if working with TypeScript or TSX files to ensure proper AST node handling and prevent unexpected behavior.

Install

• npm install jsx-ast-utils npm
• yarn add jsx-ast-utils yarn
• pnpm add jsx-ast-utils pnpm

Imports

• hasProp
  wrong:

  const hasProp = require('jsx-ast-utils'); // Missing .hasProp after require

  correct:

  import { hasProp } from 'jsx-ast-utils';

  Primary ESM named import for checking prop existence. For CommonJS, use `const { hasProp } = require('jsx-ast-utils');`
• getProp
  wrong:

  const getProp = require('jsx-ast-utils/getProp'); // Direct file imports are discouraged and may break

  correct:

  import { getProp } from 'jsx-ast-utils';

  Retrieves the full JSXAttribute node or `undefined`. Use named import for both ESM and CommonJS.
• hasAnyProp
  wrong:

  import hasAnyProp from 'jsx-ast-utils'; // No default export from the main package

  correct:

  import { hasAnyProp } from 'jsx-ast-utils';

  Checks if any of the provided props exist on a JSX element. Always use named imports for top-level utilities.

Quickstart

Demonstrates how to use `hasProp` within a simplified ESLint-like visitor function to check for prop existence on JSX elements, including handling spread attributes and case insensitivity.

import { hasProp } from 'jsx-ast-utils';

// This example mimics an ESLint rule structure to demonstrate usage.
// In a real ESLint rule, `context` and `node` would be provided by ESLint.
const mockContext = {
  report: ({ node, message }) => console.log(`Report at node ${node.type}: ${message}`)
};

const mockJSXOpeningElementNode = {
  type: 'JSXOpeningElement',
  attributes: [
    { type: 'JSXAttribute', name: { type: 'JSXIdentifier', name: 'id' }, value: null },
    { type: 'JSXAttribute', name: { type: 'JSXIdentifier', name: 'className' }, value: null },
    { type: 'JSXSpreadAttribute', argument: { type: 'Identifier', name: 'props' } }
  ]
};

// Example usage within a mock ESLint rule visitor
function JSXOpeningElementVisitor(node, context) {
  const hasIdProp = hasProp(node.attributes, 'id');
  const hasOnChange = hasProp(node.attributes, 'onChange', { spreadStrict: false }); // Look within spreads
  const hasDataAttr = hasProp(node.attributes, 'data-testId', { ignoreCase: true }); // Case-insensitive search

  if (!hasIdProp) {
    context.report({ node, message: `JSX element is missing 'id' prop.` });
  }

  if (hasOnChange) {
    context.report({ node, message: `JSX element has an 'onChange' prop, which might be a concern.` });
  }

  if (hasDataAttr) {
    context.report({ node, message: `JSX element has a data-testid attribute.` });
  }
}

// Simulate ESLint calling the visitor
JSXOpeningElementVisitor(mockJSXOpeningElementNode, mockContext);