React Source Locator

A universal front-end source code locator for React projects, allowing you to click on any element in the development environment and jump directly to the corresponding source code file.

✨ Features

• 🎯 Accurate a- 🎯 Accurate Location: Uses React Fiber to obtain component information for precise source code location.
• 🔧 Highly Configurable: Supports custom project paths, editors, hotkeys, and more.
• 🌍 Universal: Can be used in any React project without modifying the source code.
• 📝 Multi-Editor Support: Built-in support for VS Code, WebStorm, Cursor, and more.
• 🐛 Debug Friendly: Provides detailed debugging information.
• 🚀 Zero Dependencies: Does not rely on any third-party libraries.

📦 Installation

npm install react-source-locator
# or
yarn add react-source-locator
# or
pnpm add react-source-locator

🚀 Quick Start

Initialize the locator in your project's entry file (e.g., index.js or main.js):

import { SourceLocator } from 'react-source-locator';

// Initialize in the project entry file
if (process.env.NODE_ENV === 'development') {
  const sourceLocator = new SourceLocator({
    projectRoot: '/path/to/your/project', // Required
    activationKey: 'alt',                 // Optional, defaults to 'alt'
    debug: true                           // Optional, enables debug mode
  });

  sourceLocator.init();
}

How to Use

1. Hold down the Alt key (or other configured hotkey).
2. Click on any element on the page.
3. The tool will automatically open the corresponding source file in your editor.

⚙️ Configuration

The initSourceLocator function accepts a configuration object with the following options:

interface SourceLocatorOptions {
  /** The root path of your project. Required for resolving source file paths. */
  projectRoot: string;

  /** The activation hotkey. Defaults to 'alt'. */
  activationKey?: 'alt' | 'ctrl' | 'meta';

  /** The preferred editor to open files with. If not set, a selector will be shown. */
  preferredEditor?: string;

  /** Whether to show tooltips. Defaults to true. */
  showTooltip?: boolean;

  /** A list of supported editor configurations. */
  editors?: EditorConfig[];

  /** Whether to enable debug mode. Defaults to false. */
  debug?: boolean;
}

interface EditorConfig {
  /** The name of the editor. */
  name: string;

  /** The protocol used to open files (e.g., 'vscode'). */
  protocol: string;

  /** A URL template with placeholders {absolutePath}, {lineNumber}, {columnNumber}. */
  urlTemplate: string;
}

📖 Usage Examples

Basic Configuration

If you don't specify a preferredEditor, a UI selector will appear on the screen to let you choose an editor.

import { SourceLocator } from 'react-source-locator';

const sourceLocator = new SourceLocator({
  projectRoot: '/path/to/your/project',
  activationKey: 'alt',
  debug: true
});

sourceLocator.init();

Specify a Preferred Editor

Set preferredEditor to automatically open files in your favorite editor.

import { SourceLocator } from 'react-source-locator';

const sourceLocator = new SourceLocator({
  projectRoot: '/path/to/your/project',
  preferredEditor: 'VSCode', // Will prioritize VS Code
  activationKey: 'alt',
  debug: true
});

sourceLocator.init();

Custom Editors

You can also define your own list of editors.

const sourceLocator = new SourceLocator({
  projectRoot: '/path/to/project',
  editors: [
    {
      name: 'MyCoolEditor',
      protocol: 'cool-editor',
      urlTemplate: '{protocol}://open?file={absolutePath}&line={lineNumber}'
    }
  ]
});

sourceLocator.init();

License

MIT