@builder.io/webpack-plugin-jsx-loc

webpack-plugin-jsx-loc

A Webpack plugin that adds data-loc attributes to JSX elements, containing the file path and line number where the element is defined. This is useful for debugging, component tracking, and analytics.

Installation

npm install --save-dev webpack-plugin-jsx-loc
# or
yarn add --dev webpack-plugin-jsx-loc

Usage

Add the plugin to your Webpack configuration:

// webpack.config.js
const { JsxLocPlugin } = require('@builder.io/webpack-plugin-jsx-loc');

module.exports = {
  // ... other webpack config
  plugins: [
    new JsxLocPlugin({
      // Optional: specify custom include/exclude patterns
      // include: [/src\/components/],
      // exclude: [/node_modules/, /test/]
    })
  ]
};

Options

• include: RegExp or array of RegExp patterns to include specific files (optional)
• exclude: RegExp or array of RegExp patterns to exclude specific files (optional, defaults to /node_modules/)

How It Works

The plugin adds a data-loc attribute to JSX elements that contains the relative file path and line number:

// Input
<Button onClick={handleClick}>Click me</Button>

// Output
<Button data-loc="src/components/MyComponent.tsx:42" onClick={handleClick}>Click me</Button>

This allows you to identify where components are defined when inspecting the DOM.

Complex Component Support

The plugin handles a variety of JSX patterns:

• Regular JSX elements with attributes
• Member expressions (e.g., <Namespace.Component />)
• Namespaced elements (e.g., <svg:path />)
• JSX inside decorators and complex class components
• Components with TypeScript interfaces and typing
• CSS-in-JS libraries (emotion, styled-components)
• Components with spread attributes

React Fragments are intentionally skipped and won't receive a data-loc attribute:

• <React.Fragment> elements
• Shorthand fragment syntax <>
• <Fragment> elements

Testing the Plugin

This package includes comprehensive tests and manual testing scripts:

# Run the automated tests
npm test

# Run tests in watch mode
npm run test:watch

# Update snapshots if code changes intentionally 
npm test -- -u

# Test with a JSX file fixture
npm run test:jsx

# Test with a TSX file fixture
npm run test:tsx

Tests are powered by Vitest, a fast test runner built on top of Vite.

The test suite uses real fixtures to verify the plugin's behavior with a variety of components:

• Simple components
• Components with fragments
• Complex components with decorators and nested JSX
• Components using CSS-in-JS libraries
• Components with TypeScript interfaces and typing
• Real-world complex components with hundreds of lines of code and multiple levels of nesting

Both unit tests and integration tests ensure that the plugin correctly adds data-loc attributes even to highly complex components with nested structures, decorators, CSS-in-JS properties, and other challenging patterns.

Tests include both assertions and inline snapshots that precisely verify the transformation output to catch any regressions or unexpected changes in how JSX is processed.

The test scripts generate output in src/__tests__/output/ where you can inspect the transformation results.

Notes

• Only works with .jsx and .tsx files
• Skips React.Fragment and Fragment elements
• Preserves source maps
• Handles complex JSX patterns safely with error recovery
• Supports modern JavaScript syntax including:
  • Class features (decorators, private properties, static blocks)
  • Modern JS features (dynamic imports, optional chaining, nullish coalescing)
  • TypeScript syntax
  • Top-level await, numeric separators, BigInt and other recent additions