0
# Package.json Management
1

2
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.
3

4
## Capabilities
5

6
### Load Package.json (Async)
7

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

10
```typescript { .api }
11
/**
12
 * Load package.json from current working directory or specified path (async)
13
 * @param cwd - Optional working directory path (defaults to process.cwd())
14
 * @returns Promise resolving to parsed PackageJson object or null if not found
15
 */
16
function loadPackageJSON(cwd?: string): Promise<PackageJson | null>;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { loadPackageJSON } from "local-pkg";
23

24
// Load from current directory
25
const pkg = await loadPackageJSON();
26
if (pkg) {
27
  console.log(pkg.name);         // Package name
28
  console.log(pkg.version);      // Package version
29
  console.log(pkg.dependencies); // Dependencies object
30
}
31

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

38
// Handle missing package.json
39
const missing = await loadPackageJSON("/path/without/package");
40
console.log(missing); // null
41
```
42

43
### Load Package.json (Sync)
44

45
Load and parse a package.json file synchronously.
46

47
```typescript { .api }
48
/**
49
 * Load package.json from current working directory or specified path (sync)
50
 * @param cwd - Optional working directory path (defaults to process.cwd())
51
 * @returns Parsed PackageJson object or null if not found
52
 */
53
function loadPackageJSONSync(cwd?: string): PackageJson | null;
54
```
55

56
**Usage Examples:**
57

58
```typescript
59
import { loadPackageJSONSync } from "local-pkg";
60

61
// Synchronous loading
62
const pkg = loadPackageJSONSync();
63
if (pkg) {
64
  console.log(`Current project: ${pkg.name}@${pkg.version}`);
65
  
66
  // Access package.json fields
67
  console.log("Scripts:", Object.keys(pkg.scripts || {}));
68
  console.log("Author:", pkg.author);
69
  console.log("License:", pkg.license);
70
}
71
```
72

73
### Check Package Dependencies (Async)
74

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

77
```typescript { .api }
78
/**
79
 * Check if package is listed in dependencies or devDependencies (async)
80
 * @param name - Package name to check for
81
 * @param cwd - Optional working directory path (defaults to process.cwd())
82
 * @returns Promise resolving to true if package is listed, false otherwise
83
 */
84
function isPackageListed(name: string, cwd?: string): Promise<boolean>;
85
```
86

87
**Usage Examples:**
88

89
```typescript
90
import { isPackageListed } from "local-pkg";
91

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

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

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

104
if (await isPackageListed("jest")) {
105
  console.log("Jest testing framework available");
106
}
107
```
108

109
### Check Package Dependencies (Sync)
110

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

113
```typescript { .api }
114
/**
115
 * Check if package is listed in dependencies or devDependencies (sync)
116
 * @param name - Package name to check for
117
 * @param cwd - Optional working directory path (defaults to process.cwd())
118
 * @returns true if package is listed, false otherwise
119
 */
120
function isPackageListedSync(name: string, cwd?: string): boolean;
121
```
122

123
**Usage Examples:**
124

125
```typescript
126
import { isPackageListedSync } from "local-pkg";
127

128
// Synchronous dependency checking
129
const hasTailwind = isPackageListedSync("tailwindcss");
130
const hasReact = isPackageListedSync("react");
131

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

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

142
## Dependency Detection Behavior
143

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

146
```typescript
147
// Given a package.json like:
148
{
149
  "dependencies": {
150
    "express": "^4.18.0"
151
  },
152
  "devDependencies": {
153
    "typescript": "^5.0.0",
154
    "jest": "^29.0.0"
155
  }
156
}
157

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

163
// This returns false:
164
await isPackageListed("lodash");      // Not found in either
165
```
166

167
## Error Handling
168

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

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

175
```typescript
176
// Safe usage pattern
177
const pkg = await loadPackageJSON("/some/path");
178
if (pkg) {
179
  // package.json exists and was parsed successfully
180
  const isDev = await isPackageListed("nodemon");
181
} else {
182
  console.log("No package.json found");
183
}
184
```