Packages in Node.js

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.