0
# local-pkg
1

2
local-pkg provides utilities for working with local npm packages, offering functions to detect package existence, retrieve package information, resolve module paths, and import modules in both CommonJS and ESM environments. It includes comprehensive cross-environment compatibility and works with PnP (Plug'n'Play) package managers.
3

4
## Package Information
5

6
- **Package Name**: local-pkg
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install local-pkg`
10

11
## Core Imports
12

13
```typescript
14
import {
15
  isPackageExists,
16
  getPackageInfo,
17
  getPackageInfoSync,
18
  resolveModule,
19
  importModule,
20
  loadPackageJSON,
21
  loadPackageJSONSync,
22
  isPackageListed,
23
  isPackageListedSync,
24
  type PackageInfo,
25
  type PackageResolvingOptions
26
} from "local-pkg";
27
import type { PackageJson } from "pkg-types";
28
```
29

30
For CommonJS:
31

32
```javascript
33
const {
34
  isPackageExists,
35
  getPackageInfo,
36
  getPackageInfoSync,
37
  resolveModule,
38
  importModule,
39
  loadPackageJSON,
40
  loadPackageJSONSync,
41
  isPackageListed,
42
  isPackageListedSync
43
} = require("local-pkg");
44
```
45

46
## Basic Usage
47

48
```typescript
49
import { isPackageExists, getPackageInfo, resolveModule, importModule } from "local-pkg";
50

51
// Check if package exists
52
const exists = isPackageExists("express");
53
console.log(exists); // true or false
54

55
// Get package information
56
const packageInfo = await getPackageInfo("express");
57
if (packageInfo) {
58
  console.log(packageInfo.name);     // "express"
59
  console.log(packageInfo.version);  // "4.18.2"
60
  console.log(packageInfo.rootPath); // "/path/to/node_modules/express"
61
}
62

63
// Resolve module path (similar to require.resolve)
64
const modulePath = resolveModule("express");
65
console.log(modulePath); // "/path/to/node_modules/express/index.js"
66

67
// Dynamic import that works in both CJS and ESM
68
const express = await importModule("express");
69
```
70

71
## Architecture
72

73
local-pkg is built around several key components:
74

75
- **Package Detection**: Core functions to check package existence and resolve package paths
76
- **Information Retrieval**: Extract comprehensive metadata from packages and package.json files  
77
- **Module Resolution**: Cross-environment module path resolution similar to require.resolve
78
- **Dynamic Imports**: Unified import functionality that works in both CommonJS and ESM contexts
79
- **Synchronous/Asynchronous APIs**: Dual sync/async versions for key operations to support different use cases
80
- **Platform Compatibility**: Handles platform-specific path formats and PnP package managers
81

82
## Capabilities
83

84
### Package Detection
85

86
Core functionality for checking if packages exist and resolving their locations in the local environment.
87

88
```typescript { .api }
89
function isPackageExists(name: string, options?: PackageResolvingOptions): boolean;
90
function resolveModule(name: string, options?: PackageResolvingOptions): string | undefined;
91

92
interface PackageResolvingOptions {
93
  paths?: string[];
94
  platform?: 'posix' | 'win32' | 'auto';
95
}
96
```
97

98
[Package Detection](./package-detection.md)
99

100
### Package Information
101

102
Retrieve comprehensive metadata and information about installed packages, including version, paths, and full package.json contents.
103

104
```typescript { .api }
105
function getPackageInfo(name: string, options?: PackageResolvingOptions): Promise<PackageInfo | undefined>;
106
function getPackageInfoSync(name: string, options?: PackageResolvingOptions): PackageInfo | undefined;
107

108
interface PackageInfo {
109
  name: string;
110
  rootPath: string;
111
  packageJsonPath: string;
112
  version: string;
113
  packageJson: PackageJson;
114
}
115
```
116

117
[Package Information](./package-information.md)
118

119
### Module Importing
120

121
Cross-environment dynamic module importing that works consistently in both CommonJS and ESM contexts.
122

123
```typescript { .api }
124
function importModule<T = any>(path: string): Promise<T>;
125
```
126

127
[Module Importing](./module-importing.md)
128

129
### Package.json Management
130

131
Load and parse package.json files from the current working directory or specified paths, with dependency checking capabilities.
132

133
```typescript { .api }
134
function loadPackageJSON(cwd?: string): Promise<PackageJson | null>;
135
function loadPackageJSONSync(cwd?: string): PackageJson | null;
136
function isPackageListed(name: string, cwd?: string): Promise<boolean>;
137
function isPackageListedSync(name: string, cwd?: string): boolean;
138
```
139

140
[Package.json Management](./package-json-management.md)
141

142
## Types
143

144
```typescript { .api }
145
interface PackageInfo {
146
  name: string;
147
  rootPath: string;
148
  packageJsonPath: string;
149
  version: string;
150
  packageJson: PackageJson;
151
}
152

153
interface PackageResolvingOptions {
154
  paths?: string[];
155
  /**
156
   * @default 'auto'
157
   * Resolve path as posix or win32
158
   */
159
  platform?: 'posix' | 'win32' | 'auto';
160
}
161

162
// Note: PackageJson type is imported from 'pkg-types' package
163
// Contains standard package.json fields like name, version, dependencies, etc.
164
type PackageJson = import('pkg-types').PackageJson;
165
```