is-builtin-module

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.

Package Information

• Package Name: is-builtin-module
• Package Type: npm
• Language: JavaScript/TypeScript
• Installation: npm install is-builtin-module

Core Imports

ES Modules:

import isBuiltinModule from 'is-builtin-module';

CommonJS:

const isBuiltinModule = require('is-builtin-module');

TypeScript:

import isBuiltinModule from 'is-builtin-module';

Basic Usage

import isBuiltinModule from 'is-builtin-module';

// Check basic builtin modules
isBuiltinModule('fs');
//=> true

isBuiltinModule('path');
//=> true

// Check submodules
isBuiltinModule('fs/promises');
//=> true

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

// Check non-builtin modules
isBuiltinModule('express');
//=> false

isBuiltinModule('react');
//=> false

Capabilities

Builtin Module Detection

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

/**
 * Check if a string matches the name of a Node.js builtin module.
 * 
 * This matches based on a static list of modules from the latest Node.js version.
 * If you want to check for a module in the current Node.js, use the core
 * isBuiltin method from the Node.js module API.
 * 
 * @param moduleName - The name of the module to check
 * @returns true if the module name is a builtin module, false otherwise
 * @throws TypeError if moduleName is not a string
 */
export default function isBuiltinModule(moduleName: string): boolean;

Parameter Details:

• moduleName (string): The name of the module to check. Can include:
  • Basic module names (e.g., 'fs', 'path', 'crypto')
  • Submodule paths (e.g., 'fs/promises', 'assert/strict')
  • Node.js protocol prefix (e.g., 'node:fs', 'node:fs/promises')

Return Value:

• Returns true if the module name matches a Node.js builtin module
• Returns false if the module name is not a builtin module

Error Handling:

• Throws TypeError with message "Expected a string" if moduleName is not a string

Implementation Notes:

• Uses lazy initialization of a Set containing builtin module names for performance
• Static list based on the builtin-modules package, not runtime Node.js detection
• Supports both traditional module names and modern Node.js protocol prefixes
• Case-sensitive matching (e.g., 'FS' returns false)

Supported Module Patterns:

• Standard modules: 'fs', 'path', 'crypto', 'http', etc.
• Submodules: 'fs/promises', 'assert/strict', 'stream/promises', etc.
• Protocol prefixed: 'node:fs', 'node:fs/promises', 'node:test', etc.
• Protocol-only modules: 'node:test' (only works with node: prefix)

Edge Cases:

• Deprecated module 'punycode' returns false
• Trailing slashes like 'fs/' return false
• Invalid protocol formats like 'nodE:fs' or 'node:fS' return false
• Malformed paths like 'node:node:fs' or 'node:/fs' return false