From 1554bab7a5a3d3fe2175b3c89690ccd5b41b8d12 Mon Sep 17 00:00:00 2001 From: reggi Date: Thu, 5 Dec 2024 15:13:45 -0500 Subject: [PATCH 1/4] fix: package.json docs --- .../content/configuring-npm/package-json.md | 54 +++++++++++++++---- 1 file changed, 45 insertions(+), 9 deletions(-) diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md index e09d50f02b635..8695d509a4da4 100644 --- a/docs/lib/content/configuring-npm/package-json.md +++ b/docs/lib/content/configuring-npm/package-json.md @@ -15,6 +15,8 @@ settings described in [`config`](/using-npm/config). ### name +> See Node.js documentation on `name` [here](https://nodejs.org/api/packages.html#name). + If you plan to publish your package, the *most* important things in your package.json are the name and version fields as they will be required. The name and version together form an identifier that is assumed to be @@ -195,11 +197,13 @@ unpublished package under any terms: Consider also setting `"private": true` to prevent accidental publication. -### people fields: author, contributors +### licenses (deprecated) + +See [license](#license). + +### author -The "author" is one person. "contributors" is an array of people. A -"person" is an object with a "name" field and optionally "url" and "email", -like this: +The "author" is one person. A "person" is an object with a "name" field and optionally "url" and "email", like this: ```json { @@ -209,8 +213,7 @@ like this: } ``` -Or you can shorten that all into a single string, and npm will parse it for -you: +Or you can shorten that all into a single string, and npm will parse it for you: ```json { @@ -218,9 +221,15 @@ you: } ``` +### contributors + +Contributors consists of an an array of [authors](#author). + Both email and url are optional either way. -npm also sets a top-level "maintainers" field with your npm user info. +### maintainers (deprecated) + +The `maintainers` when set in package.json is not awknowledged or used by npm. `maintainers` is used internally by npm on package-like payloads. ### funding @@ -341,10 +350,16 @@ These can not be included. ### exports -The "exports" provides a modern alternative to "main" allowing multiple entry points to be defined, conditional entry resolution support between environments, and preventing any other entry points besides those defined in "exports". This encapsulation allows module authors to clearly define the public interface for their package. For more details see the [node.js documentation on package entry points](https://nodejs.org/api/packages.html#package-entry-points) +See Node.js documentation on `exports` [here](https://nodejs.org/api/packages.html#exports). + +### imports + +See Node.js documentation on `imports` [here](https://nodejs.org/api/packages.html#imports). ### main +> See Node.js documentation on `main` [here](https://nodejs.org/api/packages.html#main). + The main field is a module ID that is the primary entry point to your program. That is, if your package is named `foo`, and a user installs it, and then does `require("foo")`, then your main module's exports object will @@ -893,13 +908,16 @@ This file contains the dependencies `renderized` and `super-streams` which can be installed in a new project by executing `npm install awesome-web-framework-1.0.0.tgz`. Note that the package names do not include any versions, as that information is specified in `dependencies`. - If this is spelled `"bundledDependencies"`, then that is also honored. Alternatively, `"bundleDependencies"` can be defined as a boolean value. A value of `true` will bundle all dependencies, a value of `false` will bundle none. +### bundledDependencies (deprecated) + +Is honored by npm as alias of [bundleDependcies](#bundleDependencies). + ### optionalDependencies If a dependency can be used, but you would like npm to proceed if it cannot @@ -1191,6 +1209,24 @@ default. See [`config`](/using-npm/config) to see the list of config options that can be overridden. +### type + +> See Node.js documentation on `type` [here](https://nodejs.org/api/packages.html#type). + +Property that governs if Node.js will interpret package as [CommonJS (cjs)](https://nodejs.org/docs/latest/api/modules.html#modules-commonjs-modules) or [ECMAScript Module (esm)](https://nodejs.org/docs/latest/api/esm.html). + +When this field is undefined it is interpreted as the value `commonjs`. + +### types + +See TypeScript documentation on `types` [here](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html). + +Used by npmjs.org to display `ts` badege for a given package. + +### typings + +Alias of [types](#types). + ### workspaces The optional `workspaces` field is an array of file patterns that describes From a8a90de8f380425ae24e8339093b9d8d76a6b466 Mon Sep 17 00:00:00 2001 From: Reggi Date: Thu, 5 Dec 2024 15:19:49 -0500 Subject: [PATCH 2/4] fix: typo badge Co-authored-by: Jordan Harband --- docs/lib/content/configuring-npm/package-json.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md index 8695d509a4da4..6789326012814 100644 --- a/docs/lib/content/configuring-npm/package-json.md +++ b/docs/lib/content/configuring-npm/package-json.md @@ -1221,7 +1221,7 @@ When this field is undefined it is interpreted as the value `commonjs`. See TypeScript documentation on `types` [here](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html). -Used by npmjs.org to display `ts` badege for a given package. +Used by npmjs.org to display `ts` badge for a given package. ### typings From 826845e93e27e1fee8523b0656ddc8ee6d1f8180 Mon Sep 17 00:00:00 2001 From: reggi Date: Thu, 5 Dec 2024 15:21:37 -0500 Subject: [PATCH 3/4] fix: .org to .com --- docs/lib/content/configuring-npm/package-json.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md index 6789326012814..760bb52a88078 100644 --- a/docs/lib/content/configuring-npm/package-json.md +++ b/docs/lib/content/configuring-npm/package-json.md @@ -1221,7 +1221,7 @@ When this field is undefined it is interpreted as the value `commonjs`. See TypeScript documentation on `types` [here](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html). -Used by npmjs.org to display `ts` badge for a given package. +Used by [npmjs.com](https://npmjs.com/typescript) to display `ts` badge for a given package. ### typings From 739df1ffdae9d9f55bd1910ae494221aa490cc2c Mon Sep 17 00:00:00 2001 From: reggi Date: Thu, 5 Dec 2024 16:09:08 -0500 Subject: [PATCH 4/4] fix: maintainers --- docs/lib/content/configuring-npm/package-json.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md index 760bb52a88078..a9cfef67864a4 100644 --- a/docs/lib/content/configuring-npm/package-json.md +++ b/docs/lib/content/configuring-npm/package-json.md @@ -225,11 +225,11 @@ Or you can shorten that all into a single string, and npm will parse it for you: Contributors consists of an an array of [authors](#author). -Both email and url are optional either way. - ### maintainers (deprecated) -The `maintainers` when set in package.json is not awknowledged or used by npm. `maintainers` is used internally by npm on package-like payloads. +Use [`contributors`](#contributors) instead. + +The `maintainers` field in package.json is ignored by npm. It is only used internally by npm for package payloads. ### funding