tessl/npm-local-pkg

Get information on local packages, providing utilities for package detection, metadata retrieval, module resolution, and cross-environment imports.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Package.json Management

Name: tessl/npm-local-pkg
Author: tessl

Load and parse package.json files from the current working directory or specified paths, with dependency checking capabilities. Provides both synchronous and asynchronous variants for all operations.

Capabilities

Load Package.json (Async)

Load and parse a package.json file from the current directory or specified path.

/**
 * Load package.json from current working directory or specified path (async)
 * @param cwd - Optional working directory path (defaults to process.cwd())
 * @returns Promise resolving to parsed PackageJson object or null if not found
 */
function loadPackageJSON(cwd?: string): Promise<PackageJson | null>;

Usage Examples:

import { loadPackageJSON } from "local-pkg";

// Load from current directory
const pkg = await loadPackageJSON();
if (pkg) {
  console.log(pkg.name);         // Package name
  console.log(pkg.version);      // Package version
  console.log(pkg.dependencies); // Dependencies object
}

// Load from specific directory
const projectPkg = await loadPackageJSON("/path/to/project");
if (projectPkg) {
  console.log(`Project: ${projectPkg.name}@${projectPkg.version}`);
}

// Handle missing package.json
const missing = await loadPackageJSON("/path/without/package");
console.log(missing); // null

Load Package.json (Sync)

Load and parse a package.json file synchronously.

/**
 * Load package.json from current working directory or specified path (sync)
 * @param cwd - Optional working directory path (defaults to process.cwd())
 * @returns Parsed PackageJson object or null if not found
 */
function loadPackageJSONSync(cwd?: string): PackageJson | null;

Usage Examples:

import { loadPackageJSONSync } from "local-pkg";

// Synchronous loading
const pkg = loadPackageJSONSync();
if (pkg) {
  console.log(`Current project: ${pkg.name}@${pkg.version}`);
  
  // Access package.json fields
  console.log("Scripts:", Object.keys(pkg.scripts || {}));
  console.log("Author:", pkg.author);
  console.log("License:", pkg.license);
}

Check Package Dependencies (Async)

Check if a package is listed in dependencies or devDependencies of a package.json.

/**
 * Check if package is listed in dependencies or devDependencies (async)
 * @param name - Package name to check for
 * @param cwd - Optional working directory path (defaults to process.cwd())
 * @returns Promise resolving to true if package is listed, false otherwise
 */
function isPackageListed(name: string, cwd?: string): Promise<boolean>;

Usage Examples:

import { isPackageListed } from "local-pkg";

// Check if package is a dependency
const hasExpress = await isPackageListed("express");
console.log(hasExpress); // true if express is in dependencies or devDependencies

// Check in specific project directory
const hasLodash = await isPackageListed("lodash", "/path/to/project");

// Useful for conditional logic
if (await isPackageListed("typescript")) {
  console.log("TypeScript project detected");
}

if (await isPackageListed("jest")) {
  console.log("Jest testing framework available");
}

Check Package Dependencies (Sync)

Check if a package is listed in dependencies or devDependencies synchronously.

/**
 * Check if package is listed in dependencies or devDependencies (sync)
 * @param name - Package name to check for
 * @param cwd - Optional working directory path (defaults to process.cwd())
 * @returns true if package is listed, false otherwise
 */
function isPackageListedSync(name: string, cwd?: string): boolean;

Usage Examples:

import { isPackageListedSync } from "local-pkg";

// Synchronous dependency checking
const hasTailwind = isPackageListedSync("tailwindcss");
const hasReact = isPackageListedSync("react");

if (hasTailwind && hasReact) {
  console.log("React + Tailwind project detected");
}

// Build tool detection
const buildTools = ["webpack", "vite", "rollup", "parcel"]
  .filter(tool => isPackageListedSync(tool));
console.log("Available build tools:", buildTools);

Dependency Detection Behavior

The isPackageListed and isPackageListedSync functions check both dependencies and devDependencies fields in package.json:

// Given a package.json like:
{
  "dependencies": {
    "express": "^4.18.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "jest": "^29.0.0"
  }
}

// All of these return true:
await isPackageListed("express");     // Found in dependencies
await isPackageListed("typescript");  // Found in devDependencies  
await isPackageListed("jest");        // Found in devDependencies

// This returns false:
await isPackageListed("lodash");      // Not found in either

Error Handling

All functions handle missing or invalid package.json files gracefully:

loadPackageJSON and loadPackageJSONSync return null when package.json is not found
isPackageListed and isPackageListedSync return false when package.json is missing or doesn't contain the specified package
Invalid JSON in package.json will cause the functions to throw parsing errors

// Safe usage pattern
const pkg = await loadPackageJSON("/some/path");
if (pkg) {
  // package.json exists and was parsed successfully
  const isDev = await isPackageListed("nodemon");
} else {
  console.log("No package.json found");
}