Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: package.json docs #7962

Closed
wants to merge 4 commits into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 46 additions & 10 deletions docs/lib/content/configuring-npm/package-json.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
{
Expand All @@ -209,18 +213,23 @@ 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
{
"author": "Barney Rubble <[email protected]> (http://barnyrubble.tumblr.com/)"
}
```

Both email and url are optional either way.
### contributors

Contributors consists of an an array of [authors](#author).

### maintainers (deprecated)

Use [`contributors`](#contributors) instead.

npm also sets a top-level "maintainers" field with your npm user info.
The `maintainers` field in package.json is ignored by npm. It is only used internally by npm for package payloads.

### funding

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.com](https://npmjs.com/typescript) to display `ts` badge for a given package.

### typings

Alias of [types](#types).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think this is actually a typescript-deprecated field from TS < v3 or v2.

Copy link
Contributor Author

@reggi reggi Dec 5, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah i didn't know about it until today.

From the ts docs:

Note that the "typings" field is synonymous with types, and could be used as well.

We do honor it.

If you can find deprecation docs I'm down to add (deprecation). I still think it should be documented.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html implies it's just an alias, so maybe it's not actually deprecated.


### workspaces

The optional `workspaces` field is an array of file patterns that describes
Expand Down
Loading