Repository files navigation

Fetches package manifests and tarballs from the npm registry.

constpacote=require('pacote')// get a package manifestpacote.manifest('foo@1.x').then(manifest=>console.log('got it',manifest))// extract a package into a folderpacote.extract('github:npm/cli','some/path',options).then(({from, resolved, integrity})=>{console.log('extracted!',from,resolved,integrity)})pacote.tarball('https://server.com/package.tgz').then(data=>{console.log('got '+data.length+' bytes of tarball data')})

pacote works with any kind of package specifier that npm can install. Ifyou can pass it to the npm CLI, you can pass it to pacote. (In fact, that'sexactly what the npm CLI does.)

Anything that you can do with one kind of package, you can do with another.

Data that isn't relevant (like a packument for a tarball) will besimulated.

prepare scripts will be run when generating tarballs fromgit anddirectory locations, to simulate whatwould be published to theregistry, so that you get a working package instead of just raw sourcecode that might need to be transpiled.

This module exports a command line interface that can do most of what isdescribed below. Runpacote -h to learn more.

Pacote - The JavaScript Package Handler, v10.1.1Usage:  pacote resolve <spec>    Resolve a specifier and output the fully resolved target    Returns integrity and from if '--long' flag is set.  pacote manifest <spec>    Fetch a manifest and print to stdout  pacote packument <spec>    Fetch a full packument and print to stdout  pacote tarball <spec> [<filename>]    Fetch a package tarball and save to <filename>    If <filename> is missing or '-', the tarball will be streamed to stdout.  pacote extract <spec> <folder>    Extract a package to the destination folder.Configuration values all match the names of configs passed to npm, oroptions passed to Pacote.  Additional flags for this executable:  --long     Print an object from 'resolve', including integrity and spec.  --json     Print result objects as JSON rather than node's default.             (This is the default if stdout is not a TTY.)  --help -h  Print this helpful text.For example '--cache=/path/to/folder' will use that folder as the cache.

Thespec refers to any kind of package specifier that npm can install.If you can pass it to the npm CLI, you can pass it to pacote. (In fact,that's exactly what the npm CLI does.)

See below for validopts values.

• pacote.resolve(spec, opts) Resolve a specifier likefoo@latest orgithub:user/project all the way to a tarball url, tarball file, or gitrepo with commit hash.

• pacote.extract(spec, dest, opts) Extract a package's tarball into adestination folder. Returns a promise that resolves to the{from,resolved,integrity} of the extracted package.

• pacote.manifest(spec, opts) Fetch (or simulate) a package's manifest(basically, thepackage.json file, plus a bit of metadata).See below for more on manifests and packuments. Returns a Promise thatresolves to the manifest object.

• pacote.packument(spec, opts) Fetch (or simulate) a package's packument(basically, the top-level package document listing all the manifests thatthe registry returns). See below for more on manifests and packuments.Returns a Promise that resolves to the packument object.

• pacote.tarball(spec, opts) Get a package tarball data as a buffer inmemory. Returns a Promise that resolves to the tarball data Buffer, withfrom,resolved, andintegrity fields attached.

• pacote.tarball.file(spec, dest, opts) Save a package tarball data toa file on disk. Returns a Promise that resolves to{from,integrity,resolved} of the fetched tarball.

• pacote.tarball.stream(spec, streamHandler, opts) Fetch a tarball andmake the stream available to thestreamHandler function.

  This is mostly an internal function, but it is exposed because it doesprovide some functionality that may be difficult to achieve otherwise.

  ThestreamHandler function MUST return a Promise that resolves whenthe stream (and all associated work) is ended, or rejects if the streamhas an error.

  ThestreamHandler function MAY be called multiple times, as Pacoteretries requests in some scenarios, such as cache corruption orretriable network failures.

Options are passed tonpm-registry-fetch andcacache, so in addition to these, anything forthose modules can be given to pacote as well.

Options object is cloned, and mutated along the way to add integrity,resolved, and other properties, as they are determined.

• cache Where to store cache entries and temp files. Passed tocacache. Defaults to the same cache directorythat npm will use by default, based on platform and environment.
• where Base folder for resolving relativefile: dependencies.
• resolved Shortcut for looking up resolved values. Should be specifiedif known.
• integrity Expected integrity of fetched package tarball. If specified,tarballs with mismatched integrity values will raise anEINTEGRITYerror.
• umask Permission mode mask for extracted files and directories.Defaults to0o22. See "Extracted File Modes" below.
• fmode Minimum permission mode for extracted files. Defaults to0o666. See "Extracted File Modes" below.
• dmode Minimum permission mode for extracted directories. Defaults to0o777. See "Extracted File Modes" below.
• preferOnline Prefer to revalidate cache entries, even when it would notbe strictly necessary. Defaultfalse.
• before When picking a manifest from a packument, only considerpackages published before the specified date. Defaultnull.
• defaultTag The defaultdist-tag to use when choosing a manifest from apackument. Defaults tolatest.
• registry The npm registry to use by default. Defaults tohttps://registry.npmjs.org/.
• fullMetadata Fetch the full metadata from the registry for packuments,including information not strictly required for installation (author,description, etc.) Defaults totrue whenbefore is set, since theversion publish time is part of the extended packument metadata.
• fullReadJson Use the slowerread-package-json package insted ofread-package-json-fast in order to include extra fields like "readme" inthe manifest. Defaults tofalse.
• packumentCache For registry packuments only, you may provide aMapobject which will be used to cache packument requests between pacotecalls. This allows you to easily avoid hitting the registry multipletimes (even just to validate the cache) for a given packument, since itis unlikely to change in the span of a single command.
• verifySignatures A boolean that will make pacote verify theintegrity signature of a manifest, if present. There must be aconfigured_keys entry in the config that is scoped to theregistry the manifest is being fetched from.
• verifyAttestations A boolean that will make pacote verify Sigstoreattestations, if present. There must be a configured_keys entry in theconfig that is scoped to the registry the manifest is being fetched from.
• tufCache Where to store metadata/target files when retrieving the packageattestation key material via TUF. Defaults to the same cache directory thatnpm will use by default, based on platform and environment.

Each different type of fetcher is exposed for more advanced usage such asusing helper methods from this classes:

• DirFetcher
• FileFetcher
• GitFetcher
• RegistryFetcher
• RemoteFetcher

Files are extracted with a mode matching the following formula:

( (tarball entry mode value) | (minimum mode option) ) ~ (umask)

This is in order to prevent unreadable files or unlistable directories fromcluttering a project'snode_modules folder, even if the package tarballspecifies that the file should be inaccessible.

It also prevents files from being group- or world-writable without explicitopt-in by the user, because all file and directory modes are masked againsttheumask value.

So, a file which is0o771 in the tarball, using the defaultfmode of0o666 andumask of0o22, will result in a file mode of0o755:

(0o771 | 0o666) => 0o777(0o777 ~ 0o22) => 0o755

In almost every case, the defaults are appropriate. To respect exactlywhat is in the package tarball (even if this makes an unusable system), setbothdmode andfmode options to0. Otherwise, theumask configshould be used in most cases where file mode modifications are required,and this functions more or less the same as theumask value in most Unixsystems.

When running asroot on Unix systems, all extracted files and folderswill have their owninguid andgid values set to match the ownershipof the containing folder.

This preventsroot-owned files showing up in a project'snode_modulesfolder when a user runssudo npm install.

Amanifest is similar to apackage.json file. However, it has a fewpieces of extra metadata, and sometimes lacks metadata that is inessentialto package installation.

In addition to the commonpackage.json fields, manifests include:

• manifest._resolved The tarball url or file path where the packageartifact can be found.

• manifest._from A normalized form of the spec passed in as an argument.

• manifest._integrity The integrity value for the package artifact.

• manifest._id The canonical spec of this package version: name@version.

• manifest.dist Registry manifests (those included in a packument) have adist object. Onlytarball is required, though at least one ofshasum orintegrity is almost always present.

  • tarball The url to the associated package artifact. (Copied byPacote tomanifest._resolved.)
  • integrity The integrity SRI string for the artifact. This may notbe present for older packages on the npm registry. (Copied by Pacotetomanifest._integrity.)
  • shasum Legacy integrity value. Hexadecimal-encoded sha1 hash.(Converted to an SRI string and copied by Pacote tomanifest._integrity whendist.integrity is not present.)
  • fileCount Number of files in the tarball.
  • unpackedSize Size on disk of the package when unpacked.
  • signatures Signatures of the shasum. Includes the keyid thatcorrelates to akey from the npm registry

A packument is the top-level package document that lists the set ofmanifests for available versions for a package.

When a packument is fetched withaccept: application/vnd.npm.install-v1+json in the HTTP headers, only the mostminimum necessary metadata is returned. Additional metadata is returnedwhen fetched with onlyaccept: application/json.

For Pacote's purposes, the following fields are relevant:

• versions An object where each key is a version, and each value is themanifest for that version.
• dist-tags An object mapping dist-tags to version numbers. This is howfoo@latest gets turned intofoo@1.2.3.
• time In the full packument, an object mapping version numbers topublication times, for theopts.before functionality.

Pacote adds the following field, regardless of the accept header:

• _contentLength The size of the packument.