0
# @lerna/pack-directory
1

2
Pack a directory into an npm package tarball. This utility handles the complete packaging workflow including lifecycle script execution, file listing, and tar archive creation, primarily designed for use within the Lerna monorepo management system.
3

4
## Package Information
5

6
- **Package Name**: @lerna/pack-directory
7
- **Package Type**: npm  
8
- **Language**: JavaScript
9
- **Node.js**: ^14.15.0 || >=16.0.0
10
- **Installation**: This is an internal Lerna utility. Install via `npm install lerna` for access to Lerna tools.
11

12
## Core Imports
13

14
```javascript
15
const { packDirectory } = require("@lerna/pack-directory");
16
```
17

18
For ES modules:
19

20
```javascript
21
import { packDirectory } from "@lerna/pack-directory";
22
```
23

24
## Basic Usage
25

26
```javascript
27
const { packDirectory } = require("@lerna/pack-directory");
28
const { Package } = require("@lerna/package");
29

30
// Pack a package directory
31
const pkg = new Package(packageJsonPath, packageDirectory);
32
const packedData = await packDirectory(pkg, pkg.location, {
33
  log: require("npmlog"),
34
  lernaCommand: "publish"
35
});
36

37
console.log(`Created tarball: ${packedData.tarFilePath}`);
38
console.log(`Package size: ${packedData.size} bytes`);
39
```
40

41
## Architecture
42

43
The package follows a sequential lifecycle approach:
44

45
- **Lifecycle Execution**: Runs npm lifecycle scripts in proper order (prepublish, prepare, prepublishOnly, prepack, postpack)
46
- **File Collection**: Uses npm-packlist to determine which files to include in the tarball
47
- **Archive Creation**: Creates compressed tar archives with specific metadata for reproducible builds
48
- **Integration**: Works seamlessly with other Lerna utilities for package management
49

50
## Capabilities
51

52
### Pack Directory
53

54
Creates a tarball from a directory suitable for npm publishing, with full lifecycle script execution and metadata generation.
55

56
```javascript { .api }
57
/**
58
 * Pack a directory suitable for publishing, writing tarball to a tempfile
59
 * @param {Package|string} pkg - Package instance or path to manifest
60
 * @param {string} dir - Directory to pack  
61
 * @param {PackConfig} options - Configuration options
62
 * @returns {Promise<PackedData>} Packed tarball metadata object
63
 */
64
function packDirectory(pkg, dir, options);
65
```
66

67
**Parameters:**
68

69
- `pkg` (Package|string): Package instance from @lerna/package or path to package.json
70
- `dir` (string): Directory path to pack (typically the package root directory)
71
- `options` (PackConfig): Configuration object controlling packing behavior
72

73
**Returns:** Promise resolving to a `PackedData` object containing tarball metadata.
74

75
**Usage Example:**
76

77
```javascript
78
const { packDirectory } = require("@lerna/pack-directory");
79
const { Package } = require("@lerna/package");
80

81
// Using Package instance
82
const pkg = new Package("/path/to/package.json", "/path/to/package");
83
const result = await packDirectory(pkg, pkg.location, {
84
  log: require("npmlog"),
85
  lernaCommand: "publish",
86
  ignorePrepublish: false
87
});
88

89
// Using string path
90
const result = await packDirectory(
91
  "/path/to/package.json",
92
  "/path/to/package", 
93
  { log: require("npmlog") }
94
);
95
```
96

97
## Types
98

99
```javascript { .api }
100
/**
101
 * Configuration object for packDirectory function
102
 * @typedef {Object} PackConfig
103
 * @property {typeof log} [log] - Logger instance (defaults to npmlog)
104
 * @property {string} [lernaCommand] - If "publish", run "prepublishOnly" lifecycle
105
 * @property {boolean} [ignorePrepublish] - Skip prepublish lifecycle scripts
106
 */
107

108
/**
109
 * Packed tarball metadata returned by packDirectory
110
 * @typedef {Object} PackedData
111
 * @property {Array} bundled - Array of bundled dependencies
112
 * @property {number} entryCount - Number of entries in the tarball
113
 * @property {string} filename - Generated tarball filename (e.g., "my-package-1.0.0.tgz")
114
 * @property {Array<FileEntry>} files - Array of file objects with path, size, and mode
115
 * @property {string} id - Package identifier in format "name@version"
116
 * @property {Object} integrity - Integrity hash object for verification
117
 * @property {string} name - Package name
118
 * @property {string} shasum - SHA checksum of the tarball
119
 * @property {number} size - Total tarball size in bytes
120
 * @property {string} tarFilePath - Absolute path to the generated tarball file
121
 * @property {number} unpackedSize - Total unpacked size in bytes
122
 * @property {string} version - Package version
123
 */
124

125
/**
126
 * File entry in the packed tarball
127
 * @typedef {Object} FileEntry
128
 * @property {string} path - Relative file path within the package
129
 * @property {number} size - File size in bytes
130
 * @property {string} mode - File permissions mode
131
 */
132
```
133

134
## Lifecycle Script Integration
135

136
The packDirectory function executes npm lifecycle scripts in the following order:
137

138
1. **prepublish** (unless `ignorePrepublish: true`)
139
2. **prepare** 
140
3. **prepublishOnly** (only if `lernaCommand === "publish"`)
141
4. **prepack**
142
5. **postpack** (after tarball creation)
143

144
Scripts are executed using `@lerna/run-lifecycle` with the provided logger and options.
145

146
## Error Handling
147

148
The function returns a rejected Promise if:
149
- Package directory or manifest cannot be read
150
- Lifecycle scripts fail with non-zero exit codes
151
- File listing or tar creation encounters errors
152
- Temporary file operations fail
153

154
Common error scenarios:
155
- Missing package.json file
156
- Invalid package.json format
157
- Lifecycle script failures
158
- File permission issues
159
- Disk space limitations