How to import a module using require in Node.js

The require function in Node.js is a synchronous operation that loads modules on demand. When you call require('module-name'), Node.js first resolves the module’s location, then reads and executes the module’s code, and finally caches the exported object for future calls. This caching mechanism ensures that modules are loaded only once, improving performance and consistency across your application.

At its core, require is more than just a simple file loader; it wraps the module code in a function to provide module scope and prevent global namespace pollution. Internally, Node.js wraps every module’s code like this:

(function(exports, require, module, __filename, __dirname) {
  // Module code actually lives here
});

This means each module has its own exports object where you attach what you want to expose, plus access to the module object itself, which contains metadata and the exports reference. Understanding this wrapper is key because it explains why top-level variables in a module don’t leak out globally—they are scoped to this anonymous function.

When you call require on a module, Node.js performs a series of steps to resolve the path:

• If the argument is a core module like fs or http, it loads the internal implementation immediately.
• If it is a relative path (starting with ./ or ../), Node.js resolves it relative to the current file’s directory.
• If it is a bare module name, Node.js searches through node_modules directories, walking up the directory tree until it finds the requested module.

After resolving the path, Node.js determines the file type. It supports JavaScript files (.js), JSON files (.json), and native add-ons (.node) with appropriate loaders. If the path is a directory, Node.js looks for an index.js or the file specified in the directory’s package.json main property.

Because require caches modules after the first load, multiple calls to require with the same resolved path return the exact same object. That is important for things like singletons or shared state:

const configA = require('./config');
const configB = require('./config');

console.log(configA === configB); // true

Any mutations to configA will be visible through configB as well, which can be both useful and dangerous if not handled carefully.

Another subtlety lies in how circular dependencies are handled. If two modules require each other, Node.js doesn’t throw an error but instead provides a partial exports object to break the cycle. This means some exports might be undefined or incomplete during the initial loading phase, so it’s important to structure code to avoid relying on partially initialized modules.

Understanding these mechanics opens up advanced patterns like lazy loading modules or manipulating the module cache for hot-reloading or testing. But fundamentally, require is a powerful primitive that bridges the gap between synchronous code execution and modular design in Node.js.

For example, a simple custom module might look like this:

/* greet.js */
exports.sayHello = function(name) {
  return Hello, ${name}!; };

And importing it elsewhere:

const greet = require('./greet');

console.log(greet.sayHello('World')); // Hello, World!

Behind the scenes, the exports object is passed into the wrapped function, and whatever properties you attach become accessible to the importer. If you replace exports with a new object, make sure to assign it to module.exports instead, as exports is just a shortcut:

/* bad.js */
exports = function() {
  console.log('This won’t work as expected');
};

/* good.js */
module.exports = function() {
  console.log('This works!');
};

Misunderstanding this subtlety leads to confusing bugs where the imported module ends up being an empty object instead of the intended function or class.

Fundamentally, require is not just a loader but a core part of Node.js’s module system, enforcing encapsulation, caching, and resolution rules that shape how your application code is structured and executed. Mastering these details can greatly improve your ability to debug tricky issues, optimize loading behavior, and architect clean module boundaries that scale gracefully.

When diving deeper into require, keep in mind that the module cache is stored in require.cache, an object keyed by resolved file paths. This cache can be inspected or even manipulated at runtime:

console.log(require.cache);

delete require.cache[require.resolve('./someModule')];

const freshModule = require('./someModule');

This technique is used in development tools to reload modules without restarting the process, but it must be handled cautiously to avoid unintended side effects.

Lastly, it’s worth noting that require is synchronous, which can be a bottleneck if loading large modules or numerous files on startup. Unlike import() in ES Modules, which supports async loading, require halts execution until the module is fully loaded and evaluated. This behavior is baked into Node.js’s CommonJS design and influences how module dependencies are structured for optimal startup time.

All these mechanics make require deceptively simple at first glance but richly nuanced underneath. The more you understand its internals, the more you can leverage Node.js’s modularity to write robust, maintainable code that behaves predictably across different environments and scales well as your project grows.

Think the following example demonstrating module resolution with a nested directory:

/project
  /lib
    utils.js
  index.js

In index.js, requiring ./lib/utils will resolve to utils.js inside the lib folder relative to index.js:

const utils = require('./lib/utils');

If utils.js exports functions or objects, they’ll be available here transparently. But if you mistakenly omit the relative path prefix and write require('lib/utils'), Node.js will look for a package named lib inside node_modules, resulting in a module not found error.

Understanding this relative vs bare module specifier distinction is fundamental to correctly structuring and importing your modules.

When require encounters a JSON file, it parses the content and returns the resulting object, making it a convenient way to load configuration:

const config = require('./config.json');

console.log(config.port);

This behavior allows JSON to be treated as a first-class module, eliminating the need for manual parsing or asynchronous reads for static configuration data.

All these details combine to form the essential backbone of module loading in Node.js, setting the stage for the common pitfalls and best practices that come next. But before getting into those, it’s crucial to grasp that require is not just a function call but a sophisticated mechanism that handles resolution, wrapping, execution, caching, and export management seamlessly behind the scenes.

Now, imagine a scenario where you want to create a singleton using require’s caching:

/* singleton.js */
let count = 0;

module.exports = {
  increment() {
    count++;
  },
  getCount() {
    return count;
  }
};

In multiple files, requiring this module will refer to the same instance:

const configA = require('./config');
const configB = require('./config');

console.log(configA === configB); // true

This shared state across module boundaries is powerful but requires careful design to avoid accidental coupling or state leaks.

Sometimes you might want to force a module to reload, bypassing the cache:

const configA = require('./config');
const configB = require('./config');

console.log(configA === configB); // true

However, this can cause inconsistent state if other parts of your app still hold references to the old module exports, so use with caution.

The require mechanism also supports loading native add-ons, compiled binary modules with the .node extension. These are loaded directly by Node’s C++ runtime, extending the platform with high-performance capabilities. While less common in everyday JavaScript code, understanding that require is the universal loader for JavaScript, JSON, and native binaries explains its central role in the Node.js ecosystem.

Of course, the introduction of ES Modules in Node.js has started to shift the landscape, but require remains deeply ingrained and relevant, especially in existing codebases and tooling. Knowing how require works at this level gives you a foundation to understand compatibility layers, hybrid module systems, and transition strategies.

This foundational understanding is important before moving on to the common pitfalls that trip up many developers when importing modules, such as path mistakes, caching quirks, or circular dependencies that manifest

Common pitfalls when importing modules with require

in subtle and hard-to-debug ways.

One frequent pitfall arises from incorrect path specification. For example, forgetting the leading ./ or ../ in relative imports causes Node.js to treat the import as a package name rather than a file path. This leads to errors like:

Error: Cannot find module 'myModule'

when what you actually intended was a local file.

Another common mistake is confusing exports and module.exports. Since exports is simply a reference to module.exports at the start of the module, reassigning exports breaks this link and results in an empty exported object:

/* broken.js */
exports = {
  greet() {
    console.log('Hello');
  }
};

/* works.js */
module.exports = {
  greet() {
    console.log('Hello');
  }
};

When requiring broken.js, you get an empty object because the reassignment of exports does not affect module.exports, which is what Node.js actually returns.

Circular dependencies also cause headaches. Consider modules A and B that require each other:

/* A.js */
const B = require('./B');
module.exports = {
  name: 'Module A',
  bName: B.name
};

/* B.js */
const A = require('./A');
module.exports = {
  name: 'Module B',
  aName: A.name
};

This setup results in B.aName being undefined because when B requires A, A hasn’t finished exporting yet and provides a partial object. This partial loading can cause runtime errors if you expect all exports to be fully initialized immediately.

To mitigate circular dependency issues, you can refactor shared logic into a third module or delay access to imported values until after module initialization:

/* A.js */
const B = require('./B');
module.exports = {
  name: 'Module A',
  getBName() {
    return B.name;
  }
};

/* B.js */
const A = require('./A');
module.exports = {
  name: 'Module B',
  getAName() {
    return A.name;
  }
};

Here, functions defer evaluation, avoiding access to incomplete exports during loading.

Another subtle trap is mutating cached modules inadvertently. Since require returns the cached exports object, changes to it affect all importers. For example:

/* settings.js */
module.exports = {
  debug: false
};

/* app.js */
const settings = require('./settings');
settings.debug = true;

/* logger.js */
const settings = require('./settings');
console.log(settings.debug); // true

If you intended settings to be immutable or isolated, this shared mutation can cause unexpected side effects across your app.

Beware also of mixing ESM import syntax with CommonJS require in the same file without proper interop. Trying to require an ES Module or import a CommonJS module without default exports can lead to undefined or empty objects. Node.js provides compatibility flags and interop helpers, but these add complexity and often trip developers up.

Additionally, when requiring JSON files, a common oversight is to assume changes to the JSON on disk will be reflected immediately. Because JSON modules are cached just like JavaScript modules, any changes to the file after the first load will be ignored unless you clear the cache manually:

const config = require('./config.json');
// ... later, config.json changes on disk
delete require.cache[require.resolve('./config.json')];
const updatedConfig = require('./config.json');

Without cache invalidation, your app continues using stale configuration data.

Finally, when working with native add-ons (.node files), loading failures can be cryptic since these modules depend on binary compatibility and correct build steps. A missing or incompatible native module will cause runtime errors that may seem unrelated to require usage but ultimately stem from the same loading mechanism.

In short, the common pitfalls revolve around incorrect path resolution, misunderstanding exports vs module.exports, circular dependencies, cache side effects, ESM/CommonJS interop issues, JSON caching behavior, and native module complexities. Recognizing these traps early will save hours of debugging and improve your module management strategy.

Next, ponder how to structure your imports and modules to avoid these pitfalls and maintain clarity and scalability in your codebase.

Best practices for structuring module imports in Node.js

One of the best practices when structuring module imports in Node.js is to always use explicit relative paths for your local modules. This means prefixing paths with ./ or ../ rather than relying on bare specifiers for your own files. Doing so prevents ambiguity and ensures Node’s resolver doesn’t mistakenly search node_modules for a package that doesn’t exist.

For example, prefer:

const utils = require('./utils');

over:

const utils = require('utils'); // error unless utils is a package

Another important convention is to group and order your imports consistently. Start with built-in Node.js core modules, followed by external packages from node_modules, then your internal modules. This makes the dependencies clear at a glance and helps maintain readability:

const fs = require('fs');
const express = require('express');

const config = require('./config');
const utils = require('./lib/utils');

Grouping imports visually also aids in spotting unused dependencies or potential circular references.

When exporting from modules, prefer using module.exports directly if you intend to export a single function, class, or object, rather than mutating exports. This reduces confusion and potential bugs related to the exports alias:

/* good.js */
module.exports = function initializeApp() {
  // initialization logic
};

For modules exporting multiple named values, attach them as properties on exports or module.exports:

/* math.js */
exports.add = (a, b) => a + b;
exports.subtract = (a, b) => a - b;

Consistency in export style across your codebase is key to predictable imports and easier refactoring.

To avoid circular dependencies, consider organizing shared logic into pure utility modules that do not depend on other parts of your application. This way, modules can require these utilities without creating cycles. When circular dependencies are unavoidable, defer access to imported values by wrapping them in functions or using lazy getters:

/* A.js */
const B = require('./B');
module.exports = {
  getBName() {
    return B.name;
  }
};

This approach delays the evaluation of the imported property until runtime, ensuring the required module has finished loading.

Use descriptive and consistent naming for your modules and files. Avoid vague names like index.js buried deep in directories without clear context. Instead, use explicit filenames like userController.js or databaseClient.js to clarify intent. This reduces confusion when you import modules and makes the codebase easier to navigate.

Where possible, keep your modules small and focused on a single responsibility. This modularity improves reusability and testability. It also reduces the complexity of dependency graphs, making require resolution more simpler and less prone to circular references.

For configuration files, prefer using JSON or JavaScript modules exporting plain objects. When importing JSON, remember that it is cached like any module, so if your app requires dynamic configuration reloads, implement cache invalidation explicitly:

function loadConfig() {
  delete require.cache[require.resolve('./config.json')];
  return require('./config.json');
}

const config = loadConfig();

This pattern allows you to refresh configuration at runtime without restarting the process.

In larger projects, ponder centralizing module paths using package.json _moduleAliases or tools like module-alias to create custom import paths. This reduces deep relative path hell and improves maintainability:

/* package.json */
{
  "_moduleAliases": {
    "@utils": "src/utils",
    "@models": "src/models"
  }
}

const utils = require('@utils');

This approach requires setup but pays off in cleaner import statements and less fragile path management.

Finally, keep in mind that require is synchronous. If your application grows to include many modules, especially large ones, think lazy loading modules only when needed to enhance startup time. For example:

function useHeavyModule() {
  const heavy = require('./heavyModule');
  heavy.doWork();
}

Lazy requiring modules inside functions delays the cost of loading until the moment the code path is executed, which can improve perceived performance and memory usage.

Best practices for structuring module imports revolve around clarity, consistency, and cautious management of dependencies and caching. Explicit paths, consistent export styles, avoiding circular dependencies, and thoughtful module boundaries create a maintainable and performant codebase that leverages Node.js’s module system effectively.