0
# Editor Integration
1

2
Utilities for integrating with code editors to enable "click to open in editor" functionality from DevTools, supporting major editors and IDE configurations.
3

4
## Capabilities
5

6
### File Path Validation
7

8
Checks if a file path exists within the specified project roots.
9

10
```javascript { .api }
11
/**
12
 * Checks if a file path exists within project roots
13
 * @param maybeRelativePath - Absolute or relative file path to check
14
 * @param absoluteProjectRoots - Array of absolute project root directory paths
15
 * @returns True if file exists within project roots, false otherwise
16
 */
17
function doesFilePathExist(maybeRelativePath: string, absoluteProjectRoots: string[]): boolean;
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
import { doesFilePathExist } from "react-devtools-core/src/editor";
24

25
const projectRoots = ['/path/to/project', '/path/to/shared'];
26

27
// Check absolute path
28
const exists1 = doesFilePathExist('/path/to/project/src/App.js', projectRoots);
29
// returns: true (if file exists)
30

31
// Check relative path
32
const exists2 = doesFilePathExist('src/components/Button.js', projectRoots);
33
// returns: true (if file exists in any project root)
34

35
// Non-existent file
36
const exists3 = doesFilePathExist('nonexistent.js', projectRoots);
37
// returns: false
38
```
39

40
### Launch Editor
41

42
Opens a file in the user's preferred code editor at a specific line number.
43

44
```javascript { .api }
45
/**
46
 * Opens a file in the user's preferred editor at a specific line
47
 * @param maybeRelativePath - Path to the file to open (absolute or relative)
48
 * @param lineNumber - Line number to navigate to (1-based)
49
 * @param absoluteProjectRoots - Array of absolute project root directories for path resolution
50
 */
51
function launchEditor(
52
  maybeRelativePath: string,
53
  lineNumber: number,
54
  absoluteProjectRoots: string[]
55
): void;
56
```
57

58
**Usage Examples:**
59

60
```javascript
61
import { launchEditor } from "react-devtools-core/src/editor";
62

63
const projectRoots = ['/path/to/project'];
64

65
// Open file at specific line
66
launchEditor('src/App.js', 25, projectRoots);
67

68
// Open file at beginning (line 1)
69
launchEditor('src/components/Button.js', 1, projectRoots);
70

71
// Absolute path
72
launchEditor('/path/to/project/src/utils/helper.js', 42, projectRoots);
73
```
74

75
## Supported Editors
76

77
### Visual Studio Code
78

79
Automatically detected and launched with `code` command.
80

81
```javascript
82
// Opens in VS Code with line navigation
83
launchEditor('src/App.js', 25, projectRoots);
84
// Executes: code --goto src/App.js:25
85
```
86

87
### JetBrains IDEs
88

89
Supports WebStorm, IntelliJ IDEA, and other JetBrains products.
90

91
```javascript
92
// Detected via process name and launched appropriately
93
launchEditor('src/App.js', 25, projectRoots);
94
// May execute: webstorm --line 25 src/App.js
95
```
96

97
### Atom
98

99
Legacy support for Atom editor.
100

101
```javascript
102
// Opens in Atom with line navigation
103
launchEditor('src/App.js', 25, projectRoots);
104
// Executes: atom src/App.js:25
105
```
106

107
### Sublime Text
108

109
Supports both Sublime Text 2 and 3.
110

111
```javascript
112
// Opens in Sublime Text
113
launchEditor('src/App.js', 25, projectRoots);
114
// Executes: subl src/App.js:25
115
```
116

117
### Terminal Editors
118

119
Supports Vim, Emacs, and Nano with terminal detection.
120

121
```javascript
122
// Opens in Vim (if configured as terminal editor)
123
launchEditor('src/App.js', 25, projectRoots);
124
// Executes: vim +25 src/App.js
125

126
// Opens in Emacs
127
launchEditor('src/App.js', 25, projectRoots);
128
// Executes: emacs +25 src/App.js
129
```
130

131
## Editor Detection
132

133
### Process-Based Detection
134

135
The editor integration automatically detects running editors by examining system processes and maps them to appropriate launch commands.
136

137
**Common Editor Mappings:**
138

139
```javascript
140
const COMMON_EDITORS = {
141
  // macOS Applications
142
  '/Applications/Visual Studio Code.app/Contents/MacOS/Electron': 'code',
143
  '/Applications/Atom.app/Contents/MacOS/Atom': 'atom',
144
  '/Applications/Sublime Text.app/Contents/MacOS/Sublime Text': '/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl',
145
  
146
  // Command line editors
147
  'vim': 'vim',
148
  'nvim': 'nvim',
149
  'emacs': 'emacs',
150
  'nano': 'nano'
151
};
152
```
153

154
### Environment Variable Configuration
155

156
Set preferred editor via environment variables:
157

158
```bash
159
# Set preferred editor
160
export EDITOR=code
161
export VISUAL=code
162

163
# Or set React DevTools specific editor
164
export REACT_EDITOR=code
165
```
166

167
**Usage in different shells:**
168

169
```bash
170
# Bash/Zsh
171
export REACT_EDITOR=code
172

173
# Fish
174
set -x REACT_EDITOR code
175

176
# Windows Command Prompt
177
set REACT_EDITOR=code
178

179
# Windows PowerShell
180
$env:REACT_EDITOR = "code"
181
```
182

183
## Advanced Configuration
184

185
### Custom Editor Arguments
186

187
Different editors require different argument formats for line navigation:
188

189
```javascript
190
/**
191
 * Editor-specific argument patterns for line navigation
192
 */
193
const editorLineArgs = {
194
  'vim': ['+{line}', '{file}'],
195
  'nvim': ['+{line}', '{file}'],
196
  'emacs': ['+{line}', '{file}'],
197
  'code': ['--goto', '{file}:{line}'],
198
  'atom': ['{file}:{line}'],
199
  'subl': ['{file}:{line}'],
200
  'webstorm': ['--line', '{line}', '{file}']
201
};
202
```
203

204
### Project Root Resolution
205

206
The integration resolves file paths within project roots:
207

208
1. **Absolute Path Check**: If file path is absolute and exists, use directly
209
2. **Relative Path Resolution**: Try resolving relative to each project root
210
3. **Fallback**: Use first project root as base if file not found
211

212
**Example Resolution:**
213

214
```javascript
215
const projectRoots = ['/frontend', '/backend', '/shared'];
216
const filePath = 'src/components/Button.js';
217

218
// Resolution order:
219
// 1. /frontend/src/components/Button.js
220
// 2. /backend/src/components/Button.js  
221
// 3. /shared/src/components/Button.js
222
// 4. Use /frontend/src/components/Button.js (first root fallback)
223
```
224

225
### Monorepo Support
226

227
For monorepo setups, configure multiple project roots:
228

229
```javascript
230
import DevtoolsUI from "react-devtools-core/standalone";
231

232
// Configure for monorepo structure
233
DevtoolsUI.setProjectRoots([
234
  '/monorepo/packages/frontend',
235
  '/monorepo/packages/backend',
236
  '/monorepo/packages/shared',
237
  '/monorepo/apps/mobile'
238
]);
239

240
// DevTools will resolve files across all roots
241
// Click on component -> opens correct file in appropriate package
242
```
243

244
## Integration with DevTools UI
245

246
### Setup in CLI Tool
247

248
When using the CLI tool, pass project roots as arguments:
249

250
```bash
251
# Single project
252
react-devtools /path/to/project
253

254
# Multiple projects (monorepo)
255
react-devtools /path/to/frontend /path/to/backend /path/to/shared
256
```
257

258
### Setup in Standalone Server
259

260
Configure project roots programmatically:
261

262
```javascript
263
import DevtoolsUI from "react-devtools-core/standalone";
264

265
// Setup editor integration
266
DevtoolsUI.setProjectRoots([
267
  process.cwd(),
268
  path.join(process.cwd(), '..', 'shared')
269
]);
270

271
// Start server with editor support
272
const server = DevtoolsUI.startServer();
273
```
274

275
### React Native Integration
276

277
React Native projects benefit from editor integration for navigating to component source:
278

279
```javascript
280
import { connectToDevTools } from "react-devtools-core/backend";
281

282
// Connect with project root information
283
connectToDevTools({
284
  // Project roots passed from CLI or configuration
285
  // Enables click-to-open functionality in React Native
286
});
287
```
288

289
## Troubleshooting
290

291
### Editor Not Opening
292

293
**Check Editor in PATH:**
294

295
```bash
296
# Verify editor command is available
297
which code
298
which atom
299
which subl
300

301
# Add to PATH if needed (VS Code example)
302
export PATH="$PATH:/Applications/Visual Studio Code.app/Contents/Resources/app/bin"
303
```
304

305
**Set Explicit Editor:**
306

307
```bash
308
# Override automatic detection
309
export REACT_EDITOR=code
310
export REACT_EDITOR="/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code"
311
```
312

313
### File Not Found
314

315
**Verify Project Roots:**
316

317
```javascript
318
// Check project roots are correct
319
console.log('Project roots:', projectRoots);
320

321
// Verify file exists
322
import fs from 'fs';
323
const fullPath = path.join(projectRoot, filePath);
324
console.log('File exists:', fs.existsSync(fullPath));
325
```
326

327
**Debug Path Resolution:**
328

329
```javascript
330
import { doesFilePathExist } from "react-devtools-core/src/editor";
331

332
const filePath = 'src/App.js';
333
const projectRoots = ['/path/to/project'];
334

335
console.log('File exists:', doesFilePathExist(filePath, projectRoots));
336

337
// Manual check
338
projectRoots.forEach(root => {
339
  const fullPath = path.join(root, filePath);
340
  console.log(`${root}: ${fs.existsSync(fullPath)}`);
341
});
342
```
343

344
### Permission Issues
345

346
**macOS Security:**
347

348
```bash
349
# Grant permissions to editor if needed
350
xattr -d com.apple.quarantine /Applications/Visual\ Studio\ Code.app
351
```
352

353
**Linux Permissions:**
354

355
```bash
356
# Ensure editor executable has proper permissions
357
chmod +x /usr/local/bin/code
358
```
359

360
**Windows PATH Issues:**
361

362
```cmd
363
# Add VS Code to PATH
364
setx PATH "%PATH%;%LOCALAPPDATA%\Programs\Microsoft VS Code\bin"
365
```