pacote (original) (raw)

pacote

Fetches package manifests and tarballs from the npm registry.

USAGE

const pacote = require('pacote')

// get a package manifest pacote.manifest('foo@1.x').then(manifest => console.log('got it', manifest))

// extract a package into a folder pacote.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. 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.)

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 be simulated.

prepare scripts will be run when generating tarballs from git anddirectory locations, to simulate what would be published to the registry, so that you get a working package instead of just raw source code that might need to be transpiled.

CLI

This module exports a command line interface that can do most of what is described below. Run pacote -h to learn more.

Pacote - The JavaScript Package Handler, v10.1.1

Usage:

  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, or
options 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.

API

The spec 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 valid opts values.

Options

Options are passed tonpm-registry-fetch andcacache, so in addition to these, anything for those 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.

Advanced API

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

Extracted File Modes

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 from cluttering a project's node_modules folder, even if the package tarball specifies that the file should be inaccessible.

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

So, a file which is 0o771 in the tarball, using the default fmode of0o666 and umask of 0o22, will result in a file mode of 0o755:

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

In almost every case, the defaults are appropriate. To respect exactly what is in the package tarball (even if this makes an unusable system), set both dmode and fmode options to 0. Otherwise, the umask config should be used in most cases where file mode modifications are required, and this functions more or less the same as the umask value in most Unix systems.

Extracted File Ownership

When running as root on Unix systems, all extracted files and folders will have their owning uid and gid values set to match the ownership of the containing folder.

This prevents root-owned files showing up in a project's node_modulesfolder when a user runs sudo npm install.

Manifests

A manifest is similar to a package.json file. However, it has a few pieces of extra metadata, and sometimes lacks metadata that is inessential to package installation.

In addition to the common package.json fields, manifests include:

Packuments

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

When a packument is fetched with accept: application/vnd.npm.install-v1+json in the HTTP headers, only the most minimum necessary metadata is returned. Additional metadata is returned when fetched with only accept: application/json.

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

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