From b9ab5d193c7dccee40b9fcc35d406876118de05c Mon Sep 17 00:00:00 2001 From: Ayush Raj Date: Fri, 10 Oct 2025 13:44:25 +0530 Subject: [PATCH] doc: add note explaining ESM vs CommonJS startup performance difference --- doc/api/esm.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/api/esm.md b/doc/api/esm.md index 873147ffacd4a4..53e5e869dcaa6e 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -331,6 +331,15 @@ syncBuiltinESMExports(); fs.readFileSync === readFileSync; ``` +### Performance note + +When importing Node.js built-in modules using ESM (for example, `import { STATUS_CODES } from 'http'`), +all properties of the module are eagerly evaluated and added to the namespace at import time. +In contrast, CommonJS (`require('http')`) loads properties lazily when accessed. + +This means ESM imports can have slightly higher startup times compared to CommonJS, +especially in short-running scripts or CLI tools. +For long-running applications (e.g., servers), this difference is negligible. ## `import()` expressions