CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-pnpm--store-path

Resolves optimal pnpm store path locations based on filesystem capabilities and project structure

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

index.mddocs/

@pnpm/store-path

@pnpm/store-path provides intelligent store path resolution for pnpm package manager installations. It determines the optimal location for the pnpm store directory based on filesystem capabilities, project location, and system permissions, ensuring maximum performance through hard linking when possible.

Package Information

  • Package Name: @pnpm/store-path
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @pnpm/store-path

Core Imports

import { getStorePath } from "@pnpm/store-path";

For CommonJS:

const { getStorePath } = require("@pnpm/store-path");

Basic Usage

import { getStorePath } from "@pnpm/store-path";

// Resolve store path with explicit location
const storePath = getStorePath({
  pkgRoot: "/home/user/my-project",
  storePath: "/custom/pnpm-store",
  pnpmHomeDir: "/home/user/.local/share/pnpm"
});
// Returns: "/custom/pnpm-store/v10"

// Resolve optimal store path based on filesystem capabilities
const optimalPath = await getStorePath({
  pkgRoot: "/home/user/my-project", 
  pnpmHomeDir: "/home/user/.local/share/pnpm"
});
// Returns: Promise<string> - optimal location based on hard linking support

Architecture

The store path resolution follows a three-tier strategy:

  1. Explicit Path: When storePath is provided, use it directly (appending store version if needed)
  2. Home-relative Path: For paths starting with ~/, resolve relative to user home directory
  3. Filesystem Optimization: Automatically determine optimal location based on hard linking capabilities:
    • Test linking between project location and potential store locations
    • Prefer pnpm home directory if linking works across filesystems
    • Fall back to filesystem root with .pnpm-store prefix if linking only works locally
    • Ultimate fallback to pnpm home directory if no linking is possible

Capabilities

Store Path Resolution

Intelligently resolves the optimal pnpm store path location based on filesystem capabilities and configuration options.

/**
 * Resolves the optimal pnpm store path based on filesystem capabilities
 * @param options - Configuration options for store path resolution
 * @returns Store path string (sync) or Promise<string> (async when optimization needed)
 * @throws PnpmError with code 'NO_PNPM_HOME_DIR' when pnpmHomeDir is undefined and storePath not provided
 */
function getStorePath(options: GetStorePathOptions): string | Promise<string>;

interface GetStorePathOptions {
  /** Root directory of the package/project */
  pkgRoot: string;
  /** 
   * Optional explicit store path - can be absolute or home-relative (~/path)
   * When provided, skips filesystem optimization and uses this path directly
   */
  storePath?: string;
  /** 
   * Pnpm home directory for fallback store location
   * Required when storePath is not provided
   */
  pnpmHomeDir: string;
}

Usage Examples:

import { getStorePath } from "@pnpm/store-path";

// Explicit absolute store path
const explicitPath = getStorePath({
  pkgRoot: "/home/user/project",
  storePath: "/var/cache/pnpm",
  pnpmHomeDir: "/home/user/.local/share/pnpm"
});
// Returns: "/var/cache/pnpm/v10" (synchronous)

// Home-relative store path
const homePath = getStorePath({
  pkgRoot: "/home/user/project", 
  storePath: "~/custom-store",
  pnpmHomeDir: "/home/user/.local/share/pnpm"
});
// Returns: "/home/user/custom-store/v10" (synchronous)

// Optimized store path (filesystem linking detection)
const optimizedPath = await getStorePath({
  pkgRoot: "/mnt/external/project",
  pnpmHomeDir: "/home/user/.local/share/pnpm"
});
// Returns: Promise<string> - optimal location after testing hard linking capabilities

// Error handling
try {
  getStorePath({
    pkgRoot: "/some/project",
    pnpmHomeDir: undefined // This will throw an error
  });
} catch (error) {
  console.log(error.code); // 'NO_PNPM_HOME_DIR'
}

Error Handling

The package throws PnpmError instances from the @pnpm/error package:

// Error thrown when pnpmHomeDir is not provided and storePath is undefined
interface PnpmError extends Error {
  code: 'NO_PNPM_HOME_DIR';
  message: 'The pnpm home directory is unknown. Cannot calculate the store directory location.';
}

Constants

The package uses the STORE_VERSION constant from @pnpm/constants, which is currently "v10". This version is automatically appended to store paths to maintain compatibility across pnpm versions.

Platform Support

  • Node.js: Requires Node.js >= 18.12
  • Cross-platform: Handles both Unix (~/) and Windows (~\\) home directory notation
  • Filesystem agnostic: Works with various filesystem types, optimizing based on hard linking support

Install with Tessl CLI

npx tessl i tessl/npm-pnpm--store-path

docs

index.md

tile.json