# 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

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

## Usage

Add the plugin to your Webpack configuration:

```js
// 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:

```jsx
// 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:

```bash
# 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](https://vitest.dev/), 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