0
# import-local
1

2
Let a globally installed package use a locally installed version of itself if available. Useful for CLI tools that want to defer to the user's locally installed version when available, but still work if it's not installed locally.
3

4
## Package Information
5

6
- **Package Name**: import-local
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript (Node.js)
9
- **Installation**: `npm install import-local`
10

11
## Core Imports
12

13
```javascript
14
const importLocal = require('import-local');
15
```
16

17
For ES Modules:
18

19
```javascript
20
import importLocal from 'import-local';
21
```
22

23
For TypeScript:
24

25
```typescript
26
import importLocal from 'import-local';
27
```
28

29
## Basic Usage
30

31
```javascript
32
const importLocal = require('import-local');
33

34
if (importLocal(__filename)) {
35
    console.log('Using local version of this package');
36
} else {
37
    // Code for both global and local version here…
38
}
39
```
40

41
For ES Modules:
42

43
```javascript
44
import importLocal from 'import-local';
45

46
if (importLocal(import.meta.url)) {
47
    console.log('Using local version of this package');
48
} else {
49
    // Code for both global and local version here…
50
}
51
```
52

53
## Capabilities
54

55
### Local Package Detection
56

57
Detects if a locally installed version of the current package is available and imports it if found.
58

59
```javascript { .api }
60
/**
61
 * Let a globally installed package use a locally installed version of itself if available
62
 * @param filePath - The absolute file path to the main file of the package (supports __filename for CommonJS or import.meta.url for ES modules)
63
 * @returns The required local module if found, otherwise false
64
 */
65
function importLocal(filePath: string): any | false;
66
```
67

68
**Parameters:**
69
- `filePath` (string): The absolute file path to the main file of the package. Can be:
70
  - `__filename` when used in CommonJS context
71
  - `import.meta.url` when used in ES modules context
72
  - Any absolute file path to the package's main entry point
73

74
**Return Value:**
75
- Returns the required local module if a local version is found and successfully loaded
76
- Returns `false` if no local version is available or if the current execution is already from a local installation
77

78
**Behavior:**
79
- Automatically handles both CommonJS (`__filename`) and ES modules (`import.meta.url`) contexts
80
- Detects whether the current execution is from a global or local installation
81
- Uses intelligent path analysis to determine package directories and node_modules structures
82
- Cross-platform compatible, handling Windows path case inconsistencies
83
- Prevents infinite loops by detecting when already running from local node_modules
84

85
**Usage Examples:**
86

87
CommonJS CLI tool:
88
```javascript
89
#!/usr/bin/env node
90
const importLocal = require('import-local');
91

92
if (importLocal(__filename)) {
93
    // Local version will handle execution
94
    process.exit(0);
95
}
96

97
// Global version code continues here
98
console.log('Running global version');
99
```
100

101
ES Modules entry point:
102
```javascript
103
import importLocal from 'import-local';
104

105
if (importLocal(import.meta.url)) {
106
    // Local version will handle execution
107
    process.exit(0);
108
}
109

110
// Global version code continues here
111
console.log('Running global version');
112
```
113

114
Package main file:
115
```javascript
116
const importLocal = require('import-local');
117
const path = require('path');
118

119
// Check for local version using explicit path
120
const localModule = importLocal(path.join(__dirname, 'index.js'));
121
if (localModule) {
122
    module.exports = localModule;
123
} else {
124
    // Export global version functionality
125
    module.exports = require('./lib/global-implementation');
126
}
127
```