vite-plugin-component-ref 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antigravity User
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# vite-plugin-component-ref
+
+A powerful Vite plugin that automatically tags React components with source reference attributes. This enables a seamless **"Alt + Click"** experience to jump from your browser directly to the corresponding line in your IDE.
+
+## Features
+
+- 🎯 **Automatic Tagging**: Injects `ref-id`, `ref-component`, `ref-line`, etc., into your JSX elements.
+- ⚡ **Click-to-Open**: Press `Alt + Click` in the browser to instantly open the source file in your editor at the exact line.
+- 🤖 **Smart Editor Defaults**: Built-in support for `antigravity`, `cursor`, and `vscode` (no manual configuration needed).
+- 🛠️ **Flexible Configuration**: Full control over what attributes to inject and which files to include/exclude.
+- 👥 **Team Friendly**: Environment variable overrides allow each developer to use their preferred editor.
+- 🛡️ **Production Safe**: Automatically disables itself in production builds to keep your bundle clean.
+
+## Installation
+
+```bash
+npm install vite-plugin-component-ref --save-dev
+# or
+yarn add vite-plugin-component-ref --dev
+```
+
+## Quick Start
+
+Add the plugin to your `vite.config.ts`:
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { componentRefTagger } from 'vite-plugin-component-ref';
+
+export default defineConfig({
+  plugins: [
+    componentRefTagger({
+      editor: 'antigravity', // Automatically handles line-positioning flags
+    }),
+    react(),
+  ],
+});
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `prefix` | `string` | `"data-ref"` | Prefix for the injected attributes (e.g., `ref-id`). |
+| `attributes` | `string[]` | `['id', 'name', 'path', 'line', 'file', 'component']` | Which attributes to inject. |
+| `basePath` | `string` | `"src"` | The base directory for calculating relative paths. |
+| `include` | `(string \| RegExp)[]` | `['.tsx', '.jsx']` | Files to process. |
+| `exclude` | `(string \| RegExp)[]` | `['node_modules', 'main.tsx']` | Files to ignore. |
+| `enabled` | `boolean` | `true` | Enable or disable the plugin. |
+| `editor` | `string` | `"code"` | Your preferred editor (e.g., `antigravity`, `cursor`, `code`). |
+| `shouldTag` | `(comp, path) => boolean`| `() => true` | Custom filter for specific components or files. |
+| `openInEditor`| `(path, line) => void` | `undefined` | Custom callback for manual editor integration. |
+
+## Advanced Usage
+
+### Custom Editor Command
+If your editor needs a specific format, use `{file}` and `{line}` placeholders:
+```typescript
+componentRefTagger({
+  editor: 'my-editor --goto {file}:{line}'
+})
+```
+
+### Team Collaboration (Environment Overrides)
+Developers can override the project-wide editor setting by adding a variable to their `.env.local`:
+
+```bash
+# .env.local
+COMPONENT_REF_EDITOR=cursor
+```
+
+The plugin will automatically detect it's Cursor and use the correct positioning flags!
+
+### Selective Tagging
+Only tag components starting with "User":
+```typescript
+componentRefTagger({
+  shouldTag: (name) => name.startsWith('User')
+})
+```
+
+## License
+
+MIT © [Antigravity User]

package/dist/index.d.mts

@@ -0,0 +1,16 @@
+import { Plugin } from 'vite';
+
+interface PluginOptions {
+    prefix?: string;
+    attributes?: ("id" | "name" | "path" | "line" | "file" | "component")[];
+    basePath?: string;
+    include?: string | RegExp | (string | RegExp)[];
+    exclude?: string | RegExp | (string | RegExp)[];
+    enabled?: boolean;
+    shouldTag?: (componentName: string, filePath: string) => boolean;
+    editor?: string;
+    openInEditor?: (filePath: string, line: number) => void;
+}
+declare function componentRefTagger(options?: PluginOptions): Plugin;
+
+export { type PluginOptions, componentRefTagger };

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { Plugin } from 'vite';
+
+interface PluginOptions {
+    prefix?: string;
+    attributes?: ("id" | "name" | "path" | "line" | "file" | "component")[];
+    basePath?: string;
+    include?: string | RegExp | (string | RegExp)[];
+    exclude?: string | RegExp | (string | RegExp)[];
+    enabled?: boolean;
+    shouldTag?: (componentName: string, filePath: string) => boolean;
+    editor?: string;
+    openInEditor?: (filePath: string, line: number) => void;
+}
+declare function componentRefTagger(options?: PluginOptions): Plugin;
+
+export { type PluginOptions, componentRefTagger };