0
# Import From
1

2
Import From provides a simple utility for importing Node.js modules from a specific directory path, similar to the built-in `require()` function but with the ability to specify the base directory for module resolution. It offers both a standard version that throws errors when modules can't be found and a silent version that returns undefined instead.
3

4
## Package Information
5

6
- **Package Name**: import-from
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install import-from`
10

11
## Core Imports
12

13
```typescript
14
import importFrom = require('import-from');
15
```
16

17
CommonJS:
18

19
```javascript
20
const importFrom = require('import-from');
21
```
22

23
## Basic Usage
24

25
```javascript
26
const importFrom = require('import-from');
27

28
// Import a module from a specific directory
29
try {
30
  const chalk = importFrom('./some-directory', 'chalk');
31
  console.log(chalk.blue('Hello world'));
32
} catch (error) {
33
  console.log('Module not found:', error.message);
34
}
35

36
// Silent import - returns undefined instead of throwing
37
const lodash = importFrom.silent('./some-directory', 'lodash');
38
if (lodash) {
39
  console.log(lodash.capitalize('hello'));
40
} else {
41
  console.log('Module not available');
42
}
43
```
44

45
## Architecture
46

47
Import From uses Node.js's built-in `createRequire` API to create custom require functions that resolve modules from a specified directory. The core design pattern involves:
48

49
- **Path Resolution**: Uses `path.resolve()` to convert the target directory into an absolute path
50
- **Require Function Creation**: Creates a scoped require function using `createRequire()` with a dummy file path (`noop.js`) in the target directory
51
- **Module Resolution**: The created require function resolves modules relative to the specified directory, following standard Node.js module resolution rules
52
- **Error Handling**: Provides both throwing and silent versions for different error handling needs
53

54
This approach leverages Node.js's native module system while allowing custom resolution contexts, making it a lightweight wrapper around standard module loading behavior.
55

56
## Capabilities
57

58
### Module Import
59

60
Imports a module from a specified directory path, similar to `require()` but with custom base directory resolution.
61

62
```typescript { .api }
63
/**
64
 * Import a module like with require() but from a given path
65
 * @param fromDirectory - Directory to import from
66
 * @param moduleId - What you would use in require()
67
 * @returns The imported module
68
 * @throws MODULE_NOT_FOUND error when the module can't be found
69
 */
70
function importFrom(fromDirectory: string, moduleId: string): unknown;
71
```
72

73
**Usage Examples:**
74

75
```javascript
76
const importFrom = require('import-from');
77

78
// Import a relative module from a specific directory
79
const helper = importFrom('./src/utils', './helper');
80

81
// Import an npm package that's installed in a specific directory
82
const express = importFrom('./my-project', 'express');
83

84
// Import with path resolution
85
const config = importFrom('/absolute/path/to/project', './config.json');
86
```
87

88
### Silent Module Import
89

90
Imports a module from a specified directory path, returning `undefined` instead of throwing when the module cannot be found.
91

92
```typescript { .api }
93
/**
94
 * Import a module like with require() but from a given path
95
 * @param fromDirectory - Directory to import from
96
 * @param moduleId - What you would use in require()
97
 * @returns The imported module or undefined if not found
98
 */
99
importFrom.silent(fromDirectory: string, moduleId: string): unknown;
100
```
101

102
**Usage Examples:**
103

104
```javascript
105
const importFrom = require('import-from');
106

107
// Safely attempt to import an optional dependency
108
const optionalDep = importFrom.silent('./plugins', 'optional-plugin');
109
if (optionalDep) {
110
  optionalDep.activate();
111
}
112

113
// Check for module availability without error handling
114
const devTool = importFrom.silent('./dev-tools', 'debug-helper');
115
const debugMode = !!devTool;
116

117
// Graceful fallback for missing modules
118
const preferredLib = importFrom.silent('./libs', 'preferred-lib') || 
119
                     importFrom.silent('./libs', 'fallback-lib');
120
```
121

122
## Advanced Usage
123

124
### Partial Application
125

126
Create a bound function for importing from the same directory multiple times:
127

128
```javascript
129
const importFrom = require('import-from');
130

131
// Create a partial function for a specific directory
132
const importFromFoo = importFrom.bind(null, 'foo');
133

134
// Use the bound function multiple times
135
const bar = importFromFoo('./bar');
136
const baz = importFromFoo('./baz');
137
```
138

139
### Error Handling
140

141
The standard `importFrom` function throws standard Node.js `MODULE_NOT_FOUND` errors:
142

143
```javascript
144
const importFrom = require('import-from');
145

146
try {
147
  const missing = importFrom('./directory', './missing-module');
148
} catch (error) {
149
  console.log(error.code); // 'MODULE_NOT_FOUND'
150
  console.log(error.message); // "Cannot find module './missing-module'"
151
}
152
```
153

154
## Implementation Details
155

156
- Built on top of Node.js's `createRequire` API from the `module` module
157
- Uses `path.resolve()` to handle directory path resolution
158
- Creates a require function scoped to the specified directory
159
- Requires Node.js >=12.2 (as specified in package.json)
160
- No external dependencies - pure Node.js implementation
161

162
## Types
163

164
```typescript { .api }
165
declare const importFrom: {
166
  /**
167
   * Import a module like with require() but from a given path
168
   * @param fromDirectory - Directory to import from
169
   * @param moduleId - What you would use in require()
170
   * @throws Like require(), throws when the module can't be found
171
   */
172
  (fromDirectory: string, moduleId: string): unknown;
173

174
  /**
175
   * Import a module like with require() but from a given path
176
   * @param fromDirectory - Directory to import from
177
   * @param moduleId - What you would use in require()
178
   * @returns undefined instead of throwing when the module can't be found
179
   */
180
  silent(fromDirectory: string, moduleId: string): unknown;
181
};
182

183
export = importFrom;
184
```