@metagptx/vite-plugin-source-locator

vite-plugin-source-locator

A Vite plugin for DOM element source location tracking. This plugin helps you locate DOM elements in your source code during development.

Features

• Support for Vue 3 components
• Support for React components (JSX/TSX)
• Automatic source location tracking
• Customizable configuration

Installation

npm install @metagptx/vite-plugin-source-locator
# or
yarn add @metagptx/vite-plugin-source-locator
# or
pnpm add @metagptx/vite-plugin-source-locator

Usage

Vite

// vite.config.ts
import { defineConfig } from "vite";
import { viteSourceLocator } from "@metagptx/vite-plugin-source-locator/vite";
import vue from "@vitejs/plugin-vue"; // for Vue projects
import react from "@vitejs/plugin-react"; // for React projects

export default defineConfig({
  plugins: [
    // For Vue projects, use after vue() plugin
    vue(),
    viteSourceLocator({
      // options
    }),

    // For React projects, use before react() plugin
    viteSourceLocator({
      // options
    }),
    react(),
  ],
});

Expo / React Native Web

// babel.config.js
const { rnSourceLocator } = require("@metagptx/vite-plugin-source-locator/rn");

module.exports = function (api) {
  api.cache(true);

  return {
    presets: [["babel-preset-expo", { jsxImportSource: "nativewind" }], "nativewind/babel"],
    plugins: [rnSourceLocator()],
  };
};

rnSourceLocator injects dataSet on JSX host elements, and react-native-web turns those values into the same final DOM attributes as the Vite adapter, e.g. data-locator-path, data-locator-line, data-locator-start-column.

Use rnSourceLocator only for react-native-web / Expo Web builds. Native iOS and Android builds do not expose the same DOM data-* surface.

Backward compatibility

// vite.config.js
import { defineConfig } from "vite";
import { viteSourceLocator } from "@metagptx/vite-plugin-source-locator";
import vue from "@vitejs/plugin-vue"; // for Vue projects
import react from "@vitejs/plugin-react"; // for React projects

export default defineConfig({
  plugins: [
    // For Vue projects, use after vue() plugin
    vue(),
    viteSourceLocator({
      // options
    }),

    // For React projects, use before react() plugin
    viteSourceLocator({
      // options
    }),
    react(),
  ],
});

Important: Plugin ordering matters:

• For Vue projects: Use viteSourceLocator after vue() plugin
• For React projects: Use viteSourceLocator before react() plugin

Options

interface PluginOptions {
  // Directories to include (default: ['src'])
  include?: string[];

  // Prefix for data attributes (default: 'locator')
  prefix?: string;

  // Enable/disable the plugin (default: true)
  enable?: boolean;
}

Example

Input:

<template>
  <div>Hello World</div>
</template>

Output:

<template>
  <div data-locator-path="src/components/Hello.vue" data-locator-line="2">Hello World</div>
</template>

Upgrade Notes

• v0.0.5
  • fix issure:
    • Page crash when dom content has “"” character.