0
# @pnpm/modules-cleaner
1

2
@pnpm/modules-cleaner provides utility functions for cleaning up node_modules directories in pnpm-managed projects. The main functionality is pruning redundant packages by comparing wanted and current lockfiles to remove packages that are no longer needed.
3

4
## Package Information
5

6
- **Package Name**: @pnpm/modules-cleaner
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `pnpm install @pnpm/modules-cleaner`
10

11
## Core Imports
12

13
```typescript
14
import { prune } from "@pnpm/modules-cleaner";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { prune } = require("@pnpm/modules-cleaner");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { prune } from "@pnpm/modules-cleaner";
27
import type { LockfileObject } from "@pnpm/lockfile.types";
28
import type { StoreController } from "@pnpm/store-controller-types";
29

30
// Example pruning operation
31
const removedPackages = await prune(
32
  [
33
    {
34
      binsDir: "/project/node_modules/.bin",
35
      id: ".",
36
      modulesDir: "/project/node_modules",
37
      pruneDirectDependencies: true,
38
      rootDir: "/project"
39
    }
40
  ],
41
  {
42
    include: {
43
      dependencies: true,
44
      devDependencies: false,
45
      optionalDependencies: true
46
    },
47
    hoistedDependencies: {},
48
    wantedLockfile: wantedLockfile,
49
    currentLockfile: currentLockfile,
50
    skipped: new Set(),
51
    virtualStoreDir: "/project/node_modules/.pnpm",
52
    virtualStoreDirMaxLength: 120,
53
    lockfileDir: "/project",
54
    storeController: storeController
55
  }
56
);
57

58
console.log(`Removed ${removedPackages.size} packages`);
59
```
60

61
## Capabilities
62

63
### Package Pruning
64

65
Compares the wanted lockfile with the current one and removes redundant packages from node_modules. This is the main exported function that handles cleanup of unnecessary dependencies.
66

67
```typescript { .api }
68
/**
69
 * Prunes redundant packages from node_modules by comparing wanted and current lockfiles
70
 * @param importers - Array of importer configurations defining projects to clean
71
 * @param opts - Configuration options for pruning operation
72
 * @returns Promise resolving to Set of orphaned dependency paths that were processed
73
 */
74
function prune(
75
  importers: Array<{
76
    /** Directory containing binary files for the project */
77
    binsDir: string;
78
    /** Project identifier, typically "." for root project */
79
    id: ProjectId;
80
    /** Directory containing node_modules for the project */
81
    modulesDir: string;
82
    /** Whether to prune direct dependencies */
83
    pruneDirectDependencies?: boolean;
84
    /** Specific packages to remove */
85
    removePackages?: string[];
86
    /** Root directory of the project */
87
    rootDir: ProjectRootDir;
88
  }>,
89
  opts: {
90
    /** Whether to deduplicate direct dependencies */
91
    dedupeDirectDeps?: boolean;
92
    /** If true, only simulate the operation without making changes */
93
    dryRun?: boolean;
94
    /** Which dependency types to include in pruning */
95
    include: { [dependenciesField in DependenciesField]: boolean };
96
    /** Map of hoisted dependencies by dependency path */
97
    hoistedDependencies: HoistedDependencies;
98
    /** Directory for hoisted modules */
99
    hoistedModulesDir?: string;
100
    /** Directory for publicly hoisted modules */
101
    publicHoistedModulesDir?: string;
102
    /** The desired state lockfile */
103
    wantedLockfile: LockfileObject;
104
    /** The current state lockfile */
105
    currentLockfile: LockfileObject;
106
    /** Whether to prune the store */
107
    pruneStore?: boolean;
108
    /** Whether to prune the virtual store */
109
    pruneVirtualStore?: boolean;
110
    /** Set of dependency paths to skip */
111
    skipped: Set<DepPath>;
112
    /** Directory containing the virtual store */
113
    virtualStoreDir: string;
114
    /** Maximum length for virtual store directory names */
115
    virtualStoreDirMaxLength: number;
116
    /** Directory containing the lockfile */
117
    lockfileDir: string;
118
    /** Store controller for package operations */
119
    storeController: StoreController;
120
  }
121
): Promise<Set<string>>;
122
```
123

124
## Types
125

126
**Note:** Most types used by this package are re-exported from other @pnpm ecosystem packages. The definitions below show the essential structure needed for using the `prune` function. For complete type details, import directly from the source packages.
127

128
```typescript { .api }
129
// Core types from @pnpm/types
130
type ProjectId = string;
131
type ProjectRootDir = string;
132
type DepPath = string;
133
type DependenciesField = "dependencies" | "devDependencies" | "optionalDependencies";
134

135
interface HoistedDependencies {
136
  [depPath: string]: {
137
    [alias: string]: "public" | "private";
138
  };
139
}
140

141
// Lockfile types from @pnpm/lockfile.types
142
interface LockfileObject {
143
  importers: Record<ProjectId, ProjectSnapshot>;
144
  packages?: PackageSnapshots;
145
  lockfileVersion: string;
146
  // Additional properties may be present
147
}
148

149
interface ProjectSnapshot {
150
  dependencies?: Record<string, string>;
151
  devDependencies?: Record<string, string>;
152
  optionalDependencies?: Record<string, string>;
153
  // Additional dependency types and properties may be present
154
}
155

156
interface PackageSnapshots {
157
  [packagePath: string]: PackageSnapshot;
158
}
159

160
interface PackageSnapshot {
161
  resolution: {
162
    integrity?: string;
163
    tarball?: string;
164
    // Additional resolution properties may be present
165
  };
166
  dependencies?: Record<string, string>;
167
  devDependencies?: Record<string, string>;
168
  optionalDependencies?: Record<string, string>;
169
  // Additional dependency types and properties may be present
170
}
171

172
// Store controller type from @pnpm/store-controller-types
173
interface StoreController {
174
  requestPackage: RequestPackageFunction;
175
  fetchPackage: FetchPackageToStoreFunction | FetchPackageToStoreFunctionAsync;
176
  getFilesIndexFilePath: GetFilesIndexFilePath;
177
  importPackage: ImportPackageFunctionAsync;
178
  close(): Promise<void>;
179
  prune(removeAlienFiles?: boolean): Promise<void>;
180
  upload: UploadPkgToStore;
181
  clearResolutionCache(): void;
182
}
183

184
// Note: RequestPackageFunction, FetchPackageToStoreFunction, and other complex types
185
// are available from @pnpm/store-controller-types. Import them directly for complete signatures.
186
```