Package Publishing
Overview
Covers modern npm package authoring: package.json configuration with the exports field, dual ESM/CJS builds, TypeScript type declarations, and secure publishing workflows with provenance.
When to use: Configuring package entry points, setting up conditional exports, building dual-format packages, publishing scoped packages, or troubleshooting module resolution.
When NOT to use: Application-level bundling (Vite/webpack app configs), monorepo workspace orchestration (Turborepo/Nx), private registry setup (Verdaccio/Artifactory).
Quick Reference
| Pattern |
Field / Command |
Key Points |
| Entry point |
exports in package.json |
Replaces main/module; encapsulates internals |
| CJS fallback |
main |
Legacy consumers without exports support |
| ESM entry |
module |
Bundler convention; not used by Node.js |
| Type declarations |
types condition in exports |
Must be listed first in each condition block |
| Subpath exports |
"./utils": { ... } |
Clean public API; blocks deep imports |
| Conditional exports |
import/require conditions |
Toggle ESM vs CJS per consumer |
| Package type |
"type": "module" |
Makes .js files ESM; use .cjs for CommonJS |
| Side effects |
"sideEffects": false |
Enables tree-shaking in bundlers |
| Peer deps |
peerDependencies |
Shared runtime deps (React, Vue, etc.) |
| Engine constraints |
"engines": { "node": ">=18" } |
Document minimum Node.js version |
| Files allowlist |
"files": ["dist"] |
Controls what gets published to npm |
| Prepublish check |
"prepublishOnly": "npm run build" |
Ensure build runs before publish |
| Dry run |
npm pack --dry-run |
Preview package contents before publishing |
| Provenance |
--provenance flag or trusted publishers |
Cryptographic build attestation |
| Scoped publish |
--access public |
Required for first publish of scoped packages |
Common Mistakes
| Mistake |
Correct Pattern |
Putting types after default in exports |
types must be the first condition in every export block |
Missing "./package.json" in exports |
Include "./package.json": "./package.json" for tooling compatibility |
Different APIs for import vs require |
Same API surface; write ESM source, transpile to CJS |
Using main without exports for new packages |
Use exports as the primary entry point definition |
Forgetting "type": "module" with .js ESM output |
Set "type": "module" or use .mjs extension explicitly |
Publishing src/ or node_modules/ |
Use "files" allowlist to include only dist/ |
No prepublishOnly script |
Add build step to prevent publishing stale artifacts |
Using default export for libraries |
Prefer named exports for consistent cross-tooling behavior |
Not testing with npm pack before publish |
Always dry-run to verify package contents and size |
Omitting peerDependencies for framework plugins |
Declare shared runtime dependencies as peers |
| Publishing without provenance |
Enable provenance for supply-chain transparency |
Using .d.ts for CJS when package is "type": "module" |
Use .d.cts for CJS type declarations, .d.ts or .d.mts for ESM |
Delegation
- Build tooling setup: Use
Explore agent to examine tsup/unbuild/rollup configs
- Type resolution debugging: Use
Task agent with "Are the Types Wrong?" (attw)
- Publish pipeline review: Delegate to
code-reviewer agent
References
- Package.json configuration: exports, main, types, files, engines, peerDependencies
- Build scripts, prepublishOnly, npm pack, provenance, scoped packages
- Dual ESM/CJS builds, conditional exports, type declarations
1---
2name: package-publishing
3description: 'npm package publishing patterns for modern TypeScript libraries. Use when configuring package.json exports, setting up dual ESM/CJS builds, or publishing to npm. Use for npm-publish, package-json, exports, main, module, types, dual-package, provenance, prepublishOnly.'
4license: MIT
5metadata:
6 author: oakoss
7 version: '1.0'
8 source: 'https://docs.npmjs.com/cli/v10/configuring-npm/package-json'
9user-invocable: false
10---
11
12# Package Publishing
13
14## Overview
15
16Covers modern npm package authoring: `package.json` configuration with the `exports` field, dual ESM/CJS builds, TypeScript type declarations, and secure publishing workflows with provenance.
17
18**When to use:** Configuring package entry points, setting up conditional exports, building dual-format packages, publishing scoped packages, or troubleshooting module resolution.
19
20**When NOT to use:** Application-level bundling (Vite/webpack app configs), monorepo workspace orchestration (Turborepo/Nx), private registry setup (Verdaccio/Artifactory).
21
22## Quick Reference
23
24| Pattern | Field / Command | Key Points |
25| ------------------- | ----------------------------------------- | ------------------------------------------------ |
26| Entry point | `exports` in package.json | Replaces `main`/`module`; encapsulates internals |
27| CJS fallback | `main` | Legacy consumers without `exports` support |
28| ESM entry | `module` | Bundler convention; not used by Node.js |
29| Type declarations | `types` condition in `exports` | Must be listed first in each condition block |
30| Subpath exports | `"./utils": { ... }` | Clean public API; blocks deep imports |
31| Conditional exports | `import`/`require` conditions | Toggle ESM vs CJS per consumer |
32| Package type | `"type": "module"` | Makes `.js` files ESM; use `.cjs` for CommonJS |
33| Side effects | `"sideEffects": false` | Enables tree-shaking in bundlers |
34| Peer deps | `peerDependencies` | Shared runtime deps (React, Vue, etc.) |
35| Engine constraints | `"engines": { "node": ">=18" }` | Document minimum Node.js version |
36| Files allowlist | `"files": ["dist"]` | Controls what gets published to npm |
37| Prepublish check | `"prepublishOnly": "npm run build"` | Ensure build runs before publish |
38| Dry run | `npm pack --dry-run` | Preview package contents before publishing |
39| Provenance | `--provenance` flag or trusted publishers | Cryptographic build attestation |
40| Scoped publish | `--access public` | Required for first publish of scoped packages |
41
42## Common Mistakes
43
44| Mistake | Correct Pattern |
45| -------------------------------------------------------- | ---------------------------------------------------------------------- |
46| Putting `types` after `default` in exports | `types` must be the first condition in every export block |
47| Missing `"./package.json"` in exports | Include `"./package.json": "./package.json"` for tooling compatibility |
48| Different APIs for `import` vs `require` | Same API surface; write ESM source, transpile to CJS |
49| Using `main` without `exports` for new packages | Use `exports` as the primary entry point definition |
50| Forgetting `"type": "module"` with `.js` ESM output | Set `"type": "module"` or use `.mjs` extension explicitly |
51| Publishing `src/` or `node_modules/` | Use `"files"` allowlist to include only `dist/` |
52| No `prepublishOnly` script | Add build step to prevent publishing stale artifacts |
53| Using `default` export for libraries | Prefer named exports for consistent cross-tooling behavior |
54| Not testing with `npm pack` before publish | Always dry-run to verify package contents and size |
55| Omitting `peerDependencies` for framework plugins | Declare shared runtime dependencies as peers |
56| Publishing without provenance | Enable provenance for supply-chain transparency |
57| Using `.d.ts` for CJS when package is `"type": "module"` | Use `.d.cts` for CJS type declarations, `.d.ts` or `.d.mts` for ESM |
58
59## Delegation
60
61- **Build tooling setup**: Use `Explore` agent to examine tsup/unbuild/rollup configs
62- **Type resolution debugging**: Use `Task` agent with "Are the Types Wrong?" (`attw`)
63- **Publish pipeline review**: Delegate to `code-reviewer` agent
64
65## References
66
67- [Package.json configuration: exports, main, types, files, engines, peerDependencies](references/package-json-config.md)
68- [Build scripts, prepublishOnly, npm pack, provenance, scoped packages](references/build-and-publish.md)
69- [Dual ESM/CJS builds, conditional exports, type declarations](references/dual-format.md)
oakoss