macaly-vite-tagger

A Vite plugin that automatically injects data-macaly-loc and data-macaly-name attributes into JSX elements at build time, making it easy to trace any rendered DOM element back to its exact source location.

Features

• Precise location tracking — shows file path, line, and column for each JSX element
• Zero production overhead — only runs in development (apply: 'serve')
• TypeScript support — processes both .jsx and .tsx files
• Smart filtering — skips node_modules, React Fragments, and non-DOM elements (e.g. React Three Fiber)
• Custom renderer support — ignorePackages option prevents errors from renderers that don't support DOM attributes

Installation

npm install --save-dev macaly-vite-tagger

Usage

TanStack Start

In app.config.ts:

import { defineConfig } from '@tanstack/start/config';
import { macalyViteTagger } from 'macaly-vite-tagger';

export default defineConfig({
  vite: {
    plugins: [macalyViteTagger()],
  },
});

Vite (plain)

In vite.config.ts:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { macalyViteTagger } from 'macaly-vite-tagger';

export default defineConfig({
  plugins: [
    macalyViteTagger(), // must come before the React plugin
    react(),
  ],
});

The plugin uses enforce: 'pre' internally, so ordering in the array doesn't actually matter — it will always run before @vitejs/plugin-react transforms JSX away.

Example

Input JSX

export default function Button() {
  return (
    <div className="container">
      <h1>Hello!</h1>
      <button onClick={() => console.log('clicked')}>Click me</button>
      <MyLib.SpecialButton />
    </div>
  );
}

Output HTML (in browser DevTools)

<div
  data-macaly-loc="src/components/Button.tsx:3:4"
  data-macaly-name="div"
  class="container"
>
  <h1
    data-macaly-loc="src/components/Button.tsx:4:6"
    data-macaly-name="h1"
  >Hello!</h1>
  <button
    data-macaly-loc="src/components/Button.tsx:5:6"
    data-macaly-name="button"
  >Click me</button>
  <button
    data-macaly-loc="src/components/Button.tsx:6:6"
    data-macaly-name="MyLib.SpecialButton"
  >Special</button>
</div>

Options

macalyViteTagger({
  debug: true,               // log every tagged element to the console
  ignorePackages: [          // skip components imported from these packages
    '@react-three/fiber',
    '@react-three/drei',
  ],
})

| Option | Type | Default | Description | |--------|------|---------|-------------| | debug | boolean | false | Log each tagged element and skipped file to the console | | ignorePackages | string[] | [] | Package names whose imported components should not be tagged |

What gets tagged

| Element type | Tagged? | |---|---| | HTML elements (div, button, input, …) | Yes | | SVG elements (svg, path, circle, …) | Yes | | Custom React components (MyButton, UI.Card, …) | Yes | | React Fragments (<Fragment>, <React.Fragment>, <>) | No | | Unknown lowercase elements (mesh, boxGeometry, …) | No | | Components from ignorePackages | No |

Custom renderers (React Three Fiber, etc.)

Custom renderers like React Three Fiber use JSX elements that don't accept DOM attributes. The plugin already skips unknown lowercase elements (mesh, boxGeometry, ambientLight, …) automatically. For capitalized components imported from these packages, use ignorePackages:

macalyViteTagger({
  ignorePackages: ['@react-three/fiber', '@react-three/drei'],
})

All import styles are handled:

import { Canvas } from '@react-three/fiber';            // Canvas → skipped
import { OrbitControls } from '@react-three/drei';      // OrbitControls → skipped
import * as Fiber from '@react-three/fiber';            // Fiber.* → skipped
import Drei from '@react-three/drei';                   // Drei.* → skipped

function Scene() {
  return (
    <div>                      {/* ✓ tagged */}
      <Canvas>                 {/* ✗ skipped (ignorePackages) */}
        <OrbitControls />      {/* ✗ skipped (ignorePackages) */}
        <mesh>                 {/* ✗ skipped (unknown lowercase) */}
          <boxGeometry />      {/* ✗ skipped (unknown lowercase) */}
        </mesh>
      </Canvas>
    </div>
  );
}

Attributes

Every tagged element receives two attributes:

• data-macaly-loc — relative file path + line + column, e.g. "src/App.tsx:12:4"
• data-macaly-name — element name, e.g. "button" or "MyLib.Button"

Troubleshooting

No attributes visible in DevTools?

• Confirm you're running the dev server (vite dev), not a production build
• Check that the file extension is .jsx or .tsx
• Look for [macaly-tagger] warnings in the terminal

Enable debug logging:

macalyViteTagger({ debug: true })

License

Apache-2.0