package.json Schema, Modern Exports Maps & npm CLI Reference
Essential lookup for peerDependencies, subpath exports, ESM vs CJS conditional maps, sideEffects, and semver range rules.
Table of Contents
Modern Conditional Exports Map (ESM & CJS Dual Bundles)
The standard package.json exports field replacing the legacy main and module fields.
| Condition Key | Environment Match | Target Asset |
|---|---|---|
| `types` | TypeScript compiler lookup (MUST be listed first) | `./dist/index.d.ts` |
| `import` | ES Module runtime (`import ... from "pkg"`) | `./dist/index.mjs` |
| `require` | CommonJS runtime (`const pkg = require("pkg")`) | `./dist/index.cjs` |
| `default` | Fallback for all other module loaders | `./dist/index.js` |
Dependency Categories & When to Use Which
Understanding how npm and pnpm resolve packages in production and consumption.
| Category Key | Bundled in Prod? | Intended Package Type |
|---|---|---|
| `dependencies` | Yes | Core libraries required for production execution (e.g. react, next, express) |
| `devDependencies` | No | Compilers, linters, testing suites (e.g. typescript, jest, eslint, tailwindcss) |
| `peerDependencies` | Host Installed | Plugin architectures requiring consumer to supply host (e.g. react in UI component libs) |
| `optionalDependencies` | If Available | Platform-specific native binary bindings (e.g. @rollup/rollup-linux-x64-gnu) |
SemVer Version Prefix Match Rules
How package versions resolve on `npm update` or fresh `npm install`.
| Symbol Prefix | Version Range Behavior | Given "1.2.3", Allows |
|---|---|---|
| `^` (Caret) | Allows MINOR and PATCH updates (no breaking changes) | >= 1.2.3 and < 2.0.0 |
| `~` (Tilde) | Allows PATCH updates only | >= 1.2.3 and < 1.3.0 |
| Exact (No prefix) | Pins strictly to specified version | Only 1.2.3 |
| `*` (Wildcard) | Always pulls the latest published release | Any version (Dangerous in prod) |
Interactive Client-Side Tools for this Guide
Test and run these patterns directly inside your browser with zero server uploads:
JSON Formatter & Validator (Beautify & Minify)
Clean up messy API responses, fix syntax glitches, and compress JSON payloads directly in your browser.
JSON to JSON Schema Draft-07 Generator
Automatically infer and generate standard JSON Schema definitions from raw API responses and JSON documents with zero server uploads.
Frequently Asked Questions
What does "sideEffects": false do in package.json?
It informs webpack, Vite, and Rollup that no files in the package contain code that executes merely upon import (like modifying global prototypes or injecting CSS). This enables bundlers to aggressively tree-shake and discard 100% of unused exported modules.
What is the purpose of npm clean-install (npm ci)?
`npm ci` strictly installs dependencies based on `package-lock.json` without updating it, deleting existing node_modules first. It is significantly faster and deterministic, making it mandatory for CI/CD deployment pipelines.