From 50508f9b18051761ec466de85cf0ecbee3130165 Mon Sep 17 00:00:00 2001 From: Max Black Date: Wed, 3 Dec 2025 15:11:40 -0800 Subject: [PATCH] docs(package-json): add documentation for type field (#8793) ## Description This PR adds documentation for the `type` field in package.json, which controls whether Node.js treats .js files as ES modules or CommonJS modules. ## Changes - Added a new section documenting the `type` field - Explained the two possible values: `module` and `commonjs` - Provided examples for both module types - Added a note about .mjs and .cjs file extensions - Linked to Node.js official documentation ## Fixes Closes #8376 ## Context The `type` field is a crucial part of package.json for modern Node.js projects, especially with the widespread adoption of ES modules. As reported in issue #8376, this field was not documented in npm's package.json reference, which caused confusion for developers trying to understand how to configure their packages for ESM or CommonJS. This documentation clarifies: 1. How to enable ES modules in a package (`"type": "module"`) 2. How to explicitly use CommonJS (`"type": "commonjs"`) 3. The default behavior when `type` is omitted (CommonJS) 4. That file extensions (.mjs/.cjs) override the type field ## Type of Change - [x] Documentation update Co-authored-by: Max Black --- docs/lib/content/configuring-npm/package-json.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md index dfecb8a4777ad..27aeaf9f22176 100644 --- a/docs/lib/content/configuring-npm/package-json.md +++ b/docs/lib/content/configuring-npm/package-json.md @@ -335,6 +335,12 @@ For most modules, it makes the most sense to have a main script and often not mu If `main` is not set, it defaults to `index.js` in the package's root folder. +### type + +The `type` field defines how Node.js should interpret `.js` files in your package. This field is not used by npm. + +See the [Node.js documentation on the type field](https://nodejs.org/api/packages.html#type) for more information. + ### browser If your module is meant to be used client-side the browser field should be used instead of the main field.