CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-pnpm--find-workspace-dir

Finds the root of a pnpm workspace by searching for pnpm-workspace.yaml files

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

@pnpm/find-workspace-dir

@pnpm/find-workspace-dir is a utility library that finds the root directory of a pnpm workspace by searching for pnpm-workspace.yaml files. It supports environment variable overrides and handles case-insensitive file systems correctly.

Package Information

  • Package Name: @pnpm/find-workspace-dir
  • Package Type: npm
  • Language: TypeScript
  • Installation: pnpm add @pnpm/find-workspace-dir

Core Imports

import { findWorkspaceDir } from "@pnpm/find-workspace-dir";
import { PnpmError } from "@pnpm/error";

For CommonJS:

const { findWorkspaceDir } = require("@pnpm/find-workspace-dir");
const { PnpmError } = require("@pnpm/error");

Basic Usage

import { findWorkspaceDir } from "@pnpm/find-workspace-dir";

// Find workspace directory from current working directory
const workspaceDir = await findWorkspaceDir(process.cwd());

if (workspaceDir) {
  console.log(`Found workspace at: ${workspaceDir}`);
} else {
  console.log("No workspace found");
}

// Find workspace directory from a specific path
const workspaceDir2 = await findWorkspaceDir("/path/to/project");

Capabilities

Workspace Directory Discovery

Finds the root directory of a pnpm workspace by searching for pnpm-workspace.yaml files in the current directory and parent directories.

/**
 * Finds the root directory of a pnpm workspace by searching for pnpm-workspace.yaml files
 * @param cwd - Current working directory to start searching from
 * @returns Promise resolving to workspace directory path or undefined if not found
 * @throws PnpmError with code 'ERR_PNPM_BAD_WORKSPACE_MANIFEST_NAME' if invalid workspace manifest filename is found
 */
function findWorkspaceDir(cwd: string): Promise<string | undefined>;

Behavior:

  • Searches for pnpm-workspace.yaml files starting from the provided directory and moving up the directory tree
  • Respects the NPM_CONFIG_WORKSPACE_DIR (or npm_config_workspace_dir) environment variable for workspace directory override
  • Handles case-insensitive file systems by resolving real native paths
  • Throws an error if invalid workspace manifest filenames are detected (pnpm-workspaces.yaml, pnpm-workspaces.yml, pnpm-workspace.yml)

Usage Examples:

import { findWorkspaceDir } from "@pnpm/find-workspace-dir";
import { PnpmError } from "@pnpm/error";

// Basic usage
try {
  const workspaceDir = await findWorkspaceDir(process.cwd());
  if (workspaceDir) {
    console.log(`Workspace found at: ${workspaceDir}`);
  } else {
    console.log("No pnpm workspace found");
  }
} catch (error) {
  if (error instanceof PnpmError && error.code === 'ERR_PNPM_BAD_WORKSPACE_MANIFEST_NAME') {
    console.error('Invalid workspace manifest filename:', error.message);
  }
}

// Using environment variable override
process.env.NPM_CONFIG_WORKSPACE_DIR = '/custom/workspace/path';
const workspaceDir = await findWorkspaceDir(process.cwd());
// Returns '/custom/workspace/path' regardless of cwd

Error Handling

The function throws a PnpmError when invalid workspace manifest filenames are detected:

class PnpmError extends Error {
  readonly code: string;
  readonly hint?: string;
  attempts?: number;
  prefix?: string;
  pkgsStack?: Array<{ id: string, name: string, version: string }>;
  
  constructor(
    code: string,
    message: string,
    opts?: {
      attempts?: number;
      hint?: string;
    }
  );
}

Error Codes:

  • ERR_PNPM_BAD_WORKSPACE_MANIFEST_NAME: Thrown when an invalid workspace manifest filename is found (e.g., pnpm-workspaces.yaml instead of pnpm-workspace.yaml)

Environment Variables

NPM_CONFIG_WORKSPACE_DIR / npm_config_workspace_dir

When set, either of these environment variables overrides the workspace directory search and directly returns the specified path. The function appends pnpm-workspace.yaml to this path as the workspace manifest location. The function checks both NPM_CONFIG_WORKSPACE_DIR and npm_config_workspace_dir (the lowercase variant).

# Override workspace directory (either format works)
export NPM_CONFIG_WORKSPACE_DIR="/path/to/workspace"
# or
export npm_config_workspace_dir="/path/to/workspace"

Node.js Compatibility

  • Minimum Node.js Version: 18.12
  • Module Type: CommonJS
  • TypeScript Support: Full type definitions included

docs

index.md

tile.json