LogoفارسیFA

Packages in Node.js

A package in Node.js is a folder tree described by a package.json file. The package consists of the folder containing the package.json file and all subfolders until another folder with its own package.json or a node_modules folder is encountered. The package.json file defines how .js files are interpreted (as CommonJS or ES modules), specifies entry points, and controls exports and imports. Node.js supports both CommonJS and ES modules, and package authors can use fields like type, main, exports, and imports to configure behavior.

package.jsontype: "module" / "commonjs"main و exportssubpath exports / imports

~2 min read • Updated Dec 30, 2025

1. Package Definition


A package is a folder containing a package.json file. All subfolders belong to the package until another package.json or a node_modules folder is found.


2. Determining Module System


  • .mjs files are always ES modules.
  • .cjs files are always CommonJS.
  • .js files depend on the type field in package.json.
  • If no type field exists, .js files default to CommonJS.

3. Syntax Detection


If a .js file lacks a type field, Node.js inspects the code. ES module syntax (import/export, import.meta, top-level await) forces the file to be treated as an ES module.


4. Resolution and Loading


  • require(): CommonJS resolution supports folders as modules and tries extensions (.js, .json, .node).
  • import: ES module resolution requires explicit extensions and supports URLs.

5. The type Field


The type field in package.json defines how .js files are interpreted:


// package.json
{
  "type": "module"
}

6. Entry Points


  • main: Legacy field defining the default entry point.
  • exports: Modern field allowing multiple entry points and encapsulation.

7. Subpath Exports


Custom subpaths can be defined in exports:


// package.json
{
  "exports": {
    ".": "./index.js",
    "./submodule.js": "./src/submodule.js"
  }
}

8. Subpath Imports


The imports field defines private internal mappings, starting with #:


// package.json
{
  "imports": {
    "#dep": "./dep-polyfill.js"
  }
}

9. Conditional Exports


Different paths can be defined depending on conditions:


// package.json
{
  "exports": {
    "import": "./index-module.js",
    "require": "./index-require.cjs"
  }
}

10. Self-Referencing


A package can import itself using its name, provided exports is defined:


// package.json
{
  "name": "a-package",
  "exports": {
    ".": "./index.mjs"
  }
}

Conclusion


Packages in Node.js are managed through package.json, which controls module type, entry points, and exports. Proper use of type, exports, and imports ensures predictable, secure, and compatible packages across modern tools and environments.


Written & researched by Dr. Shahin Siami

Next Article