npm / documentation

Documentation for the npm registry, website, and command-line interface.

npm Documentation

This is the documentation for https://docs.npmjs.com/.

This repository contains the content for our documentation site, and the GitHub Actions workflows that generate the site itself.

Quick start

1. npm install to download gatsby, our theme, and the dependencies
2. npm run develop: starts the test server at http://localhost:8000.
3. Update the content - it's Mdx, which is like markdown - in the content directory.
4. Review your content at http://localhost:8000. (Gatsby watches the filesystem and will reload your content changes immediately.)
5. Once you're happy, commit it and open a pull request at https://github.com/npm/documentation.
6. A CI workflow run will publish your PR to a GitHub Preview Page.
7. Once the content is reviewed, merge the pull request. That will deploy the site.

Do you want to know more? Check out our contributing guide.

License

The npm product documentation in the content, and static folders are licensed under a CC-BY 4.0 license.

All other code in this repository is licensed under a MIT license.

When using the GitHub logos, be sure to follow the GitHub logo guidelines.

documentation's Issues

[BUG] CLI’s non-index pages do not redirect to “default” version

What / Why

Non-index pages for the npm CLI docs do not currently redirect to the “default” version when omitting the version number (e.g., https://docs.npmjs.com/cli/commands/npx). Because of this, no permalink is available for docs pages to the most relevant version of particular commands (amongst other versioned resources). If this previously worked, those links are currently broken (see below).

When

• Malfunctioning (?) for at least the past couple of months

Where

All versioned npm CLI documentation content on the website (npm/documentation repo) deeper than these indices:

• https://docs.npmjs.com/cli/v8/commands
• https://docs.npmjs.com/cli/v8/configuring-npm
• https://docs.npmjs.com/cli/v8/using-npm

How

Current Behavior

Currently, users are only redirected to the npm CLI’s “default” version of docs pages for the “index” pages (e.g., https://docs.npmjs.com/cli/commands redirects to https://docs.npmjs.com/cli/v8/commands/).

Steps to Reproduce

1. Attempt to visit the “default” version of any page deeper than an “index” page by omitting the version number entirely (e.g., https://docs.npmjs.com/cli/commands/npx)

2. Expect to be redirected to the npm CLI’s “default” version of the docs page (e.g., https://docs.npmjs.com/cli/v8/commands/npx)

3. See the 404 error page instead (https://docs.npmjs.com/cli/commands/npx)

   

Expected Behavior

Be redirected to the npm CLI’s “default” version for docs page deeper than “index” pages when omitting the version number from the URL. Otherwise, we’d currently have to update links to, e.g., particular commands, every new major version of the npm CLI to avoid our links going stale.

Who

• @darcyclarke
• @ruyadorno
• @MylesBorins

References

• @rauschma’s Tweet inquiring about this functionality
• @ethomson’s Tweet classifying it as a bug

[FEATURE] Improve documentation for created / deleting access tokens

What / Why

Current documentation is lacking and doesn't have details about doing this entire flow from npmjs.com (only talks about the CLI.

We should fix this!

When

• n/a

Where

• n/a

How

Current Behavior

• n/a

Expected Behavior

• n/a

Who

• n/a

References

• n/a

Update npm mirror url in the documentation

Hey folks.

The documentation here https://docs.npmjs.com/cli/v9/using-npm/registry states that the mirror url is https://skimdb.npmjs.com/registry. however, as per https://github.com/npm/registry/blob/master/docs/REPLICATE-API.md#overview, it states that skimdb is deprecated in favor of https://replicate.npmjs.com.

Can you guys please confirm which mirror is the accurate and update the documentation here

Thanks.

[BUG] Package search rank criteria states that npm uses npms - it is not

What / Why

content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx is outdated. npm no longer uses npms for scoring. And there is no up-to-date information on how npm is scoring packages anywhere.

Where

https://docs.npmjs.com/searching-for-and-choosing-packages-to-download

[QUESTION] Should the package name guideline mention that package name cannot contain capital letters?

What / Why

The package name guideline does not seem to mention that the package name cannot contain capital letters. Should it be added to the guidelines? I'll be happy to do that.

Where

• https://docs.npmjs.com/package-name-guidelines

Who

• n/a

References

• n/a

[BUG] <title>

What / Why

n/a

When

• n/a

Where

• n/a

How

Current Behavior

• n/a

Steps to Reproduce

• n/a

Expected Behavior

• n/a

Who

• n/a

References

• n/a

[BUG] <title>

What / Why

n/a

When

• n/a

Where

• n/a

How

Current Behavior

• n/a

Steps to Reproduce

• n/a

Expected Behavior

• n/a

Who

• n/a

References

• n/a

[FEATURE] Document enviroment variables set by `npx` and `npm exec`

What / Why

npx sets many enviroment variables.

It can be seen by running command:

meld <(npx -c 'env | sort') <(env | sort) <(npm exec -c 'env | sort')

How

Current Behavior

There is no documentation on this.

Expected Behavior

It should be documented.

Who

• n/a

References

• n/a

[BUG] copy button hiding text

What / Why

The text at the end of each code block is cut off by the copy button.

image from here

The full line is http.createServer(...).listen(process.env.npm_package_config_port), but the reader can only see http.createServer(...).listen(process.env.npm_package_config.

Where

• any block where the text fills the entire line

How

Current Behavior

• copy button covers last part of line in code block

Steps to Reproduce

• go to any block where the text fills the entire line on the documentation website

Expected Behavior

• the copy button should not hide any text or should only show on hover (this is what GitHub does)

[BUG] Outdate links and tutorial

What / Why

The repository link to automatically update npm on windows is deprecated and read-only.

https://github.com/felixrieseberg/npm-windows-upgrade

The link for "edit your Windows installation's PATH" is from 10 years ago...I say that just to let you know

When

https://docs.npmjs.com/try-the-latest-stable-version-of-npm

When I follow the tutorial to keep npm up to date on Windows

Where

When I'm following the tutorial to keep npm up to date on Windows

How

Current Behavior

The repository link to automatically update npm on windows is deprecated and read-only.

https://github.com/felixrieseberg/npm-windows-upgrade

The link for "edit your Windows installation's PATH" is from 10 years ago...I say that just to let you know

Steps to Reproduce

Go to: https://docs.npmjs.com/try-the-latest-stable-version-of-npm and click on the links to keep Windows updated

Expected Behavior

It should lead to updated material that can be used with Windows 10 to 11 and indicate what Windows is for

Who

n/a

References

n/a

[BUG] package.json vars documentation seems outdated

What / Why

Apparently many package.json vars have been removed since v6 (reference). But docs are still pointing to them here:

You can access these variables in your code with process.env.npm_package_name and process.env.npm_package_version, and so on for other fields.

and here:

Objects are flattened following this format, so if you had {"scripts":{"install":"foo.js"}} in your package.json, then you'd see this in the script:
process.env.npm_package_scripts_install === "foo.js"

References

• npm/cli#2609
• https://docs.npmjs.com/cli/v8/using-npm/scripts#packagejson-vars
• https://docs.npmjs.com/cli/v8/using-npm/scripts#current-lifecycle-event

[BUG] <title>

What / Why

n/a

When

• n/a

Where

• n/a

How

Current Behavior

• n/a

Steps to Reproduce

• n/a

Expected Behavior

• n/a

Who

• n/a

References

• n/a

[BUG] Link to field `description` on article `package.json` is broken

What / Why

When

Scroll down to the section description (not Description above)

Where

https://docs.npmjs.com/cli/v7/configuring-npm/package-json

How

URLs don't care about casing so the HTML anchor is ambiguous. Interestingly, the ToC uses a better strategy for creating unique anchors but the HTML content itself does not adopt this strategy.

Current Behavior

Cannot create a valid link to the field description

Steps to Reproduce

Option 1: Click here

Option 2: Click on description here

Expected Behavior

Option 1: Link is invalid
Option 2: Link refers to wrong section

Olp****

          Olp****

Originally posted by @Saberhabeelshohdy in #365 (comment)

[BUG] Internal links in `downloading-and-installing-node-js-and-npm#overview` not working

What / Why

The 3 links under the Overview heading in Downloading and installing Node.js and npm are not working as intended.

Information about how npm handles malicious versions of otherwise benign packages

I think the information regarding how npm handles malicious versions of otherwise benign packages could be improved in the documentation here:
https://docs.npmjs.com/reporting-malware-in-an-npm-package#how-npm-security-handles-malware.

Based on this issue for the ua-parser-js package it seems like the version got unpublished.

Does the npm security team recommend unpublishing? This removes the history and explanation from the npm website.

[BUG] Readme is often hidden

Readme is often hidden.
You can access any npm package, which will have a chance to trigger. For example: https://www.npmjs.com/package/rxjs
Actually it has reademe file.

discussion link: Readme is often hidden

[FEATURE] Add more fields to the `package.json` documentation

When creating JS libraries, the package.json documentation on docs.npmjs.com is one of the most helpful resources to me. However it is far from complete, there are many fields that aren't documented there, but they are often needed in order to make a working library. These are for example:

• exports – which module should be used when using module requests like import "package/sub/path", src: [1], [2]
• types and typesVersions – type declarations for TS, src: [3]
• module – the main entry point for an ESM project, src: [4], [5], [6]
• type – whether the main entrypoint is whether all .js files are a CommonJS or ES Module, src: [7]

While these options aren't directly used by the NPM CLI, I think it would be great to include them, since they are a de-facto standard shared by many different systems. Should I make a PR that adds them?

[FEATURE] add “Edit on GitHub” button to pages

What / Why

As we work on getting specific areas of the docs up to date, it would be helpful to link directly from a docs page to where the file lives in GitHub.

This would enable everyone to more easily find and flag issues with the docs.

Explanation of "idealTree" and "reify"

What / Why

When installing packages via npm the console will print a lines like
idealTree:[package-name]
and
reify:[package-name]
What do those terms mean? What is npm doing exactly?

[BUG] 404 error while publishing npm package

What / Why

Documentation isn't complete and can lead to a 404 error

When

• using the npm publish command

References

• The documentation should be updated to mention npm login before npm publish
  documentation/content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-private-packages.mdx

npm WARN config global `--global`, `--local` are deprecated. Use `--location=global` instead.[BUG] <title>

What / Why

-->

n/a

When

• n/a

Where

• n/a

How

Current Behavior

• n/a

Steps to Reproduce

• n/a

Expected Behavior

• n/a

Who

• n/a

References

• n/a

[BUG] Removed files not being deleted for CLI vendored documentation

What / Why

npm/cli#2559 removed https://github.com/npm/documentation/blob/main/content/cli/v7/using-npm/disputes.md but it still remains in the repo. It seems like removed files are not being removed from the vendored directory.

Don't autofocus the npm version dropdown

The npm version dropdown:

is focused when the page loads:

documentation/theme/src/components/variant-select.js

Line 66 in f8069dd

<ActionMenu.Button autofocus="true" aria-label={ariaLabelMenuButton}>

This is user-hostile and prevents scrolling with spacebar when the page loads. If the intent was to make it easy to change the selected npm version with the keyboard (which seems a bizarre choice, frankly, I'm not sure I ever remember doing that, and other popular projects (e.g. the Python documentation) don't autofocus their version selector elements), it's misguided – whilst pressing space opens the dropdown, it's not then possible to navigate the dropdown with standard keyboard controls like the arrow keys (or, as far as I can tell, with any keyboard controls at all: pressing tab just moves focus to the ToC).

This was added in 4505fce, as part of #303.

> - [Hello World!!!]

• [Hello World!!!]

Originally posted by @n012judge420 in https://github.com/ethereum/EIPs/issues/6814#issuecomment-1493102192

Originally posted by @n012judge420 in n012judge420/fuzzy-octo-umbrella#5 (comment)

```suggestion

    ```suggestion
    root = root.replace(/\/+$/g, '')

_Originally posted by @uzkjzjjz in https://github.com/npm/documentation/pull/352#discussion_r1056075665_
      

[BUG] Unclear unpublish policy

What / Why

The document unpublish.md (at content/policies/unpublish.mdx) does not specify whether the conditions are joined by conjunction or disjunction. To reduce confusion, it should be clarified by adding a word such as and or or or adding a clause you can unpublish a package that meets any of these conditions: or you can unpublish a package that meets all of these conditions:. Also, it seems like and is intended, not or.

This is the original:

Packages published more than 72 hours ago

Regardless of how long ago a package was published, you can unpublish a package that:

• no other packages in the npm Public Registry depend on
• had less than 300 downloads over the last week
• has a single owner/maintainer

These versions are more clear:

Packages published more than 72 hours ago

Regardless of how long ago a package was published, you can unpublish a package that:

• no other packages in the npm Public Registry depend on,
• had less than 300 downloads over the last week, and
• has a single owner/maintainer

Packages published more than 72 hours ago

Regardless of how long ago a package was published, you can unpublish a package that meets all of these conditions:

• no other packages in the npm Public Registry depend on
• had less than 300 downloads over the last week
• has a single owner/maintainer

(same as npm/policies#139)

When, Where, How, Current Behavior,Steps to Reproduce, Expected Behavior, Who, References

• n/a

[BUG] <title>

npm token list # What / Why

n/a

When

• n/a

Where

• n/a

How

Current Behavior

• n/a

Steps to Reproduce

• n/a

Expected Behavior

• n/a

Who

• n/a

References

• n/a

[FEATURE] Make CONTRIBUTING.md files mention the RFC/RRFC process for new features?

What / Why

New feature requests get opened by new contributors in the issue trackers of npm/cli, etc and closed mentioning that the RRFC process should be used instead. The first place I found the RRFC process mentioned was in the reason for closing feature requests, not in README.md or CONTRIBUTING.md in https://github.com/npm/cli/blob/latest/CONTRIBUTING.md

When

• n/a

Where

https://github.com/npm/cli/blob/latest/CONTRIBUTING.md
Various other repos in https://github.com/npm/

How

Current Behavior

No mention of RRFC process or what to do to request new features in README.md/CONTRIBUTING.md of npm/cli, and probably other repos.

(Some repos such as https://github.com/npm/npm-registry-fetch#contributing also have a 404 for their link to CONTRIBUTING.md "Contributors guide" https://github.com/npm/npm-registry-fetch/blob/main/CONTRIBUTING.md)

Expected Behavior

Add a section along the lines of:

New Features

New feature requests should be reported in the https://github.com/npm/rfcs/ repo instead of this repo. Please check if a similar feature request has been made already.

Who

• n/a

References

• n/a

[QUESTION] Delete organization by mistake

What / Why

Hello, I have a problem now. Add an organization and move the package to this organization, then accidentally delete the organization, and then the package is gone. Is there any way to recover?

n/a

Where

• n/a

Who

• n/a

References

• n/a

[BUG] Every time I use Chrome to log in to npmjs.com, it fails and I can only do it in Edge 😭

What / Why

The login on edge is normal, this problem has been following me for a long time,
I have changed several computers, I don't think it is a computer problem, it may be related to my account,
I want to know if there is a problem with my account or what the Chinese network firewall is doing to it? (but I already use VPN)

When

https://raw.githubusercontent.com/wangrongding/image-house/master/img/202207301430728.mp4

This is a video of my login steps, I can only use edge to login to npmjs.com for more than a year, it's really too uncomfortable.😭😭😭😭

My account number: wangrongding

Nothing should link to `npx` package on www.npmjs.com

I just opened npm/cli#5742 and #277.

Searching Google for "npx" brings up:
https://www.npmjs.com/package/npx
... as the first result. The "best link", the npx CLI command entry in the npm docs isn't in the first page of results (it's the 1st result on the 2nd page).

https://www.npmjs.com/package/npx is a bit cryptic. Following the link to GitHub goes to:
https://github.com/npm/npx
... which shows:

This repository has been archived by the owner. It is now read-only.

... up top. Scrolling down reveals:

⚠️ DEPRECATED: This project has been deprecated - npx is now part of the npm cli

... that leads to:
https://github.com/npm/cli
The sidebar gives the link to:
https://docs.npmjs.com/cli/
... and then you have to search for "npx" (or drill down into "CLI Commands"), and then finally, you get to:
https://docs.npmjs.com/cli/commands/npx

I'm not sure what can be done to improve this user experience, any ideas?

[Bug] link doesn't work when clicked

On this page, the third link to "Requiring two-factor authentication in your organization" doesn't do anything when clicked:

The target page does exist, but looking in Chrome DevTools shows there's some code that runs when you hover over the link just before clicking it, and that code is causing a stack overflow:

[BUG] Broken externally-linked URL https://docs.npmjs.com/files/package-locks

What / Why

The URL https://docs.npmjs.com/files/package-locks, linked to from other sites, 404s.

Looks like it used to redirect to https://docs.npmjs.com/cli/v6/configuring-npm/package-locks, as of https://web.archive.org/web/20201214093528/https://docs.npmjs.com/files/package-locks, but no longer did as of https://web.archive.org/web/20211126181007/https://docs.npmjs.com/files/package-locks.

And for some reason that topic is only available for 6.x?

P.S. This issue template seems entirely unhelpful for this documentation project.

When

• n/a

Where

• n/a

How

Current Behavior

• n/a

Steps to Reproduce

• n/a

Expected Behavior

• n/a

Who

• n/a

References

• n/a

Hola mundo

Hola que tal

[FEATURE] Top-level `requires` property in package-lock.json not describe on website

What / Why

The package-lock.json file contains a property called requires:

{
  "name": "foo",
  "version": "0.0.0",
  "lockfileVersion": 3,
  "requires": true, // <--- this one
  "packages": {

It existed in all versions of lockfileVersion (1, 2 and 3). Notice that I am now using version 3.

I do not know what its purpose is. Nor if it is a bug or not to exist in lockfileVersion: 3. But even so, it is not documented at https://docs.npmjs.com/cli/v8/configuring-npm/package-lock-json.

As a top-level property, it would be nice to describe it at https://docs.npmjs.com/cli/v8/configuring-npm/package-lock-json (for all versions that you can select in the dropdown).

Update screenshots on Account Settings

• Connected to https://github.com/npm/wubwub/issues/2365

Inside docs

Things to change inside Managing your profile

→ 📁 Updated screenshots.zip

Screenshots

Windows

Ji

[FEATURE] Gatsby I18n

What / Why

I propose to add an I18n system.

How

This could be implemented with the I18n plugins of Gatsby.

Expected Behavior

There could be a selector in the header.

References

• https://www.gatsbyjs.com/docs/how-to/adding-common-features/localization-i18n/

[BUG] using unknown tool in documentation

What / Why

The page: https://github.com/npm/documentation/blob/main/content/packages-and-modules/securing-your-code/verifying-the-pgp-signature-for-a-package-from-the-npm-public-registry.mdx (also this) contains example code and its impossible to execute that as it refers to an unknown command-line utility. The code:

http GET https://registry.npmjs.org/light-cycle | json "versions['1.4.3'].dist.npm-signature" > sig-to-check

The error: Command 'json' not found. Shouldn't be here jq? Or if there really exist some json cmd, please instruct on how to install it in the Prerequisites section of the same article.
Also http: Command 'http' not found. Assuming curl. Also add to Prerequisites.

n/a

When

execute: json shell or http shell

Where

bash(ubuntu).

How

typing command by keyboard

Current Behavior

• n/a

Steps to Reproduce

run this on any computer that doesn't have any json and http packages

Expected Behavior

jq? curl?

Who

linux user

References

• n/a

👋 I'm your friendly documentation robot, and I'm going to build your pull request on our staging site so that you can review it. If you push up subsequent commits, I'll rebuild your staging area (and when this pull request is closed, I'll clean that staging area up).

👋 I'm your friendly documentation robot, and I'm going to build your pull request on our staging site so that you can review it. If you push up subsequent commits, I'll rebuild your staging area (and when this pull request is closed, I'll clean that staging area up).

I'll let you know when I'm done! 🤖

Originally posted by @npm-docs-robot in #160 (comment)

[BUG] Git logo link not working!!

What / Why

I was surfing through the npm website. There is a Github logo in the footer that doesn't link to the repo.

When

whenever you open the website

Where

npm official website : npmjs.com

How

Current Behavior

inactive icon links

Expected Behavior

should link to this organization repo

Who

@everyone

References

check out the website npmjs.com

Is NPM a universal tool?

It may seem like an obvious query, but there is a great divergence between the content available on the web and the npm documentation itself with respect to the current reality and, in my opinion, this part affects what is known as javascript fatigue.

To explain better, I'll quote the readme of [npm package in npmjs.com]

Contrary to popular belief, npm is not in fact an acronym for "Node Package Manager"; It is a recursive bacronymic abbreviation for "npm is not an acronym"... The precursor to npm was actually a bash utility named "pm", which was the shortform name of "pkgmakeinst" - a bash function that installed various things on various platforms. If npm were to ever have been considered an acronym, it would be as "node pm" or, potentially "new pm".

Similarly, in the "about" of the official page, there is no mention of having a relationship with Node (except for the invitation to study at nodeschool).

Despite all this, as the documentation is read, the direct relationship of terminology associated with packages for Node becomes notable, which may make sense from a historical point of view, but today NPM contains in its There are many packages created for other execution environments, such as the browser or even DENO.

DENO, for its part, is working hard to stabilize this operation, as explained on its official site.

In this sense, and taking into account the reality of Javascript today, regarding everything that can be done with the language and the platforms it covers (IoT, Mobile, DENO, BunJS, NODE, Browsers, etc.), I think it would be It is convenient to be able to update the documentation to understand if NPM works with cross-platform packages or if it only has the focus of following the guidelines of packages that can be published for NODE.

Defining what is the purpose and objective of NPM today I think is crucial.

Understanding that NPM's view is the reference for javascript packages, my suggestion is to improve the documentation, and make the necessary adjustments so that it handles generalized information, which can be useful for the development of any package, regardless of the environment in which you work.

To better exemplify it,
If we talk about Node itself, today it is somewhat outdated with respect to what can or cannot be defined in the package. They are, for example, the “exports” entry point and the conditional exports proposed by node and already taken into account by others. tools and platforms are not included here, I think that unifying criteria so that the community can understand whether or not to use NPM as a reference for the definition of packages is something crucial nowadays.

[BUG] https://docs.npmjs.com/adding-collaborators-to-private-packages-owned-by-a-user-account seems incorrect

https://docs.npmjs.com/adding-collaborators-to-private-packages-owned-by-a-user-account

1. Section "Granting access to a private user package on the web" - the documentation references 'Collaborators' but this is actually 'maintainers' on the current site.

2. Documentation states "The user you want to add as a collaborator on your private package must have a paid user account" - however from my testing this is not correct. I was able to add a non-paying user as a maintainer with no issues

[BUG] Option 2 of "upgrade npm on windows" made windows not recognize npm

What / Why

Option 2 of "upgrade npm on windows" made windows not recognize npm as a command
https://docs.npmjs.com/try-the-latest-stable-version-of-npm

How

I deleted npm and npm.cmd from nodejs/, and even though C:\Users\<username>\AppData\Roaming\npm is still listed in the path and npm config get prefix -g did return C:\Users\<username>\AppData\Roaming\npm, windows won't recognize npm as a command anymore.
(it turns out this folder is empty, I should have checked myself but I trusted the docs)

Expected Behavior

I think the doc should include a warning about this method being dangerous or just be clearer about who can apply it, because evidently I wasn't one of them.

[BUG] NPM 8.1 is not present in the documentation despite being the default NPM version distributed in the Node LTS version

What / Why

NPM 8.1 is the default version of NPM distributed with Node LTS, yet there is no documentation for NPM 8.1, shouldn't NPM 8.1 be the current release?

When

• n/a

Where

• n/a

How

Current Behavior

• n/a

Steps to Reproduce

• n/a

Expected Behavior

• n/a

Who

• n/a

References

• n/a

H

Inconsistent result of "npm view <package name> readme"

Note. I don't know where is good place to open this issue because it's related to npm backend.

npm view uws readme returns up to date readme
npm view aq readme doesn't match with latest readme on https://www.npmjs.com/package/aq but matches with readme on https://replicate.npmjs.com/registry/aq

expected behaviour:
npm view aq readme and https://replicate.npmjs.com/registry/aq should have latest readme for all packages
real behaviour:
some packages have latest version of readme, some packages have very first version of readme

Npm/docs

Saisai

🙂🙂😙🙂🙂