Packages, dependencies, and package.json

This page explains how JavaScript/TypeScript projects pull in libraries (like Tailwind, tRPC, Zod).

What package.json is

package.json describes:

• project metadata (name, version)
• scripts (dev, build, test, etc.)
• dependencies:
  • dependencies: runtime dependencies needed in production
  • devDependencies: tooling used during development (linting, testing, build tools)
  • peerDependencies: “host must provide this” (common for plugins/libraries)

Official reference:

• https://docs.npmjs.com/cli/v10/configuring-npm/package-json 

Where packages come from (npm registry)

Packages are published to registries (by default, npm).

• npm registry: https://www.npmjs.com/ 
• how installs work (high-level): https://docs.npmjs.com/about-npm 

pnpm (what we use)

We use pnpm as the package manager.

Why people use it:

• fast installs
• disk-efficient store (packages are content-addressed and shared)
• strict dependency resolution helps avoid “it works on my machine”

Docs:

• pnpm: https://pnpm.io/ 

Lockfiles (why they matter)

Lockfiles pin exact dependency versions to make installs reproducible.

• pnpm-lock.yaml is part of the “source of truth” for dependency resolution.

Concept:

• https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json 

Semantic versioning (what ^ and ~ mean)

Most packages follow SemVer: MAJOR.MINOR.PATCH.

• ^1.2.3 usually allows updates that don’t change the major version
• ~1.2.3 usually allows patch updates

Reference:

• https://docs.npmjs.com/about-semantic-versioning 

Cheatsheet (commands)

• install deps: pnpm install
• add dep: pnpm add <pkg>
• add dev dep: pnpm add -D <pkg>
• run script: pnpm <script> (e.g. pnpm dev, pnpm test)