0
# @pnpm/exportable-manifest
1

2
@pnpm/exportable-manifest creates exportable package manifests by resolving workspace dependencies for pnpm's publishing workflow. It transforms package.json files to prepare them for publishing by resolving workspace protocol dependencies, catalog protocol dependencies, and JSR protocol dependencies to their concrete versions.
3

4
## Package Information
5

6
- **Package Name**: @pnpm/exportable-manifest
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `pnpm add @pnpm/exportable-manifest`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  createExportableManifest, 
16
  overridePublishConfig,
17
  type MakePublishManifestOptions,
18
  type PublishDependencyConverter 
19
} from "@pnpm/exportable-manifest";
20
```
21

22
For CommonJS:
23

24
```javascript
25
const { createExportableManifest, overridePublishConfig } = require("@pnpm/exportable-manifest");
26
```
27

28
## Basic Usage
29

30
```typescript
31
import { createExportableManifest } from "@pnpm/exportable-manifest";
32
import { type ProjectManifest } from "@pnpm/types";
33
import { type Catalogs } from "@pnpm/catalogs.types";
34

35
// Basic manifest transformation
36
const originalManifest: ProjectManifest = {
37
  name: "my-package",
38
  version: "1.0.0",
39
  dependencies: {
40
    "workspace-dep": "workspace:^",
41
    "catalog-dep": "catalog:",
42
    "jsr-dep": "jsr:@scope/package@1.0.0"
43
  },
44
  pnpm: {
45
    overrides: {
46
      "some-dep": "2.0.0"
47
    }
48
  },
49
  scripts: {
50
    prepublishOnly: "npm run build",
51
    test: "jest"
52
  }
53
};
54

55
const catalogs: Catalogs = {
56
  default: {
57
    "catalog-dep": "^2.1.0"
58
  }
59
};
60

61
const exportableManifest = await createExportableManifest(
62
  "/path/to/package",
63
  originalManifest,
64
  { catalogs }
65
);
66

67
// Result will have workspace:, catalog:, and jsr: protocols resolved
68
// pnpm-specific fields removed, and publish scripts removed
69
```
70

71
## Architecture
72

73
@pnpm/exportable-manifest is built around several key transformation components:
74

75
- **Protocol Resolution**: Converts workspace:, catalog:, and jsr: protocols to concrete versions
76
- **Manifest Cleaning**: Removes pnpm-specific fields and publish lifecycle scripts  
77
- **PublishConfig Processing**: Automatically applies publishConfig overrides to main manifest fields
78
- **Dependency Processing**: Handles all dependency types including peers and optionals
79

80
## Capabilities
81

82
### Manifest Export Creation
83

84
Creates publication-ready manifests by resolving all protocol dependencies and cleaning pnpm-specific fields.
85

86
```typescript { .api }
87
/**
88
 * Creates an exportable manifest from a workspace package manifest
89
 * @param dir - Directory path of the package
90
 * @param originalManifest - Original package.json manifest
91
 * @param opts - Options for manifest creation
92
 * @returns Promise resolving to transformed ProjectManifest ready for publishing
93
 */
94
async function createExportableManifest(
95
  dir: string,
96
  originalManifest: ProjectManifest,
97
  opts: MakePublishManifestOptions
98
): Promise<ProjectManifest>;
99

100
interface MakePublishManifestOptions {
101
  /** Catalog configurations for resolving catalog protocol dependencies */
102
  catalogs: Catalogs;
103
  /** Optional path to node_modules directory */
104
  modulesDir?: string;
105
  /** Optional readme file content to add to manifest */
106
  readmeFile?: string;
107
}
108
```
109

110
### PublishConfig Override Processing
111

112
Applies publishConfig overrides to the main manifest fields and removes processed fields.
113

114
```typescript { .api }
115
/**
116
 * Overrides manifest fields with publishConfig values and cleans up publishConfig
117
 * @param publishManifest - Manifest to process publishConfig overrides for
118
 */
119
function overridePublishConfig(publishManifest: ProjectManifest): void;
120
```
121

122

123

124
## Protocol Resolution Details
125

126
### Workspace Protocol Resolution
127

128
Resolves `workspace:` dependencies to their concrete versions:
129

130
- `workspace:*` → `1.2.3` (exact version)
131
- `workspace:^` → `^1.2.3` (caret range)
132
- `workspace:~` → `~1.2.3` (tilde range)
133
- `workspace:./path` → `1.2.3` (relative path resolution)
134
- `workspace:@scope/alias@*` → `npm:@scope/alias@1.2.3` (aliased packages)
135

136
### Catalog Protocol Resolution
137

138
Resolves `catalog:` dependencies using provided catalogs:
139

140
- `catalog:` → Uses default catalog entry for the dependency name
141
- `catalog:named` → Uses named catalog entry
142
- Throws error for misconfigured catalogs
143

144
### JSR Protocol Resolution
145

146
Converts JSR (JavaScript Registry) dependencies to npm equivalents:
147

148
- `jsr:@scope/name@1.0.0` → `npm:@jsr/scope__name@1.0.0`
149
- `jsr:@scope/name` → `npm:@jsr/scope__name`
150

151
## Manifest Transformations
152

153
### Removed Fields
154

155
The following fields are removed from the exported manifest:
156

157
- `pnpm` - pnpm-specific configuration
158
- `packageManager` - Package manager specification
159
- Publish lifecycle scripts: `prepublishOnly`, `prepack`, `prepare`, `postpack`, `publish`, `postpublish`
160

161
### PublishConfig Processing
162

163
The following publishConfig fields are automatically copied to the main manifest by `createExportableManifest`:
164

165
- Module fields: `main`, `module`, `types`, `typings`, `exports`, `browser`, `esnext`, `es2015`, `unpkg`, `umd:main`
166
- System constraints: `os`, `cpu`, `libc`
167
- TypeScript: `typesVersions`
168
- Package metadata: `bin`, `type`, `imports`
169

170
## Error Handling
171

172
The package throws `PnpmError` with code `CANNOT_RESOLVE_WORKSPACE_PROTOCOL` when:
173

174
- Workspace dependencies are not installed
175
- Package manifests are missing name or version fields
176
- Workspace protocol resolution fails
177

178
## Usage Examples
179

180
### Complex Workspace Resolution
181

182
```typescript
183
import { createExportableManifest } from "@pnpm/exportable-manifest";
184

185
const manifest = {
186
  name: "my-workspace-package",
187
  version: "1.0.0",
188
  dependencies: {
189
    "peer-dep": "workspace:^",
190
    "alias-dep": "workspace:@other/name@*", 
191
    "relative-dep": "workspace:../other-package"
192
  },
193
  peerDependencies: {
194
    "peer-workspace": "workspace:>=1.0.0 || ^2.0.0"
195
  },
196
  publishConfig: {
197
    main: "dist/index.js",
198
    types: "dist/index.d.ts"
199
  },
200
  scripts: {
201
    prepublishOnly: "npm run build",
202
    test: "jest"
203
  }
204
};
205

206
const result = await createExportableManifest("/workspace/my-package", manifest, {
207
  catalogs: {}
208
});
209

210
// Result:
211
// {
212
//   name: "my-workspace-package", 
213
//   version: "1.0.0",
214
//   main: "dist/index.js",
215
//   types: "dist/index.d.ts", 
216
//   dependencies: {
217
//     "peer-dep": "^1.2.3",
218
//     "alias-dep": "npm:@other/name@1.0.0",
219
//     "relative-dep": "2.1.0"
220
//   },
221
//   peerDependencies: {  
222
//     "peer-workspace": ">=1.2.3 || ^2.0.0"
223
//   },
224
//   scripts: {
225
//     test: "jest"
226
//   }
227
// }
228
```
229

230
### Catalog Resolution
231

232
```typescript
233
import { createExportableManifest } from "@pnpm/exportable-manifest";
234

235
const manifest = {
236
  name: "catalog-example",
237
  version: "1.0.0", 
238
  dependencies: {
239
    "default-catalog": "catalog:",
240
    "named-catalog": "catalog:react"
241
  }
242
};
243

244
const catalogs = {
245
  default: {
246
    "default-catalog": "^3.1.0"
247
  },
248
  react: {
249
    "named-catalog": "^18.0.0"
250
  }
251
};
252

253
const result = await createExportableManifest("/path", manifest, { catalogs });
254

255
// Result dependencies:
256
// {
257
//   "default-catalog": "^3.1.0",
258
//   "named-catalog": "^18.0.0"  
259
// }
260
```
261

262
### PublishConfig Override
263

264
```typescript
265
import { overridePublishConfig } from "@pnpm/exportable-manifest";
266

267
const manifest = {
268
  name: "example-package",
269
  version: "1.0.0",
270
  main: "src/index.js",
271
  types: "src/index.d.ts",
272
  publishConfig: {
273
    main: "dist/index.js",
274
    types: "dist/index.d.ts",
275
    registry: "https://registry.npmjs.org/"
276
  }
277
};
278

279
// Apply publishConfig overrides
280
overridePublishConfig(manifest);
281

282
// Result:
283
// {
284
//   name: "example-package",
285
//   version: "1.0.0", 
286
//   main: "dist/index.js",        // overridden from publishConfig
287
//   types: "dist/index.d.ts",     // overridden from publishConfig
288
//   publishConfig: {
289
//     registry: "https://registry.npmjs.org/"  // non-whitelisted fields remain
290
//   }
291
// }
292
```
293

294
## Types
295

296
```typescript { .api }
297
// Re-exported from @pnpm/types
298
interface ProjectManifest {
299
  name?: string;
300
  version?: string;
301
  dependencies?: Dependencies;
302
  devDependencies?: Dependencies;
303
  optionalDependencies?: Dependencies;
304
  peerDependencies?: Dependencies;
305
  scripts?: Record<string, string>;
306
  publishConfig?: PublishConfig;
307
  [key: string]: any;
308
}
309

310
interface Dependencies {
311
  [name: string]: string;
312
}
313

314
interface Catalogs {
315
  [catalogName: string]: {
316
    [packageName: string]: string;
317
  };
318
}
319

320
interface PublishConfig {
321
  [key: string]: any;
322
}
323

324
/**
325
 * Function type for converting dependency specifications during publishing
326
 */
327
type PublishDependencyConverter = (
328
  depName: string,
329
  depSpec: string,
330
  dir: string,
331
  modulesDir?: string
332
) => Promise<string> | string;
333
```