package-publishing

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