Write package.json deliberately

package.json is both your local project config and the metadata npm shows to the world. A field you add for convenience today can confuse a consumer tomorrow.

Let’s build the manifest for @acme/slugify-title by hand instead of accepting whatever npm init generates.

{
  "name": "@acme/slugify-title",
  "version": "0.1.0",
  "description": "Turn blog post titles into URL slugs",
  "type": "module",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/acme/slugify-title.git"
  },
  "engines": {
    "node": ">=20"
  },
  "scripts": {
    "test": "node --test",
    "build": "tsup"
  }
}

Run npm pkg get name version engines from the package root. You should see the same values echoed back:

"@acme/slugify-title"
"0.1.0"
{ "node": ">=20" }

Fields that deserve a second look

name: Scoped names like @acme/slugify-title reduce registry collisions. Unscoped names are global and permanent once published.

type: "module" tells Node to treat .js files as ESM. If you also ship CommonJS, you will express that in exports, not by flipping this back and forth.

engines: This is a compatibility signal, not a hard lock. Still, I always set it to the Node version I actually test against. Lying here creates support tickets.

repository: npm links to it on the package page. GitHub’s “open issue” flow also reads this field.

scripts: These are the commands CI and future you will run. Name them after outcomes (test, build), not after tools (vitest, tsup) unless the tool name is already the convention.

Validate before you commit

npm pkg fix
npm pkg get name

npm pkg fix normalizes common mistakes. If you typo the name, npm publish fails early with a clear validation error instead of halfway through a release.

Be careful with fields you do not need yet. Skip keywords, funding, and exports until the next lessons fill them in with real values. An empty or wrong field is worse than a missing one.