react-data-attributes-plugin

Automatically add file and line number data attributes to JSX elements for easier debugging and development

A universal plugin that automatically injects data attributes into your JSX elements, making it easy to trace DOM elements back to their source code. Perfect for debugging, testing, and development tools.

Supports: Vite ⚡ | Rollup 📦 | Webpack 🔧 | Esbuild 🚀

✨ Features

• 🔍 Automatic attribute injection - No manual work required
• 📍 File location tracking - Know exactly where each element came from
• 🎯 Selective attributes - Choose which attributes to include
• ⚡ Zero runtime overhead - Build-time transformation only
• 🔧 TypeScript support - Works seamlessly with TypeScript
• 🎨 Customizable - Configure which attributes to add

📦 Installation

npm install --save-dev react-data-attributes-plugin @babel/core

pnpm add -D react-data-attributes-plugin @babel/core

yarn add -D react-data-attributes-plugin @babel/core

Note: @babel/core is required as a peer dependency. Make sure to install it.

🚀 Quick Start

Vite

// vite.config.js
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import reactDataAttributesPlugin from "react-data-attributes-plugin/vite";

export default defineConfig({
  plugins: [reactDataAttributesPlugin(), react()],
});

Rollup

// rollup.config.js
import reactDataAttributesPlugin from "react-data-attributes-plugin/rollup";

export default {
  plugins: [reactDataAttributesPlugin()],
};

Webpack

// webpack.config.js
import jsxDataAttributesLoader from "react-data-attributes-plugin/webpack";

export default {
  module: {
    rules: [
      {
        test: /\.(tsx|jsx)$/,
        use: [
          "babel-loader",
          {
            loader: jsxDataAttributesLoader,
            options: {
              addFileId: true,
              addComponentLine: true,
            },
          },
        ],
      },
    ],
  },
};

Esbuild

import { build } from "esbuild";
import reactDataAttributesPlugin from "react-data-attributes-plugin/esbuild";

await build({
  plugins: [reactDataAttributesPlugin()],
});

That's it! Your JSX elements will now automatically have data attributes added regardless of your bundler.

📝 What Gets Added

By default, the plugin adds the following attributes to each JSX element:

• data-file-id - Full path with line and column: "src/components/Button.tsx:42:5"
• data-element-name - The element/component name: "Button"
• data-component-path - Relative file path: "src/components/Button.tsx"
• data-component-line - Line number: "42"
• data-component-file - Filename only: "Button.tsx"
• data-component-name - Component name (same as element-name): "Button"

Example Output

<button
  data-file-id="src/components/Button.tsx:42:5"
  data-element-name="button"
  data-component-path="src/components/Button.tsx"
  data-component-line="42"
  data-component-file="Button.tsx"
  data-component-name="button"
>
  Click me
</button>

⚙️ Configuration

Basic Options

reactDataAttributesPlugin({
  enabled: true, // Enable/disable plugin (default: true in development)
  include: /\.(tsx|jsx)$/, // File pattern to include (default)
  exclude: /\.test\./, // File pattern to exclude
});

Attribute Control

Control which attributes are added:

reactDataAttributesPlugin({
  addFileId: true, // data-file-id (default: true)
  addElementName: true, // data-element-name (default: true)
  addComponentPath: true, // data-component-path (default: true)
  addComponentLine: true, // data-component-line (default: true)
  addComponentFile: true, // data-component-file (default: true)
  addComponentName: true, // data-component-name (default: true)
  addComponentContent: false, // data-component-content (default: false)
});

Minimal Configuration

Only add file location info:

reactDataAttributesPlugin({
  addFileId: true,
  addComponentLine: true,
  addComponentFile: true,
  // Disable others
  addElementName: false,
  addComponentPath: false,
  addComponentName: false,
  addComponentContent: false,
});

Enable Component Content

Include URL-encoded props in data-component-content:

reactDataAttributesPlugin({
  addComponentContent: true, // Adds URL-encoded JSON of props
});

💡 Use Cases

1. Debugging

Quickly identify which component/file an element came from in the browser:

// In browser console
document.querySelector('[data-file-id*="Button.tsx"]');

2. Testing

Use data attributes in your E2E tests:

// Playwright / Cypress
await page.click('[data-component-name="SubmitButton"]');

3. Development Tools

Build browser extensions or dev tools that use the data attributes:

// Highlight elements from specific files
document
  .querySelectorAll('[data-component-path*="components/"]')
  .forEach((el) => (el.style.border = "2px solid red"));

4. Source Mapping

Trace production issues back to source code using the file and line information.

🎯 How It Works

The plugin uses Babel to transform your JSX during the build process:

1. Parse - Babel parses your JSX/TSX files
2. Transform - Custom Babel plugin adds data attributes to each JSX element
3. Generate - Modified JSX is passed to React's plugin for final transformation

This happens entirely at build time, with zero runtime overhead.

🔧 Advanced Usage

Conditional Enabling

Only enable in development:

reactDataAttributesPlugin({
  enabled: process.env.NODE_ENV === "development",
});

Exclude Test Files

reactDataAttributesPlugin({
  exclude: /\.(test|spec)\.(tsx|jsx)$/,
});

Custom File Patterns

reactDataAttributesPlugin({
  include: /\.(tsx|jsx|vue)$/, // Include Vue files too
});

📚 API Reference

Options

All plugins share the same configuration options:

Option	Type	Default	Description
enabled	boolean	true (dev mode for Vite)	Enable/disable the plugin
include	RegExp	`/.(tsx	jsx)$/`	File pattern to include
exclude	RegExp	undefined	File pattern to exclude
addFileId	boolean	true	Add data-file-id attribute
addElementName	boolean	true	Add data-element-name attribute
addComponentPath	boolean	true	Add data-component-path attribute
addComponentLine	boolean	true	Add data-component-line attribute
addComponentFile	boolean	true	Add data-component-file attribute
addComponentName	boolean	true	Add data-component-name attribute
addComponentContent	boolean	false	Add data-component-content attribute

Import Paths

• Vite: react-data-attributes-plugin/vite
• Rollup: react-data-attributes-plugin/rollup
• Webpack: react-data-attributes-plugin/webpack
• Esbuild: react-data-attributes-plugin/esbuild
• Core: react-data-attributes-plugin/core (for custom implementations)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT © M Arie Syukron

🙏 Acknowledgments

Inspired by tools like Lovable.dev and other development debugging utilities.

---

Made with ❤️ for the developer experience