intermediate · 26 minute study

Read package.json as an executable project contract

A repository is more than source files. Its runtime, dependencies, lockfile and scripts determine whether another engineer can reproduce its behavior.

Loading progressEvidence grows with practice

Useful preparation · 1 prerequisite

Use this as a map, not a lock. If these ideas are familiar, continue.

Ask where and when this code runs — The same JavaScript syntax can run during a build, on a request server or inside a browser. Confusing those locations creates broken builds and misplaced trust.

First, build a mental model

Node runs JavaScript with process and system capabilities. npm resolves a dependency graph and executes named project scripts. The manifest expresses intent; the lockfile records concrete resolutions.

Browser and Node APIs overlap but are not identical. Node scripts can access filesystem/process capabilities; importing a Node-only module into browser code does not create those capabilities in a tab.
package.json describes scripts, dependency ranges and package metadata. dependencies and devDependencies communicate use, but a build environment often needs development tools to create the production artifact.
A normal stable caret range such as ^1.2.3 allows compatible 1.x updates below 2.0.0; a lockfile pins actual resolutions. Major-zero ranges have narrower rules, so do not generalize this example blindly.
npm ci expects the manifest and lockfile to agree and performs a clean dependency install. Package lifecycle scripts can execute code; review new dependencies, provenance and lockfile changes rather than assuming an install is passive.

Read the codejson · educational example

{
  "name": "synthetic-tools",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node --test",
    "validate-assets": "node scripts/validate-assets.mjs"
  },
  "engines": { "node": ">=22" }
}

Manifest
The example names two scripts and declares ESM interpretation. These are commands, not evidence that either command ran.
Environment
The actual installed Node version and CI configuration still need to match the project's supported tooling.
Verification
A clean lockfile-based install followed by the relevant scripts tests reproducibility; an engines field alone is not proof.

Production thinking

Take this beyond the example.

Keep scripts discoverable, environment values validated and credentials out of logs. Pin the supported CI runtime deliberately. Use automation to remove repeated mistakes, not to obscure what commands execute.

Sources and further reading

Your evidence

unseen is a local learning signal, not a credential or proof of production competence.

Explain the mental model, then explicitly acknowledge it. Opening a page is not evidence.

Supported retries can complete this lesson. Independent evidence and delayed review determine the skill stage.

Next lesson · Share a contract without making everything depend on everything →