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

Module Importing

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

Cross-environment dynamic module importing that works consistently in both CommonJS and ESM contexts, providing a unified interface for dynamic imports with proper interop handling.

Capabilities

Dynamic Module Import

Import modules dynamically with automatic interop handling for cross-environment compatibility.

/**
 * Import modules dynamically with cross-environment compatibility
 * @param path - Module path to import (can be package name or file path)
 * @returns Promise resolving to the imported module with proper interop
 */
function importModule<T = any>(path: string): Promise<T>;

Usage Examples:

import { importModule } from "local-pkg";

// Import a package by name
const express = await importModule("express");
const app = express();

// Import specific utilities from a package
const { join } = await importModule("node:path");
const fullPath = join("/home", "user", "file.txt");

// Import from a resolved path
const modulePath = "/path/to/node_modules/lodash/index.js";
const lodash = await importModule(modulePath);
const result = lodash.map([1, 2, 3], x => x * 2);

// Generic type support
interface MyModule {
  doSomething: (x: string) => number;
}
const myModule = await importModule<MyModule>("./my-module.js");
const result = myModule.doSomething("hello");

Cross-Environment Compatibility

The importModule function handles the differences between CommonJS and ESM module systems automatically:

ESM Environment

// In ESM context
const chalk = await importModule("chalk");
// Equivalent to: const chalk = await import("chalk");

CommonJS Environment

// In CJS context - works the same way
const chalk = await importModule("chalk");
// Handles interop automatically, equivalent to dynamic import with proper default handling

Interop Handling

The function automatically handles default export interop, ensuring consistent behavior regardless of how the target module was exported:

// These all work correctly regardless of module format
const express = await importModule("express");           // Default export
const { readFile } = await importModule("node:fs/promises"); // Named exports
const entire = await importModule("some-package");       // Mixed exports

Error Handling

Import failures are handled through standard Promise rejection:

import { importModule } from "local-pkg";

try {
  const module = await importModule("nonexistent-package");
} catch (error) {
  console.error("Failed to import module:", error.message);
}

// Or with promise chaining
importModule("some-package")
  .then(module => {
    // Use the imported module
    console.log(module);
  })
  .catch(error => {
    console.error("Import failed:", error);
  });

Type Safety

The function supports TypeScript generics for type-safe imports when you know the shape of the imported module:

// Define the expected module interface
interface UtilityModule {
  helper: (input: string) => string;
  constant: number;
}

// Import with type safety
const utils = await importModule<UtilityModule>("./utils");
utils.helper("test"); // TypeScript knows this exists and its signature
console.log(utils.constant); // TypeScript knows this is a number