I've given this some thought, and I do think we should merge modules.md and esm.md. The package.json info can be on that merged page. I think the merged page would still have big “CommonJS Modules” and “ECMAScript Modules” sections, with lots of subsections moved from the current modules.md and esm.md respectively; but the idea is that all content that is not particular to either module system should be outside of those big system-specific sections. And there's a lot of such content! So much so that it's made me more sure that we should merge the pages.

For example, I assume the Source Maps API applies to both module systems, but currently it only lives in modules.md; and conversely Package Exports applies to both but currently only lives in esm.md. And so on. Below I've written a draft outline of the merged page, and you can see how many sections are common, outside of the scope of either module system. For each section I've noted which former file the section came from, or if it is new.

Modules

• Introduction (new, explain that Node.js has two module systems)

  • CommonJS Modules (based on modules.md introduction)
  • ECMAScript Modules (based on esm.md introduction)

• Using (based on esm.md section “Enabling”)

  • package.json "type" field
  • Package Scope and File Extensions
  • --input-type flag

• CommonJS Modules (new; all subsections from modules.md)

  • The Module Wrapper
  • The Module Scope
    • __dirname
    • __filename
    • exports
    • module
    • require(id)
      • require.cache
      • require.extensions
      • require.main
      • require.resolve(request[, options])
        • require.resolve.paths(request)
  • The module Object
    • module.children
    • module.exports
      • exports shortcut
    • module.filename
    • module.id
    • module.loaded
    • module.parent
    • module.paths
    • module.require(id)
  • Accessing The Main Module
  • Core Modules
  • File Modules
    • require of Files with the .mjs Extension (from modules.md “Addenda: The .mjs extension”)
  • Folders as Modules
  • Loading from the Global Folders
  • Loading from node_modules Folders
  • Cycles
  • Caching
    • Module Caching Caveats

• ECMAScript Modules (new; all subsections from esm.md)

  • import Specifiers
    • Terminology
      • data: Imports
  • import.meta
  • Differences Between ES Modules and CommonJS
    • Mandatory File Extensions
    • No NODE_PATH
    • No require, exports, module.exports, __filename, __dirname
    • No require.resolve
    • No require.extensions
    • No require.cache
    • URL-based Paths
  • Interoperability with CommonJS
    • require
    • import statements
    • import() expressions
  • CommonJS, JSON, and Native Modules
  • Builtin Modules
  • Experimental JSON Modules
  • Experimental Wasm Modules
  • Experimental Top-Level await
  • Experimental Loaders
    • Hooks
      • resolve Hook
      • getFormat Hook
      • getSource Hook
      • transformSource Hook
      • getGlobalPreloadCode Hook
      • dynamicInstantiate Hook
    • Examples
      • HTTPS Loader
      • Transpiler Loader

• Packages (from esm.md)

  • The package.json File (new section introducing the file itself, with very brief subsections that are nothing more than links to the appropriate sections)
    • "exports"
    • "main"
    • "name"
    • "type"
  • Package Entry Points
    • Main Entry Point Export
    • Subpath Exports
    • Package Exports Fallbacks
    • Exports Sugar
    • Conditional Exports
    • Nested conditions
    • Self-referencing a package using its name
  • Dual CommonJS/ES Module Packages
    • Dual Package Hazard
    • Writing Dual Packages While Avoiding or Minimizing Hazards
      • Approach deps: update openssl to 1.0.1j #1: Use an ES Module Wrapper
      • Approach test: don't remove empty.txt on win32 #2: Isolate State

• Utility Methods (from modules.md “The Module Object”)

  • module.builtinModules
  • module.createRequire(filename)
  • module.createRequireFromPath(filename)
  • module.syncBuiltinESMExports())

• Source Map V3 Support (from modules.md)

  • module.findSourceMap(path[, error])
  • Class: module.SourceMap
    • new SourceMap(payload)
    • sourceMap.payload
    • sourceMap.findEntry(lineNumber, columnNumber)

• Resolution Algorithms (new)

  • CommonJS Resolution Algorithm (from modules.md section “All Together...”)
  • ECMAScript Modules Resolution Algorithm (from esm.md section “Resolution Algorithm”)
    • Features
    • Resolver Algorithm
    • Customizing ESM specifier resolution algorithm

• Tips for Package Manager Authors (from modules.md “Package Manager Tips”)

For reference, here are the current full outlines of each page:

Modules

• Accessing the main module
• Addenda: Package Manager Tips
• Addenda: The .mjs extension
• All Together...
• Caching
  • Module Caching Caveats
• Core Modules
• Cycles
• File Modules
• Folders as Modules
• Loading from node_modules Folders
• Loading from the global folders
• The module wrapper
• The module scope
  • __dirname
  • __filename
  • exports
  • module
  • require(id)
    • require.cache
    • require.extensions
    • require.main
    • require.resolve(request[, options])
      • require.resolve.paths(request)
• The module Object
  • module.children
  • module.exports
    • exports shortcut
  • module.filename
  • module.id
  • module.loaded
  • module.parent
  • module.paths
  • module.require(id)
• The Module Object
  • module.builtinModules
  • module.createRequire(filename)
  • module.createRequireFromPath(filename)
  • module.syncBuiltinESMExports()
• Source Map V3 Support
  • module.findSourceMap(path[, error])
  • Class: module.SourceMap
    • new SourceMap(payload)
    • sourceMap.payload
    • sourceMap.findEntry(lineNumber, columnNumber)

ECMAScript Modules

• Introduction
• Enabling
  • package.json "type" field
  • Package Scope and File Extensions
  • --input-type flag
• Packages
  • Package Entry Points
    • Main Entry Point Export
    • Subpath Exports
    • Package Exports Fallbacks
    • Exports Sugar
    • Conditional Exports
    • Nested conditions
    • Self-referencing a package using its name
  • Dual CommonJS/ES Module Packages
    • Dual Package Hazard
    • Writing Dual Packages While Avoiding or Minimizing Hazards
      • Approach deps: update openssl to 1.0.1j #1: Use an ES Module Wrapper
      • Approach test: don't remove empty.txt on win32 #2: Isolate State
• import Specifiers
  • Terminology
    • data: Imports
• import.meta
• Differences Between ES Modules and CommonJS
  • Mandatory file extensions
  • No NODE_PATH
  • No require, exports, module.exports, __filename, __dirname
  • No require.resolve
  • No require.extensions
  • No require.cache
  • URL-based paths
• Interoperability with CommonJS
  • require
  • import statements
  • import() expressions
• CommonJS, JSON, and Native Modules
• Builtin modules
• Experimental JSON Modules
• Experimental Wasm Modules
• Experimental Top-Level await
• Experimental Loaders
  • Hooks
    • resolve hook
    • getFormat hook
    • getSource hook
    • transformSource hook
    • getGlobalPreloadCode hook
    • dynamicInstantiate hook
  • Examples
    • HTTPS loader
    • Transpiler loader
• Resolution Algorithm
  • Features
  • Resolver Algorithm
  • Customizing ESM specifier resolution algorithm