Modules, Loading and Bootstrap

// every CommonJS file is wrapped in a function before it runs
(function (exports, require, module, __filename, __dirname) {
  // your file here
});

// require('x') resolution, simplified:
// 1. core module ('fs', 'node:fs')?                         → built in
// 2. starts with './', '../', '/'?                          → file, then file.js/.json/.node, then dir/index.js
// 3. otherwise walk up node_modules/ directories            → package.json "exports" (if present) or "main"
// result is cached in require.cache by absolute filename

// a cycle: a.js requires b.js, b.js requires a.js
// b sees a's exports object as it is at that moment: partially filled
console.log(require.resolve('lodash'), Object.keys(require.cache).length);

// package.json for a package shipping both formats
{
  "name": "money",
  "type": "module",
  "exports": {
    ".": { "import": "./dist/index.js", "require": "./dist/index.cjs", "types": "./dist/index.d.ts" },
    "./format": "./dist/format.js",
    "./package.json": "./package.json"
  },
  "imports": { "#internal/*": "./src/internal/*.js" }   // private aliases, only inside this package
}

// customise resolution and loading: module.register (runs hooks off-thread)
// register.mjs
import { register } from 'node:module';
register('./hooks.mjs', import.meta.url);

// hooks.mjs: load .graphql files as modules exporting a string
export async function load(url, context, next) {
  if (url.endsWith('.graphql')) {
    const src = await (await import('node:fs/promises')).readFile(new URL(url), 'utf8');
    return { format: 'module', source: `export default ${JSON.stringify(src)};`, shortCircuit: true };
  }
  return next(url, context);
}
// node --import ./register.mjs app.mjs