0
# Import Fresh
1

2
Import Fresh provides a utility function for importing Node.js modules while bypassing the require cache. This enables fresh imports of modules for testing and development purposes by ensuring that modules are fully reloaded and re-executed, resetting any module-level state.
3

4
## Package Information
5

6
- **Package Name**: import-fresh
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install import-fresh`
10

11
## Core Imports
12

13
CommonJS:
14

15
```javascript
16
const importFresh = require('import-fresh');
17
```
18

19
ESM:
20

21
```javascript
22
import importFresh from 'import-fresh';
23
```
24

25
TypeScript (CommonJS):
26

27
```typescript
28
import importFresh = require('import-fresh');
29
```
30

31
TypeScript (ESM):
32

33
```typescript
34
import importFresh from 'import-fresh';
35
```
36

37
## Basic Usage
38

39
```javascript
40
const importFresh = require('import-fresh');
41

42
// Example: Fresh import of a counter module
43
// counter.js exports a function that increments an internal counter
44

45
require('./counter')(); //=> 1
46
require('./counter')(); //=> 2 (cached, counter state persists)
47

48
importFresh('./counter')(); //=> 1 (fresh import, counter state reset)
49
importFresh('./counter')(); //=> 1 (fresh import again, counter state reset)
50
```
51

52
## Capabilities
53

54
### Import Fresh Function
55

56
Imports a module while bypassing Node.js require cache, ensuring the module is freshly loaded and executed.
57

58
```javascript { .api }
59
/**
60
 * Import a module while bypassing the cache
61
 * @param moduleId - The module identifier to import (relative path, absolute path, or package name)
62
 * @returns The imported module's exports
63
 * @throws TypeError if moduleId is not a string
64
 */
65
function importFresh(moduleId: string): any;
66
```
67

68
**Parameters:**
69
- `moduleId` (string): The module identifier to import. Can be:
70
  - Relative path: `'./my-module'`, `'../utils/helper'`
71
  - Absolute path: `'/path/to/module'`
72
  - Package name: `'lodash'`, `'express'`
73

74
**Returns:**
75
- The imported module's exports (any type)
76

77
**Error Handling:**
78
- Throws `TypeError` with message "Expected a string" if `moduleId` is not a string
79

80
**Behavior:**
81
- Resolves the module path using the calling module's directory as context
82
- Removes the target module from Node.js's `require.cache`
83
- Properly manages parent-child module relationships to prevent memory leaks
84
- Re-imports the module with fresh execution context
85
- Works correctly even when the parent module is removed from cache
86

87
**Usage Examples:**
88

89
```javascript
90
const importFresh = require('import-fresh');
91

92
// Testing scenario: Module with internal state
93
// config.js
94
let config = { debug: false };
95
module.exports = {
96
  getConfig: () => config,
97
  setDebug: (value) => { config.debug = value; }
98
};
99

100
// Test file
101
const config1 = require('./config');
102
config1.setDebug(true);
103
console.log(config1.getConfig().debug); //=> true
104

105
const config2 = require('./config'); // Cached
106
console.log(config2.getConfig().debug); //=> true (state persisted)
107

108
const config3 = importFresh('./config'); // Fresh import
109
console.log(config3.getConfig().debug); //=> false (state reset)
110
```
111

112
```typescript
113
// TypeScript usage with generic type parameter (CommonJS)
114
import importFresh = require('import-fresh');
115

116
interface MyModule {
117
  getValue(): number;
118
  reset(): void;
119
}
120

121
const myModule = importFresh<MyModule>('./my-module');
122
const value = myModule.getValue(); // Fully typed
123
```
124

125
```typescript
126
// TypeScript usage with generic type parameter (ESM)
127
import importFresh from 'import-fresh';
128

129
interface MyModule {
130
  getValue(): number;
131
  reset(): void;
132
}
133

134
const myModule = importFresh<MyModule>('./my-module');
135
const value = myModule.getValue(); // Fully typed
136
```
137

138
## Types
139

140
```typescript { .api }
141
/**
142
 * Import a module while bypassing the cache with TypeScript generics support
143
 */
144
declare function importFresh<T>(moduleId: string): T;
145
```
146

147
The TypeScript declaration supports generic type parameters for type-safe imports when you know the expected module structure.