From 540d1cf5f1c874018951b25f75a3d625b06263f0 Mon Sep 17 00:00:00 2001 From: npm CLI robot Date: Wed, 29 Jan 2025 21:20:29 +0000 Subject: [PATCH] CLI documentation update from CI --- cli-cache.json | 2 +- content/cli/v11/commands/npm-deprecate.mdx | 9 ++ content/cli/v11/commands/npm-ls.mdx | 4 +- content/cli/v11/commands/npm-undeprecate.mdx | 81 ++++++++++++++ content/cli/v11/commands/npm.mdx | 2 +- .../cli/v11/configuring-npm/package-json.mdx | 102 +++++++++--------- content/cli/v11/using-npm/changelog.mdx | 41 +++++++ content/cli/v11/using-npm/config.mdx | 2 +- content/nav.yml | 2 +- 9 files changed, 188 insertions(+), 57 deletions(-) create mode 100644 content/cli/v11/commands/npm-undeprecate.mdx diff --git a/cli-cache.json b/cli-cache.json index c0002320f90..b6e0e3f45e3 100644 --- a/cli-cache.json +++ b/cli-cache.json @@ -2,5 +2,5 @@ "v8": "aa8fff11cdab94fff1a2160ee5241f5f4632e96b", "v9": "64763a341e7aa5b456e696f956759bf9b3440dc1", "v10": "a3041941586b6fb8ed7403fe3c24d81138a96005", - "v11": "6d0f46e67e9673e8a2dc6edb92144a73f853950c" + "v11": "cab74ff7c25149d172cf5d612eb0a651eda531e3" } \ No newline at end of file diff --git a/content/cli/v11/commands/npm-deprecate.mdx b/content/cli/v11/commands/npm-deprecate.mdx index a09467d000c..367ec4de030 100644 --- a/content/cli/v11/commands/npm-deprecate.mdx +++ b/content/cli/v11/commands/npm-deprecate.mdx @@ -83,6 +83,15 @@ This is a one-time password from a two-factor authenticator. It's needed when pu If not set, and a registry response fails with a challenge for a one-time password, npm will prompt on the command line for one. +#### `dry-run` + +- Default: false +- Type: Boolean + +Indicates that you don't want npm to make any changes and that it should only report what it would have done. This can be passed into any of the commands that modify your local installation, eg, `install`, `update`, `dedupe`, `uninstall`, as well as `pack` and `publish`. + +Note: This is NOT honored by other network related commands, eg `dist-tags`, `owner`, etc. + ### See Also - [package spec](/cli/v11/using-npm/package-spec) diff --git a/content/cli/v11/commands/npm-ls.mdx b/content/cli/v11/commands/npm-ls.mdx index 05b9e2d70af..b874a1a242b 100644 --- a/content/cli/v11/commands/npm-ls.mdx +++ b/content/cli/v11/commands/npm-ls.mdx @@ -52,7 +52,7 @@ Note: to get a "bottoms up" view of why a given package is included in the tree Positional arguments are `name@version-range` identifiers, which will limit the results to only the paths to the packages named. Note that nested packages will _also_ show the paths to the specified packages. For example, running `npm ls promzard` in npm's source tree will show: ```bash -npm@11.0.0 /path/to/npm +npm@11.1.0 /path/to/npm └─┬ init-package-json@0.0.4 └── promzard@0.1.5 ``` @@ -112,7 +112,7 @@ Operates in "global" mode, so that packages are installed into the `prefix` fold #### `depth` -- Default: `Infinity` if `--all` is set, otherwise `1` +- Default: `Infinity` if `--all` is set, otherwise `0` - Type: null or Number The depth to go when recursing packages for `npm ls`. diff --git a/content/cli/v11/commands/npm-undeprecate.mdx b/content/cli/v11/commands/npm-undeprecate.mdx new file mode 100644 index 00000000000..c016773b1ed --- /dev/null +++ b/content/cli/v11/commands/npm-undeprecate.mdx @@ -0,0 +1,81 @@ +--- +title: npm-undeprecate +section: 1 +description: Undeprecate a version of a package +github_repo: npm/cli +github_branch: latest +github_path: docs/lib/content/commands/npm-undeprecate.md +redirect_from: + - /cli-commands/npm-undeprecate + - /cli-commands/undeprecate + - /cli-documentation/cli-commands/npm-undeprecate + - /cli-documentation/cli-commands/undeprecate + - /cli-documentation/commands/npm-undeprecate + - /cli-documentation/commands/undeprecate + - /cli-documentation/npm-undeprecate + - /cli-documentation/undeprecate + - /cli-documentation/v11/cli-commands/npm-undeprecate + - /cli-documentation/v11/cli-commands/undeprecate + - /cli-documentation/v11/commands/npm-undeprecate + - /cli-documentation/v11/commands/undeprecate + - /cli-documentation/v11/npm-undeprecate + - /cli-documentation/v11/undeprecate + - /cli/cli-commands/npm-undeprecate + - /cli/cli-commands/undeprecate + - /cli/commands/npm-undeprecate + - /cli/commands/undeprecate + - /cli/npm-undeprecate + - /cli/undeprecate + - /cli/v11/cli-commands/npm-undeprecate + - /cli/v11/cli-commands/undeprecate + - /cli/v11/commands/undeprecate + - /cli/v11/npm-undeprecate + - /cli/v11/undeprecate + - /commands/npm-undeprecate + - /commands/undeprecate +--- + +### Synopsis + +```bash +npm undeprecate +``` + +Note: This command is unaware of workspaces. + +### Description + +This command will update the npm registry entry for a package, removing any deprecation warnings that currently exist. + +It works in the same way as [npm deprecate](/cli/v11/commands/npm-deprecate), except that this command removes deprecation warnings instead of adding them. + +### Configuration + +#### `registry` + +- Default: "https://registry.npmjs.org/" +- Type: URL + +The base URL of the npm registry. + +#### `otp` + +- Default: null +- Type: null or String + +This is a one-time password from a two-factor authenticator. It's needed when publishing or changing package permissions with `npm access`. + +If not set, and a registry response fails with a challenge for a one-time password, npm will prompt on the command line for one. + +#### `dry-run` + +- Default: false +- Type: Boolean + +Indicates that you don't want npm to make any changes and that it should only report what it would have done. This can be passed into any of the commands that modify your local installation, eg, `install`, `update`, `dedupe`, `uninstall`, as well as `pack` and `publish`. + +Note: This is NOT honored by other network related commands, eg `dist-tags`, `owner`, etc. + +### See Also + +- [npm deprecate](/cli/v11/commands/npm-deprecate) diff --git a/content/cli/v11/commands/npm.mdx b/content/cli/v11/commands/npm.mdx index 2305fb86ab6..4fd6fe24d25 100644 --- a/content/cli/v11/commands/npm.mdx +++ b/content/cli/v11/commands/npm.mdx @@ -31,7 +31,7 @@ Note: This command is unaware of workspaces. ### Version -11.0.0 +11.1.0 ### Description diff --git a/content/cli/v11/configuring-npm/package-json.mdx b/content/cli/v11/configuring-npm/package-json.mdx index 46fdc94ab28..98c85372cd4 100644 --- a/content/cli/v11/configuring-npm/package-json.mdx +++ b/content/cli/v11/configuring-npm/package-json.mdx @@ -53,7 +53,7 @@ Some tips: - The name will probably be passed as an argument to require(), so it should be something short, but also reasonably descriptive. - You may want to check the npm registry to see if there's something by that name already, before you get too attached to it. [https://www.npmjs.com/](https://www.npmjs.com/) -A name can be optionally prefixed by a scope, e.g. `@myorg/mypackage`. See [`scope`](/cli/v11/using-npm/scope) for more detail. +A name can be optionally prefixed by a scope, e.g. `@npm/example`. See [`scope`](/cli/v11/using-npm/scope) for more detail. ### version @@ -76,7 +76,7 @@ The URL to the project homepage. Example: ```json -"homepage": "https://github.com/owner/project#readme" +"homepage": "https://github.com/npm/example#readme" ``` ### bugs @@ -88,8 +88,8 @@ It should look like this: ```json { "bugs": { - "url": "https://github.com/owner/project/issues", - "email": "project@hostname.com" + "url": "https://github.com/npm/example/issues", + "email": "example@npmjs.com" } } ``` @@ -110,7 +110,7 @@ If you're using a common license such as BSD-2-Clause or MIT, add a current SPDX } ``` -You can check [the full list of SPDX license IDs](https://spdx.org/licenses/). Ideally you should pick one that is [OSI](https://opensource.org/licenses/) approved. +You can check [the full list of SPDX license IDs](https://spdx.org/licenses/). Ideally, you should pick one that is [OSI](https://opensource.org/licenses/) approved. If your package is licensed under multiple common licenses, use an [SPDX license expression syntax version 2.0 string](https://spdx.dev/specifications/), like this: @@ -187,8 +187,8 @@ The "author" is one person. "contributors" is an array of people. A "person" is ```json { "name": "Barney Rubble", - "email": "b@rubble.com", - "url": "http://barnyrubble.tumblr.com/" + "email": "barney@npmjs.com", + "url": "http://barnyrubble.npmjs.com/" } ``` @@ -196,7 +196,7 @@ Or you can shorten that all into a single string, and npm will parse it for you: ```json { - "author": "Barney Rubble (http://barnyrubble.tumblr.com/)" + "author": "Barney Rubble (http://barnyrubble.npmjs.com/)" } ``` @@ -212,7 +212,7 @@ You can specify an object containing a URL that provides up-to-date information { "funding": { "type": "individual", - "url": "http://example.com/donate" + "url": "http://npmjs.com/donate" } } ``` @@ -221,14 +221,14 @@ You can specify an object containing a URL that provides up-to-date information { "funding": { "type": "patreon", - "url": "https://www.patreon.com/my-account" + "url": "https://www.patreon.com/user" } } ``` ```json { - "funding": "http://example.com/donate" + "funding": "http://npmjs.com/donate" } ``` @@ -237,12 +237,12 @@ You can specify an object containing a URL that provides up-to-date information "funding": [ { "type": "individual", - "url": "http://example.com/donate" + "url": "http://npmjs.com/donate" }, - "http://example.com/donateAlso", + "http://npmjs.com/donate-also", { "type": "patreon", - "url": "https://www.patreon.com/my-account" + "url": "https://www.patreon.com/user" } ] } @@ -448,9 +448,9 @@ For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use the same ```json { - "repository": "npm/npm", + "repository": "npm/example", - "repository": "github:user/repo", + "repository": "github:npm/example", "repository": "gist:11081aaa281", @@ -518,7 +518,7 @@ See [semver](https://github.com/npm/node-semver#versions) for more details about - `user/repo` See 'GitHub URLs' below - `tag` A specific version tagged and published as `tag` See [`npm dist-tag`](/cli/v11/commands/npm-dist-tag) - `path/path/path` See [Local Paths](#local-paths) below -- `npm:@scope/pkg@version` Custom alias for a pacakge See [`package-spec`](/cli/v11/using-npm/package-spec#aliases) +- `npm:@scope/pkg@version` Custom alias for a package See [`package-spec`](/cli/v11/using-npm/package-spec#aliases) For example, these are all valid: @@ -530,7 +530,7 @@ For example, these are all valid: "baz": ">1.0.2 <=2.3.4", "boo": "2.0.1", "qux": "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0", - "asd": "http://asdf.com/asdf.tar.gz", + "asd": "http://npmjs.com/example.tar.gz", "til": "~1.2", "elf": "~1.2.3", "two": "2.x", @@ -593,7 +593,7 @@ As of version 1.1.65, you can refer to GitHub URLs as just "foo": "user/foo-proj "dependencies": { "express": "expressjs/express", "mocha": "mochajs/mocha#4727d357ea", - "module": "user/repo#feature\/branch" + "module": "npm/example-github-repo#feature\/branch" } } ``` @@ -638,7 +638,7 @@ For example: ```json { - "name": "ethopia-waza", + "name": "@npm/ethopia-waza", "description": "a delightfully fruity coffee varietal", "version": "1.2.3", "devDependencies": { @@ -661,19 +661,19 @@ For example: ```json { - "name": "tea-latte", + "name": "@npm/tea-latte", "version": "1.3.5", "peerDependencies": { - "tea": "2.x" + "@npm/tea": "2.x" } } ``` -This ensures your package `tea-latte` can be installed _along_ with the second major version of the host package `tea` only. `npm install tea-latte` could possibly yield the following dependency graph: +This ensures your package `@npm/tea-latte` can be installed _along_ with the second major version of the host package `@npm/tea` only. `npm install tea-latte` could possibly yield the following dependency graph: ```bash -├── tea-latte@1.3.5 -└── tea@2.2.0 +├── @npm/tea-latte@1.3.5 +└── @npm/tea@2.2.0 ``` In npm versions 3 through 6, `peerDependencies` were not automatically installed, and would raise a warning if an invalid version of the peer dependency was found in the tree. As of npm v7, peerDependencies _are_ installed by default. @@ -690,14 +690,14 @@ For example: ```json { - "name": "tea-latte", + "name": "@npm/tea-latte", "version": "1.3.5", "peerDependencies": { - "tea": "2.x", - "soy-milk": "1.2" + "@npm/tea": "2.x", + "@npm/soy-milk": "1.2" }, "peerDependenciesMeta": { - "soy-milk": { + "@npm/soy-milk": { "optional": true } } @@ -716,13 +716,13 @@ If we define a package.json like this: ```json { - "name": "awesome-web-framework", + "name": "@npm/awesome-web-framework", "version": "1.0.0", - "bundleDependencies": ["renderized", "super-streams"] + "bundleDependencies": ["@npm/renderized", "@npm/super-streams"] } ``` -we can obtain `awesome-web-framework-1.0.0.tgz` file by running `npm pack`. 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`. +we can obtain `@npm/awesome-web-framework-1.0.0.tgz` file by running `npm pack`. This file contains the dependencies `@npm/renderized` and `@npm/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. @@ -736,8 +736,8 @@ It is still your program's responsibility to handle the lack of the dependency. ```js try { - var foo = require("foo"); - var fooVersion = require("foo/package.json").version; + var foo = require("@npm/foo"); + var fooVersion = require("@npm/foo/package.json").version; } catch (er) { foo = null; } @@ -767,57 +767,57 @@ To make sure the package `foo` is always installed as version `1.0.0` no matter ```json { "overrides": { - "foo": "1.0.0" + "@npm/foo": "1.0.0" } } ``` -The above is a short hand notation, the full object form can be used to allow overriding a package itself as well as a child of the package. This will cause `foo` to always be `1.0.0` while also making `bar` at any depth beyond `foo` also `1.0.0`: +The above is a short hand notation, the full object form can be used to allow overriding a package itself as well as a child of the package. This will cause `@npm/foo` to always be `1.0.0` while also making `@npm/bar` at any depth beyond `@npm/foo` also `1.0.0`: ```json { "overrides": { - "foo": { + "@npm/foo": { ".": "1.0.0", - "bar": "1.0.0" + "@npm/bar": "1.0.0" } } } ``` -To only override `foo` to be `1.0.0` when it's a child (or grandchild, or great grandchild, etc) of the package `bar`: +To only override `@npm/foo` to be `1.0.0` when it's a child (or grandchild, or great grandchild, etc) of the package `bar`: ```json { "overrides": { - "bar": { - "foo": "1.0.0" + "@npm/bar": { + "@npm/foo": "1.0.0" } } } ``` -Keys can be nested to any arbitrary length. To override `foo` only when it's a child of `bar` and only when `bar` is a child of `baz`: +Keys can be nested to any arbitrary length. To override `@npm/foo` only when it's a child of `@npm/bar` and only when `@npm/bar` is a child of `@npm/baz`: ```json { "overrides": { - "baz": { - "bar": { - "foo": "1.0.0" + "@npm/baz": { + "@npm/bar": { + "@npm/foo": "1.0.0" } } } } ``` -The key of an override can also include a version, or range of versions. To override `foo` to `1.0.0`, but only when it's a child of `bar@2.0.0`: +The key of an override can also include a version, or range of versions. To override `@npm/foo` to `1.0.0`, but only when it's a child of `@npm/bar@2.0.0`: ```json { "overrides": { - "bar@2.0.0": { - "foo": "1.0.0" + "@npm/bar@2.0.0": { + "@npm/foo": "1.0.0" } } } @@ -828,7 +828,7 @@ You may not set an override for a package that you directly depend on unless bot ```json { "dependencies": { - "foo": "^1.0.0" + "@npm/foo": "^1.0.0" }, "overrides": { // BAD, will throw an EOVERRIDE error @@ -836,9 +836,9 @@ You may not set an override for a package that you directly depend on unless bot // GOOD, specs match so override is allowed // "foo": "^1.0.0" // BEST, the override is defined as a reference to the dependency - "foo": "$foo", + "@npm/foo": "$foo", // the referenced package does not need to match the overridden one - "bar": "$foo" + "@npm/bar": "$foo" } } ``` diff --git a/content/cli/v11/using-npm/changelog.mdx b/content/cli/v11/using-npm/changelog.mdx index 5064d58605b..171a41fd078 100644 --- a/content/cli/v11/using-npm/changelog.mdx +++ b/content/cli/v11/using-npm/changelog.mdx @@ -15,6 +15,47 @@ redirect_from: - /using-npm/changelog --- +## [11.1.0](https://github.com/npm/cli/compare/v11.0.0...v11.1.0) (2025-01-29) + +### Features + +- [`7f6c997`](https://github.com/npm/cli/commit/7f6c9973dc9a4dfebd76e52e060a9d8496b8bd98) [#8009](https://github.com/npm/cli/pull/8009) add dry-run to deprecate/undeprecate commands (@wraithgar) +- [`1764a37`](https://github.com/npm/cli/commit/1764a37f1913b6a0811a85d89e029fc1dc79da54) [#8009](https://github.com/npm/cli/pull/8009) add npm undeprecate command (@wraithgar) + +### Bug Fixes + +- [`31455b2`](https://github.com/npm/cli/commit/31455b2e177b721292f3382726e3f5f3f2963b1d) [#8054](https://github.com/npm/cli/pull/8054) publish: honor force for no dist tag and registry version check (#8054) (@reggi) +- [`dc31c1b`](https://github.com/npm/cli/commit/dc31c1bdc6658ab69554adcf2988ee99a615c409) [#8038](https://github.com/npm/cli/pull/8038) remove max-len linting bypasses (@wraithgar) +- [`8a911ff`](https://github.com/npm/cli/commit/8a911ff895967678aa786595db3418fc28e6966a) [#8038](https://github.com/npm/cli/pull/8038) publish: disregard deprecated versions when calculating highest version (@wraithgar) +- [`7f72944`](https://github.com/npm/cli/commit/7f72944e43f009cf4d55ff4fe24c459e07f588fd) [#8038](https://github.com/npm/cli/pull/8038) publish: accept publishConfig.tag to override highes semver check (@wraithgar) +- [`ab9ddc0`](https://github.com/npm/cli/commit/ab9ddc0413374fbf4879da535f82e03bc4e62cf3) [#7992](https://github.com/npm/cli/pull/7992) sbom: deduplicate sbom dependencies (#7992) (@bdehamer) +- [`f7da341`](https://github.com/npm/cli/commit/f7da341322c2f860156e8144b208583596504479) [#7980](https://github.com/npm/cli/pull/7980) search: properly display multiple search terms (#7980) (@wraithgar) + +### Documentation + +- [`3644e79`](https://github.com/npm/cli/commit/3644e79a73e511bc54d857bc2026b071fe18a6fe) [#8055](https://github.com/npm/cli/pull/8055) update readme for Node.js versions, remove badges (#8055) (@wraithgar) +- [`f1af61f`](https://github.com/npm/cli/commit/f1af61f917e58a0a45d2b15d1e5600988b2c824f) [#8041](https://github.com/npm/cli/pull/8041) fix typos in "package-json" (#8041) (@maxkoryukov) +- [`e90c6fe`](https://github.com/npm/cli/commit/e90c6feeacdf9ad010d4d73b65d7dd7d3b86efe2) [#8051](https://github.com/npm/cli/pull/8051) depth flag default value (#8051) (@milaninfy) +- [`866b5ee`](https://github.com/npm/cli/commit/866b5ee3ae5ed508ecbe832d01f5ebd6b00f6789) [#8030](https://github.com/npm/cli/pull/8030) safer documentation urls, repos, packages (#8030) (@reggi) + +### Dependencies + +- [`7ddfbad`](https://github.com/npm/cli/commit/7ddfbadd1d51d07e68afbe1b91a36106d98c7bea) [#8053](https://github.com/npm/cli/pull/8053) `@npmcli/package-json@6.1.1` +- [`9473a86`](https://github.com/npm/cli/commit/9473a8638257297c420136009de567c131d2f299) [#8053](https://github.com/npm/cli/pull/8053) `spdx-license-ids@3.0.21` +- [`a65e5ce`](https://github.com/npm/cli/commit/a65e5ceb15c4aad6bde1ffdbee7da6f685caf81e) [#8053](https://github.com/npm/cli/pull/8053) `@sigstore/protobuf-specs@0.3.3` +- [`215ebe4`](https://github.com/npm/cli/commit/215ebe4d8f6c7f30d4b6a68fa11a3372c132929e) [#8053](https://github.com/npm/cli/pull/8053) `chalk@5.4.1` + +### Chores + +- [`61f00e3`](https://github.com/npm/cli/commit/61f00e3c23211d37c7980ebd6d1cf8d1dac49f18) [#8069](https://github.com/npm/cli/pull/8069) splits out smoke-tests from publish-dryrun tests (#8069) (@reggi) +- [`6d0f46e`](https://github.com/npm/cli/commit/6d0f46e67e9673e8a2dc6edb92144a73f853950c) [#8058](https://github.com/npm/cli/pull/8058) stop publish smoke from check git clean (#8058) (@reggi) +- [`9281ebf`](https://github.com/npm/cli/commit/9281ebf8e428d40450ad75ba61bc6f040b3bf896) [#8057](https://github.com/npm/cli/pull/8057) fix smoke tests prerelease needs separate string args (#8057) (@reggi) +- [`aa202e9`](https://github.com/npm/cli/commit/aa202e9dac2f927bedcaaed4db0eef7b3415fc68) [#8056](https://github.com/npm/cli/pull/8056) smoke tests using a preid (#8056) (@reggi) +- [`18e0449`](https://github.com/npm/cli/commit/18e0449ae41703a7980cee73bae69521db6fa53e) [#8053](https://github.com/npm/cli/pull/8053) dev dependency updates (@wraithgar) +- [`859a71c`](https://github.com/npm/cli/commit/859a71c59ea5f91f21a8410db46585a2fc0a8126) [#8052](https://github.com/npm/cli/pull/8052) update node versions for release integration tests (#8052) (@wraithgar) +- [`7e7961d`](https://github.com/npm/cli/commit/7e7961d8936e277f3dbc8e44f9e7b07daaeb36ca) [#8038](https://github.com/npm/cli/pull/8038) bump @npmcli/eslint-config to 5.1.0 (@wraithgar) +- [workspace](https://github.com/npm/cli/releases/tag/config-v10.0.1): `@npmcli/config@10.0.1` + ## [11.0.0](https://github.com/npm/cli/compare/v11.0.0-pre.1...v11.0.0) (2024-12-16) ### Documentation diff --git a/content/cli/v11/using-npm/config.mdx b/content/cli/v11/using-npm/config.mdx index f071bee3a18..67146a3c257 100644 --- a/content/cli/v11/using-npm/config.mdx +++ b/content/cli/v11/using-npm/config.mdx @@ -274,7 +274,7 @@ Override CPU architecture of native modules to install. Acceptable values are sa #### `depth` -- Default: `Infinity` if `--all` is set, otherwise `1` +- Default: `Infinity` if `--all` is set, otherwise `0` - Type: null or Number The depth to go when recursing packages for `npm ls`. diff --git a/content/nav.yml b/content/nav.yml index 270af10940a..426f2bad30c 100644 --- a/content/nav.yml +++ b/content/nav.yml @@ -1594,7 +1594,7 @@ - title: Changelog url: /cli/v10/using-npm/changelog description: Changelog notes for each version - - title: Version 11.0.0 + - title: Version 11.1.0 shortName: v11 url: /cli/v11 default: true