Node.js interview questions: Modules and packaging

First it checks whether it's a core module, like fs. If the string starts with ./ or ../ or /, it resolves relative to the file doing the require, so it tries the exact name, then it adds extensions, .js, .json, .node, and then it'll treat it as a directory and look for a package.json main or an index.js. Otherwise it's a bare specifier, a package name basically, and Node looks in node_modules, starting next to the requiring file and walking up the parent directories until it finds the package or hits the root. Inside the package, the package.json main field says which file is the entry point, or exports in modern packages. And results get cached, so requiring the same module twice gives you the same instance back. That caching is also why two packages can get different versions, I think, each one just finds the nearest matching node_modules.

So the first time you require something, Node loads it, runs it, and sticks the module object in require.cache, keyed by the resolved filename I believe. After that, every require of the same file just hands back the cached exports object, nothing re-executes. That's why the pattern of creating a database pool at the top of a module works as a singleton, everyone who imports it shares the one pool. Circular dependencies don't error or anything, the module that joins the cycle just gets whatever the other one has exported so far, so you can end up with missing properties if you call things too early. You can also delete entries from require.cache to force a re-load, that's how some hot-reload tools do it. And ESM keeps its own cache, but it's the same practical effect, one execution per module, shared exports.

Importing CJS from ESM has basically always worked. The module's module.exports becomes the default export, and Node can usually expose named exports too, so import pkg from 'cjs-pkg' works and import { thing } from 'cjs-pkg' tends to work as well. The other direction was forbidden for years, require() on an ES module threw ERR_REQUIRE_ESM, and the workaround was dynamic import(), which gives you back a promise and works from CJS. But modern Node has largely removed that restriction, I think, so require() of an ES module works now in current versions. The friction that's left is mostly around default exports. Depending on how the package was authored or transpiled, you sometimes have to go through .default to reach the actual function, and that's where the double-default shape comes from, or something like that.

So exports is how a package defines its public entry points. Before that you had main, which named one default file and left every other path in the package open. exports replaces that with a map, . covers the root, subpaths like ./utils cover the rest, and conditions like import, require, node, and default pick different files depending on the consumer. Usually that means importers get an ESM build and requirers get a CJS build. And anything not listed in the map just can't be imported at all, which is how a package hides its internals. The dual-package hazard is, I think, the cost of shipping both formats. The same package can load twice in one process, once as CJS and once as ESM, and the two copies don't share state, so singletons break and instanceof checks fail. There's also an imports field that does the same mapping for a package's own internal aliases, with # prefixes.

So package.json declares the version ranges, and the lockfile records what those actually resolved to, the exact version of every package, its download URL, and an integrity hash. That way a later install reproduces the same tree instead of re-resolving the ranges against whatever happens to be newest that day. You commit the lockfile, and in CI you run npm ci, which installs strictly from it. It deletes node_modules first, it fails if the lockfile and package.json disagree, and it never writes back to the lockfile. Plain npm install can update it, I think. For the ranges, caret accepts minor and patch updates, and tilde is patches only. Put together you get reproducible builds, basically, the same lockfile produces the same dependency tree and the same behavior on every developer machine and every deploy.

import.meta is the metadata object each module gets. import.meta.url is the module's file URL, and newer Node has import.meta.dirname and import.meta.filename, which give you the __dirname and __filename equivalents directly. Older code derives those with fileURLToPath. There's also import.meta.resolve('specifier'), which tells you the URL a specifier would resolve to without actually importing it, and it honors the package's exports map while it's at it. Top-level await is, well, awaiting at module scope, so a module can load config or open a connection before its exports count as ready, and Node evaluates the graph around that. I'd use it sparingly though. It's handy in scripts and small tools, but awaiting something slow during import can delay startup and kind of hide failures, so long-running services usually keep initialization explicit instead of pushing it into module load.

A peer dependency is the package saying, the host project supplies this, I just work alongside it. The classic case is a React component library, it has to use the app's React instead of shipping its own copy. And modern npm installs missing peers automatically, I think, and errors when the versions conflict. Hoisting is the package manager lifting shared dependencies up to the root node_modules so packages share one copy, and when versions conflict the extra copies stay nested down in the tree. Workspaces link your local packages into the root so they resolve like published ones. The problems that come up are basically two. Hoisting can't reconcile some versions, so you get duplicates, and two Reacts break hooks. And phantom dependencies, where your code imports a package it never declared but hoisting happened to place it at the root anyway.

Native modules are compiled C or C++ that gets loaded into the process, and they're built against a specific Node version's headers. So a major upgrade changes the binary interface, and the compiled addons you already have stop loading, you get a version mismatch error until they're rebuilt. Which means running npm rebuild, or honestly just deleting node_modules and reinstalling. Most of the popular packages avoid the compile step by shipping prebuilt binaries, at install time a helper downloads the binary matching your platform and architecture and Node version. When there's no prebuild it compiles from source with node-gyp, which needs Python and a C++ toolchain lying around. The exception is packages built on N-API, or Node-API I guess it's called now. That interface stays stable across Node versions, so those addons keep working after an upgrade.

Modern Node just runs TypeScript files directly. It strips out the type annotations and executes the JavaScript that's left, so for a lot of projects you can literally do node app.ts, no loader, no build step. Type stripping has been on by default since Node 23.6, I believe. It doesn't type-check though, so you still run tsc --noEmit in CI for that part. And the older path still works fine, you compile in CI with tsc or esbuild and deploy plain JavaScript, which keeps production simple and fast. Tools like tsx and ts-node are still around, mostly for older Node versions and for the TypeScript features the built-in stripping doesn't handle. Either way, source maps or preserved positions keep your stack traces pointing at the actual TypeScript lines.