0
# is-builtin-module
1

2
is-builtin-module provides a simple utility function to check if a string matches the name of a Node.js builtin module. It uses a static list of modules from the latest Node.js version (via the `builtin-modules` package) rather than runtime checks, making it ideal for static analysis tools, bundlers, and linters.
3

4
## Package Information
5

6
- **Package Name**: is-builtin-module
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install is-builtin-module`
10

11
## Core Imports
12

13
ES Modules:
14
```javascript
15
import isBuiltinModule from 'is-builtin-module';
16
```
17

18
CommonJS:
19
```javascript
20
const isBuiltinModule = require('is-builtin-module');
21
```
22

23
TypeScript:
24
```typescript
25
import isBuiltinModule from 'is-builtin-module';
26
```
27

28
## Basic Usage
29

30
```javascript
31
import isBuiltinModule from 'is-builtin-module';
32

33
// Check basic builtin modules
34
isBuiltinModule('fs');
35
//=> true
36

37
isBuiltinModule('path');
38
//=> true
39

40
// Check submodules
41
isBuiltinModule('fs/promises');
42
//=> true
43

44
// Check with node: prefix
45
isBuiltinModule('node:fs/promises');
46
//=> true
47

48
// Check non-builtin modules
49
isBuiltinModule('express');
50
//=> false
51

52
isBuiltinModule('react');
53
//=> false
54
```
55

56
## Capabilities
57

58
### Builtin Module Detection
59

60
Checks if a string matches the name of a Node.js builtin module using a static list from the `builtin-modules` package.
61

62
```typescript { .api }
63
/**
64
 * Check if a string matches the name of a Node.js builtin module.
65
 * 
66
 * This matches based on a static list of modules from the latest Node.js version.
67
 * If you want to check for a module in the current Node.js, use the core
68
 * isBuiltin method from the Node.js module API.
69
 * 
70
 * @param moduleName - The name of the module to check
71
 * @returns true if the module name is a builtin module, false otherwise
72
 * @throws TypeError if moduleName is not a string
73
 */
74
export default function isBuiltinModule(moduleName: string): boolean;
75
```
76

77
**Parameter Details:**
78
- `moduleName` (string): The name of the module to check. Can include:
79
  - Basic module names (e.g., `'fs'`, `'path'`, `'crypto'`)
80
  - Submodule paths (e.g., `'fs/promises'`, `'assert/strict'`)
81
  - Node.js protocol prefix (e.g., `'node:fs'`, `'node:fs/promises'`)
82

83
**Return Value:**
84
- Returns `true` if the module name matches a Node.js builtin module
85
- Returns `false` if the module name is not a builtin module
86

87
**Error Handling:**
88
- Throws `TypeError` with message "Expected a string" if `moduleName` is not a string
89

90
**Implementation Notes:**
91
- Uses lazy initialization of a Set containing builtin module names for performance
92
- Static list based on the `builtin-modules` package, not runtime Node.js detection
93
- Supports both traditional module names and modern Node.js protocol prefixes
94
- Case-sensitive matching (e.g., `'FS'` returns `false`)
95

96
**Supported Module Patterns:**
97
- Standard modules: `'fs'`, `'path'`, `'crypto'`, `'http'`, etc.
98
- Submodules: `'fs/promises'`, `'assert/strict'`, `'stream/promises'`, etc.
99
- Protocol prefixed: `'node:fs'`, `'node:fs/promises'`, `'node:test'`, etc.
100
- Protocol-only modules: `'node:test'` (only works with `node:` prefix)
101

102
**Edge Cases:**
103
- Deprecated module `'punycode'` returns `false`
104
- Trailing slashes like `'fs/'` return `false`
105
- Invalid protocol formats like `'nodE:fs'` or `'node:fS'` return `false`
106
- Malformed paths like `'node:node:fs'` or `'node:/fs'` return `false`