npm package: @jjvvv/react-source-locator
Description: A tool to locate React component source code from the browser.
Author: Alex Liu
Latest version: 0.1.2-beta.1

# 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

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

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

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

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

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

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

sourceLocator.init();
```

## 🔧 Environment Configuration

### Environment Variables

In the `.env.local` file, configure:

```bash
# Project root path
REACT_APP_PROJECT_ROOT=/Users/yourname/projects/my-app
```


## License

[MIT](./LICENSE)