@metagptx/vite-plugin-source-locator/README.md

A Vite plugin for source code location tracking

# 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

```bash
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

```ts
// 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

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

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

```ts
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:

```vue
<template>
  <div>Hello World</div>
</template>
```

Output:

```vue
<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.