package.json end to end

medium

Learn with your AI

Open this lesson in your favourite AI. It'll walk you through the why, explain the demo, and quiz you on the try-it list.

Open in Claude Open in ChatGPT

Why this matters

package.json is the manifest, the script runner, the dep contract, the type declaration, the entry-point declaration, and the version pin all in one file. A real project's package.json has 30+ fields and skipping any of them ('main', 'type', 'exports', 'engines', 'scripts') causes a real bug eventually. Knowing every field that matters in 2026 is the difference between 'I copy from a template' and 'I can audit any npm package in 30 seconds'.

Demo

A well-structured package.json for a TypeScript service in 2026 carries more information than just dependencies: it specifies the module type ("type": "module" for native ESM), exports maps for proper resolution, and engine constraints to prevent accidental deployment on the wrong Node version. The scripts section is the team's build contract — how you run tests, how you start in development versus production, and how CI invokes the linter. Reading an unfamiliar package.json cold should tell you the entire operational story of how a service is built and run.

Try it yourself

Create a fresh package with pnpm init. Add "type": "module" and "engines": {"node": ">=22"} immediately.

Add a scripts.dev using node --watch --env-file=.env. Now pnpm dev is your hot-reload story (no nodemon needed in modern Node).

Add packageManager to pin pnpm/yarn version. Corepack will refuse mismatches.

Look at three real packages on npm (e.g. fastify, zod, drizzle). Compare their package.json — note the field overlap.

Prompt your AI

Use these three in order. Each builds on the one before.

1. Basics & terminology

In one paragraph, explain what the 'type' field in package.json controls and why setting it to 'module' is the 2026 default.

2. Why it works (the mechanism)

Walk me through `exports` field resolution. What's the difference between `main`, `module`, and `exports`? Why is `exports` the only one that should matter today?

3. Advanced — application & what's next

I'm shipping a library that should work in Node, browsers, and Bun. What does my `exports` field look like? Cover dual-package hazard, conditional exports, and types-first.