package.json "type" & exports

package.json fields "type" and "exports" define how Node resolves your package - they replace ambiguous main fields and lock down internal files from deep imports.

Recipe

{
  "name": "@acme/billing-sdk",
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./package.json": "./package.json"
  },
  "files": ["dist"]
}

When to reach for this:

• Publishing internal monorepo packages to npm or Verdaccio
• Blocking consumers from import '@acme/pkg/src/internal/foo.js'
• Dual CJS/ESM libraries during ecosystem transition
• Tooling that respects exports (TypeScript 5.6+, webpack 5, Node 24)

Working Example

{
  "name": "@acme/shared-types",
  "type": "module",
  "exports": {
    ".": "./dist/index.js",
    "./users": "./dist/users.js",
    "./package.json": "./package.json"
  },
  "imports": {
    "#internal/*": "./src/internal/*.js"
  }
}

// consumer.ts
import { UserDto } from '@acme/shared-types/users';

// inside @acme/shared-types package only
import { helper } from '#internal/helper.js';

What this demonstrates:

• "exports" whitelist is the only importable surface - deep paths fail without a match
• Subpath exports (./users) publish focused entry points without barrel bloat
• "imports" field maps internal aliases (#internal/*) for package-private shortcuts
• Explicit "./package.json" export when tools need to read metadata

Deep Dive

How It Works

• "type": "module" - .js files are ESM; use .cjs for intentional CommonJS.
• "exports" - object keys are public subpaths; values are target files or conditional objects.
• Conditions - "import", "require", "node", "default" pick variants per resolver.
• No match, no access - importing unexported paths throws ERR_PACKAGE_PATH_NOT_EXPORTED.

Common export shapes

TypeScript Notes

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  }
}

Pair "types" condition (or typesVersions) so consumers get typings matching the export.

Gotchas

• Only setting main without exports - modern tools may still allow deep imports. Fix: add "exports" to encapsulate.
• Forgetting .js in export targets - must point to files that exist after build. Fix: CI check that dist matches exports.
• Dual package hazard - separate import and require instances break instanceof. Fix: prefer ESM-only for app packages; document for libraries.
• Wildcard exports too broad - "./src/*" exposes internals. Fix: export only dist artifacts.
• Monorepo workspace protocol without building - consumers resolve to TS source incorrectly. Fix: exports point to compiled dist in published packages.

Alternatives

FAQs

Related

• ES Modules (import) - ESM syntax consuming exports
• Module Resolution Algorithm - resolution order
• CJS ↔ ESM Interop - dual condition exports
• Sharing Types with Frontend - monorepo packages

External Related Links

• Node.js API Documentation - Complete reference for core modules and APIs.
• npm Official Website & Registry - Package search, publishing, and documentation.
• npm CLI Documentation - Official docs for the npm CLI.
• Node.js Cookbook, 5th Edition - Practical server-side recipes.
• Node.js Design Patterns, 4th Edition - Production-grade application patterns.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.