What is package.json? (your project's ID card)

What it actually is

package.json is the ID card of a JavaScript or Node project. It sits in the root folder, and it’s a plain text file in JSON format, not code that runs, just structured information about the project: its name, its version, which outside packages it needs, and which commands you’re allowed to run on it.

A typical one looks something like this:

{
  "name": "my-app",
  "version": "0.1.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "^14.2.3",
    "react": "^18.3.1"
  },
  "devDependencies": {
    "eslint": "^8.57.0"
  }
}

name and version identify the project. scripts is a menu of named shortcuts, running npm run dev looks up the dev entry and runs next dev for you, so nobody has to memorize the real command. dependencies are packages the app needs to actually run, React, Next.js, whatever your UI is built on. devDependencies are tools needed only while you’re building or checking the code, like a linter, they’re not required for the finished app to work.

None of these fields contain the actual code of those packages. package.json is only the list. The real files live in a folder called node_modules, built by running npm install.

Why your AI just did this

Every time your agent adds a library (Tailwind, a date-picker, an animation package), it does two things: it edits package.json to add that package’s name and version under dependencies or devDependencies, and it runs npm install so the real files get downloaded into node_modules. Editing package.json without running install would leave the entry there but nothing to back it up, that’s exactly the “module not found” failure below.

It also touches the scripts block when it sets up how your project runs. A dev script for local work, a build script for producing the production version. Hosting platforms look at package.json to know what to run: Vercel checks for a build script and uses it to build your app (for a framework like Next.js there’s no separate step to start, the built output runs on demand as serverless functions), while a traditional Node host that keeps a server running, like Railway or Render, also needs a start script to know how to launch the built app afterward. If that script is missing, misnamed, or your agent renamed it without telling you, the deploy fails on the platform’s side, not on your screen.

When you’ll run into it

• npm error Missing script: "dev", the scripts field has no entry named dev, often a typo or a script your agent renamed.
• Cannot find module 'some-package', it’s referenced in code but was never added to package.json, or it’s listed there but npm install was never run.
• A teammate (or you, on a new machine) clones the repo, runs the app, and nothing works until they run npm install first, package.json travels with the repo, node_modules never does.
• git diff shows package.json and package-lock.json changed right after your agent installed something, that’s expected, both should get committed together.
• A deploy fails with a build-command error even though it runs fine on your machine, the build or start script in package.json doesn’t match what the hosting platform expects.

What to check

• package.json sits at the actual root of the project, not buried inside a subfolder
• The dev and build scripts match what you type, or what your hosting platform’s dashboard expects
• package-lock.json is committed to git alongside package.json, it locks the exact versions so everyone installs the same thing
• node_modules is listed in .gitignore, it’s rebuilt from package.json on every machine, never committed
• After pulling changes that touched package.json, run npm install again before starting the dev server

Say it like a dev

Instead of: “add that library to the project” Say: “add it as a dependency in package.json and run npm install”

Instead of: “the command that starts the project” Say: “the dev script in package.json, run with npm run dev”

Instead of: “it stopped working after I pulled the latest changes” Say: “package.json changed, did we run npm install after pulling?”