Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 36 ยท Packages and package.json

Entry Points, exports and type

Learn how main, module, type and the exports map decide what import and require load from a package, including conditional exports, subpath exports and dual ESM/CommonJS packages.

A package is only useful if others can import it, and package.json decides what they get. Older packages used main; modern ones use exports, which is stricter and can serve different files to import and require. This lesson shows how each field works, and you will run real ES module and CommonJS code to see the differences.

main: the classic entry point

main names one file. When someone writes require('my-lib') or import 'my-lib', Node loads that file. Without main, Node falls back to index.js at the package root.

JSON
{ "name": "my-lib", "main": "./lib/index.js" }

main has one limitation: it points at a single file and anyone can still deep-import anything, such as my-lib/lib/internal/secret.js, even if you consider it private.

type: ESM or CommonJS?

.js files can mean two module systems. The type field decides which:

  • "type": "commonjs" (the default): .js is CommonJS (require, module.exports).
  • "type": "module": .js is an ES module (import, export).

Whatever type says, the extensions .mjs (always ESM) and .cjs (always CommonJS) override it. The scope is every file under the folder containing that package.json, until a nearer package.json is found.

Node.js ESM facts you can observe

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

exports: the modern entry map

exports replaces main for new code. It is a map from subpaths to files and, when present, blocks everything not listed.

JSON
{
  "name": "my-lib",
  "type": "module",
  "exports": {
    ".": "./dist/index.js",
    "./tools": "./dist/tools.js",
    "./package.json": "./package.json"
  }
}

With that map, import 'my-lib' and import 'my-lib/tools' work, but import 'my-lib/dist/internal.js' fails with ERR_PACKAGE_PATH_NOT_EXPORTED. You decide your public API.

Conditional exports

A target can be an object keyed by conditions. Node picks the first matching key in order. Common conditions: import, require, node, browser, types, default.

JSON
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "default": "./dist/index.js"
    }
  }
}

Put types first (TypeScript reads top to bottom) and default last as a fallback.

Node.js A small exports resolver (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Subpath patterns and imports

Wildcards expose many files with one line: "./features/*": "./dist/features/*.js" makes my-lib/features/a point at dist/features/a.js. A separate field, imports, defines private aliases starting with #, usable only inside the package:

JSON
{ "imports": { "#db": "./src/db/index.js" } }

Then import db from '#db' works anywhere in your package, without long relative paths.

Dual packages

Some consumers still use require, others import. Libraries therefore ship both builds and list them under import and require conditions, as above. The danger is the dual package hazard: a program that loads both builds gets two separate copies of your module's state. Keep state out of module scope, or make one build a thin wrapper around the other. Recent Node versions can also require() ES modules that have no top-level await, which eases the problem.

Checking an export map before you publish

Node.js Do all export targets exist?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Combine this habit with npm pack --dry-run so that every exported file is actually in the tarball (package.json Fields).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does "type": "module" change?

    With type module, .js files in that package scope are treated as ES modules.
  2. 2. What happens to a deep import of a file not listed in exports?

    exports defines the complete public surface of the package.
  3. 3. In conditional exports, where should the default condition go?

    Conditions are tried in order, so default goes last.
  4. 4. What is the dual package hazard?

    Each build is a separate module instance with its own state.

Summary

  • main is a single legacy entry; exports is the modern, strict map.
  • type sets how .js is interpreted; .mjs and .cjs always win.
  • Conditional exports serve import, require, types and more from one subpath.
  • imports with # aliases keep private shortcuts inside a package.
  • Verify that every export target exists before publishing.

Next: The npm Registry and Package Names