global-builtin-modules

Installs a global with lazy-loaded Node.js builtin modules.

Install

npm i global-builtin-modules

Usage (recommended)

Side-effect import at the top of your entrypoint:

import 'global-builtin-modules'

const fileContent = await N.fs.promises.readFile('example.txt', 'utf8')
const fileContent2 = await N.fs.promises.readFile('example2.txt', 'utf8')

N.fs is loaded on first access; subsequent reads hit a normal property (no Proxy trap overhead).

Manual install/uninstall (advanced)

import { installGlobalBuiltinModules } from 'global-builtin-modules/install'
import { uninstallGlobalBuiltinModules } from 'global-builtin-modules/uninstall'

installGlobalBuiltinModules() // installs globalThis.N

// Optional: customize the global name
installGlobalBuiltinModules({ name: 'NB' })
await NB.path.join('a', 'b')

// Uninstall
uninstallGlobalBuiltinModules() // removes globalThis.N
uninstallGlobalBuiltinModules('NB') // removes globalThis.NB

Options

installGlobalBuiltinModules(options) supports:

• name (default "N"): the global name to define
• allowlist (default: all Node builtins, minus internal _...): which builtins to expose on N
• overwrite (default false): overwrite an existing global with the same name
• preventExtensions (default true): disallow adding new properties onto N
• require: custom loader (useful in tests)

Example allowlist:

import { installGlobalBuiltinModules } from 'global-builtin-modules/install'

installGlobalBuiltinModules({
  allowlist: ['fs', 'path', 'crypto'],
})

Notes

• Node-only. Requires Node >= 18.
• Default allowlist is derived from Node’s builtinModules.
• Implementation uses self-rewriting getters (fast after first access).