-
Notifications
You must be signed in to change notification settings - Fork 3.1k
Update searching-for-and-choosing-packages-to-download.mdx #1453
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
Merged
Merged
Changes from 3 commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
152d4f4
Update searching-for-and-choosing-packages-to-download.mdx
monishcm f6fc3b5
Create viewing-package-provenance.mdx
monishcm 802d736
Update content/packages-and-modules/getting-packages-from-the-registr…
monishcm 6ff2807
Update content/packages-and-modules/getting-packages-from-the-registr…
monishcm 3676414
Add note about package provenance information.
monishcm d4c09a1
Fix typo in package provenance information.
monishcm 5bfa597
Update content/packages-and-modules/getting-packages-from-the-registr…
monishcm 7b65c1a
Update content/packages-and-modules/getting-packages-from-the-registr…
monishcm a3b0b35
Fix style issue
monishcm File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -6,6 +6,8 @@ redirect_from: | |
|
||
You can use the npm search bar to find packages to use in your projects. The search is performed using content from the package's title, description, readme, and keywords and is powered by [opensearch](https://opensearch.org/). Search results are displayed based on keyword matching from the package's title, description, readme, and keywords. No subjective ranking criteria are applied, except for a minimal boost to deprioritize spammy or entirely new packages, aiming to maintain a neutral stance towards all other packages. | ||
|
||
Please note that newly published packages may take up to one-two week to appear in the search results. Additionally, deprecated packages are excluded from the search results to enhance the user experience. | ||
|
||
## Searching for a package | ||
|
||
1. In the search bar, type a search term and press **Enter**. As you type, possible choices will appear. | ||
|
@@ -19,61 +21,3 @@ You can use the npm search bar to find packages to use in your projects. The sea | |
<Screenshot src="/packages-and-modules/getting-packages-from-the-registry/search-sort-options.png" alt="Screenshot of the search Sort by dropdown featuring sorting options" /> | ||
|
||
3. In the package search results list, click the name of the package. | ||
|
||
monishcm marked this conversation as resolved.
Show resolved
Hide resolved
|
||
## Package provenance | ||
|
||
When packages have been published with provenance, you can: | ||
|
||
- Verify where and how a package was published. | ||
- Validate that an authorized user published a package. | ||
|
||
You can use this information to audit packages and determine whether or not you want to consume them. For more information about npm provenance, see "[About npm provenance][about-provenance]." | ||
|
||
To view provenance information for a package in the npm registry: | ||
|
||
1. In the npm registry, navigate to a package. | ||
|
||
2. On the package's page, in the **Version** field to the right of the README, look for a green check mark. If there is a green check mark, this means the package was published with provenance. | ||
|
||
<Screenshot src="/packages-and-modules/getting-packages-from-the-registry/npm-provenance-check-mark.png" alt="Screenshot showing a Version field with a green check mark" /> | ||
|
||
3. Click on the check mark, then click **View more details**. | ||
|
||
4. View the following information for the package: | ||
|
||
- **Build Environment**: The environment used to build the package. | ||
- **Build Summary**: A link to the workflow run that built the package. | ||
- **Source Commit**: A link to the commit the package was built from. | ||
- **Build File**: A link to the workflow file used to build the package. | ||
- **Public Ledger**: A link to a transparency log entry attesting an authorized user published the package. | ||
|
||
<Screenshot src="/packages-and-modules/getting-packages-from-the-registry/npm-provenance.png" alt="Screenshot showing npm provenance information for a published package" /> | ||
|
||
<Note> | ||
|
||
**Note:** Whenever you access a package's provenance information on [npmjs.com](https://npmjs.com), the linked source commit and repository are checked by npm. If the linked source commit or repository cannot be found, an error message will appear at the top of the page and alongside the provenance information. This is to inform you that the provenance for this package can no longer be established, which may occur when a repository is deleted or made private. | ||
|
||
<Screenshot src="/packages-and-modules/getting-packages-from-the-registry/[email protected]" alt="Screenshot showing a warning when the provenance source commit or repository cannot be found." /> | ||
|
||
</Note> | ||
|
||
### Verifying provenance attestations | ||
|
||
When you download a package from the registry, you can verify the provenance of a package with the following CLI command: | ||
|
||
``` | ||
npm audit signatures | ||
``` | ||
|
||
This command checks the registry signatures and provenance attestations. If a package has missing or invalid signatures or attestations, it returns an error. This could indicate that a package has been tampered with. | ||
|
||
<Note> | ||
|
||
**Note:** In order to run the audit command to verify package provenance, you must: | ||
|
||
- Install npm CLI version `v9.5.0` or later: `npm install -g npm@latest` | ||
- Install dependencies with `npm install` or `npm ci` | ||
|
||
</Note> | ||
|
||
[about-provenance]: /generating-provenance-statements#about-npm-provenance |
63 changes: 63 additions & 0 deletions
63
...s-and-modules/getting-packages-from-the-registry/viewing-package-provenance.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,63 @@ | ||
--- | ||
title: Viewing package provenance | ||
redirect_from: | ||
- /getting-started/searching-for-packages | ||
monishcm marked this conversation as resolved.
Show resolved
Hide resolved
|
||
--- | ||
|
||
## Viewing package provenance | ||
|
||
When packages have been published with provenance, you can: | ||
|
||
- Verify where and how a package was published. | ||
- Validate that an authorized user published a package. | ||
|
||
You can use this information to audit packages and determine whether or not you want to consume them. For more information about npm provenance, see "[About npm provenance][about-provenance]." | ||
|
||
To view provenance information for a package in the npm registry: | ||
|
||
1. In the npm registry, navigate to a package. | ||
|
||
2. On the package's page, in the **Version** field to the right of the README, look for a green check mark. If there is a green check mark, this means the package was published with provenance. | ||
|
||
<Screenshot src="/packages-and-modules/getting-packages-from-the-registry/npm-provenance-check-mark.png" alt="Screenshot showing a Version field with a green check mark" /> | ||
|
||
3. Click on the check mark, then click **View more details**. | ||
|
||
4. View the following information for the package: | ||
|
||
- **Build Environment**: The environment used to build the package. | ||
- **Build Summary**: A link to the workflow run that built the package. | ||
- **Source Commit**: A link to the commit the package was built from. | ||
- **Build File**: A link to the workflow file used to build the package. | ||
- **Public Ledger**: A link to a transparency log entry attesting an authorized user published the package. | ||
|
||
<Screenshot src="/packages-and-modules/getting-packages-from-the-registry/npm-provenance.png" alt="Screenshot showing npm provenance information for a published package" /> | ||
|
||
<Note> | ||
|
||
**Note:** Whenever you access a package's provenance information on [npmjs.com](https://npmjs.com), the linked source commit and repository are checked by npm. If the linked source commit or repository cannot be found, an error message will appear at the top of the page and alongside the provenance information. This is to inform you that the provenance for this package can no longer be established, which may occur when a repository is deleted or made private. | ||
|
||
<Screenshot src="/packages-and-modules/getting-packages-from-the-registry/[email protected]" alt="Screenshot showing a warning when the provenance source commit or repository cannot be found." /> | ||
|
||
</Note> | ||
|
||
### Verifying provenance attestations | ||
|
||
When you download a package from the registry, you can verify the provenance of a package with the following CLI command: | ||
|
||
``` | ||
npm audit signatures | ||
``` | ||
|
||
This command checks the registry signatures and provenance attestations. If a package has missing or invalid signatures or attestations, it returns an error. This could indicate that a package has been tampered with. | ||
|
||
<Note> | ||
|
||
**Note:** In order to run the audit command to verify package provenance, you must: | ||
|
||
- Install npm CLI version `v9.5.0` or later: `npm install -g npm@latest` | ||
- Install dependencies with `npm install` or `npm ci` | ||
|
||
</Note> | ||
|
||
[about-provenance]: /generating-provenance-statements#about-npm-provenance |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.