Pacote: JavaScript Package Downloader

Common errors

• Error: Command failed with exit code 1

  cause Often occurs when `prepare` scripts within a fetched package (especially from Git or local directory) fail during execution.
  fix Inspect the full error output for details from the failed script. Ensure the environment has necessary build tools and dependencies for the package's `prepare` script. You might need to adjust options to skip `prepare` if not critical.

• Error: Unsupported specifier: <your-package-specifier>

  cause The provided package specifier (e.g., `foo@^1.0`, `github:user/repo`, `file:../path`) is malformed or not recognized by Pacote/npm-package-arg.
  fix Verify the package specifier against `npm-package-arg` documentation and examples. Ensure correct syntax for versions, ranges, Git URLs, and local paths.

• ETIMEDOUT

  cause Network issues, incorrect registry configuration, or proxy problems preventing connection to the npm registry or other package sources.
  fix Check your network connection, npm proxy settings, and ensure your `.npmrc` or programmatic options have the correct `registry` and authentication (e.g., `_authToken`) configured.

• Error: Cannot find module 'pacote'

  cause Package `pacote` is not installed, or there is a module resolution issue (e.g., wrong import path, CJS/ESM mismatch in an improperly configured project).
  fix Ensure `pacote` is listed in `dependencies` and `npm install` has been run. Verify import statement (`const pacote = require('pacote');` for CJS or `import pacote from 'pacote';` for ESM) matches your project's module system and Node.js configuration.

Warnings

• breaking Pacote now requires Node.js version `^20.17.0 || >=22.9.0`. Older Node.js environments will result in runtime errors. Ensure your environment meets these minimum requirements.
  Fix: Upgrade your Node.js installation to version 20.17.0 or higher (or 22.9.0+).
• gotcha When fetching packages from Git repositories or local directories, Pacote automatically executes `prepare` scripts to simulate the build process as if it were being published to the registry. This can have side effects, introduce unexpected build times, or require specific environment configurations if not properly anticipated.
  Fix: Be aware of `prepare` script execution; ensure your environment can run these scripts safely and efficiently. If fetching from untrusted sources, consider security implications.
• gotcha Pacote's configuration options (`opts` parameter) mirror npm's CLI configuration. Incorrectly setting options like `cache`, `registry`, or authentication tokens can lead to unexpected fetching behavior, authentication failures, or network errors. Utilize the recently introduced `allowRegistry`, `allowRemote`, `allowFile`, `allowDirectory`, and `allowGit` options to explicitly control allowed package sources, as misconfiguration could unintentionally block valid package types.
  Fix: Carefully review `pacote` options against npm CLI documentation. For security and control, explicitly set `allow*` options to permit desired package source types.
• gotcha The `integrity` field, especially for Git sources, can be complex. Recent versions (e.g., v21.3.1 fix for `git ref matches expected sha`) highlight potential for inconsistencies in how Git references are resolved. Always verify the resolved `integrity` and `resolved` fields for critical dependencies.
  Fix: Always inspect the `integrity` and `resolved` fields returned by Pacote's APIs to ensure the fetched package matches expectations, particularly for Git-based dependencies.
• gotcha The introduction of 'attestation bundles' in v21.5.0 provides a security layer. While beneficial, it might introduce overhead or unexpected network requests if the registry or network setup doesn't fully support it, potentially impacting performance or causing errors if validation fails.
  Fix: Monitor network behavior and error logs after upgrading to ensure attestation bundle fetching and validation are working as expected within your environment and with your chosen registry.

Install

• npm install pacote npm
• yarn add pacote yarn
• pnpm add pacote pnpm

Imports

• pacote
  wrong:

  import { pacote } from 'pacote'; // Incorrect named import, pacote exports a default object.

  correct:

  import pacote from 'pacote';

  Pacote is typically imported as a default object containing all its functions.
• pacote (CommonJS)

  const pacote = require('pacote');

  CommonJS require style is fully supported and demonstrated in the official documentation.
• pacote.manifest
  wrong:

  import { manifest } from 'pacote'; // Manifest is a method on the default export, not a named export.

  correct:

  import pacote from 'pacote';
  const manifest = await pacote.manifest('foo@latest');

  All API functions like `manifest`, `extract`, `tarball` are methods of the main `pacote` object.

Quickstart

Demonstrates fetching a package manifest, extracting a package from a Git repository, and downloading a tarball directly from a URL using `pacote`'s core asynchronous APIs.

const pacote = require('pacote');
const path = require('path');
const fs = require('fs/promises');

async function main() {
  const packageName = 'lodash';
  const packageVersion = '4.17.21';
  const gitSpec = 'github:npm/cli';
  const tarballUrl = 'https://registry.npmjs.org/is-odd/-/is-odd-3.0.1.tgz';

  console.log(`--- Fetching manifest for ${packageName}@${packageVersion} ---`);
  try {
    const manifest = await pacote.manifest(`${packageName}@${packageVersion}`);
    console.log(`Got manifest for ${manifest.name}@${manifest.version}`);
    console.log(`Dependencies: ${Object.keys(manifest.dependencies || {}).join(', ') || 'None'}`);
  } catch (error) {
    console.error(`Failed to fetch manifest: ${error.message}`);
  }

  console.log(`\n--- Extracting ${gitSpec} to a temporary path ---`);
  const tempExtractPath = path.join(__dirname, 'temp-extracted-repo');
  try {
    await fs.mkdir(tempExtractPath, { recursive: true });
    const { from, resolved, integrity } = await pacote.extract(gitSpec, tempExtractPath);
    console.log(`Extracted '${from}' (resolved to '${resolved}') with integrity '${integrity}' to '${tempExtractPath}'`);
    const files = await fs.readdir(tempExtractPath);
    console.log(`Extracted files (first 5): ${files.slice(0, 5).join(', ')}...`);
  } catch (error) {
    console.error(`Failed to extract package: ${error.message}`);
  } finally {
    await fs.rm(tempExtractPath, { recursive: true, force: true });
  }

  console.log(`\n--- Downloading tarball from ${tarballUrl} ---`);
  try {
    const tarballData = await pacote.tarball(tarballUrl);
    console.log(`Got ${tarballData.length} bytes of tarball data. Resolved URL: ${tarballData.resolved}`);
  } catch (error) {
    console.error(`Failed to download tarball: ${error.message}`);
  }
}

main().catch(console.error);