Understanding package.json: A Guide for AI-Assisted Developers

Anatomy of package.json

Here is a fully annotated package.json from a typical Next.js project AI generates:

{
  "name": "my-app",          // Project name — lowercase, no spaces
  "version": "0.1.0",        // Your app's version (semver)
  "private": true,            // Prevents accidental npm publish
  "description": "My AI-built SaaS app",

  // Scripts — run with: npm run [script-name]
  "scripts": {
    "dev": "next dev",              // Start development server
    "build": "next build",          // Build for production
    "start": "next start",          // Start production server
    "lint": "eslint . --ext .ts,.tsx",
    "format": "prettier --write .",
    "type-check": "tsc --noEmit"    // TypeScript type checking
  },

  // Runtime dependencies — needed in production
  "dependencies": {
    "next": "^15.0.0",       // ^ means any compatible version (15.x.x)
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "@prisma/client": "^6.0.0",
    "zod": "^3.22.0"
  },

  // Dev dependencies — only needed during development
  "devDependencies": {
    "typescript": "^5.3.0",
    "@types/node": "^20.0.0",
    "@types/react": "^19.0.0",
    "eslint": "^9.0.0",
    "prettier": "^3.0.0",
    "prisma": "^6.0.0"      // CLI tool — dev only
  },

  // Node.js and npm version requirements
  "engines": {
    "node": ">=20.0.0",
    "npm": ">=9.0.0"
  }
}

Understanding Scripts

Scripts are shortcuts for terminal commands. npm run dev runs whatever is defined in "dev". You can chain commands:

"scripts": {
  // & runs both simultaneously (parallel)
  "dev": "next dev & prisma studio",

  // && runs second only if first succeeds (sequential)
  "build": "tsc --noEmit && next build",

  // Call other scripts using npm run
  "check": "npm run lint && npm run type-check",

  // Pass arguments with --
  // Usage: npm run lint -- --fix
  "lint": "eslint . --ext .ts,.tsx"
}

Common scripts AI generates for Next.js projects:

• dev — Start the dev server (usually next dev or vite)
• build — Production build
• start — Run the production build
• lint — Check for ESLint violations
• format — Run Prettier
• test — Run test suite
• db:push or migrate — Database migration commands

Dependencies vs. devDependencies

The Prisma CLI (prisma) is a devDependency because you run migrations during development. The Prisma client (@prisma/client) is a dependency because your app uses it at runtime. AI sometimes gets this wrong — placing the CLI in dependencies or the client in devDependencies.

Reading Version Numbers (Semver)

Version numbers follow the pattern: MAJOR.MINOR.PATCH (e.g., 15.2.4)

• MAJOR — Breaking changes. Upgrading may require code changes.
• MINOR — New features, backward compatible. Usually safe to upgrade.
• PATCH — Bug fixes. Always safe to upgrade.

Version range prefixes in package.json:

"next": "^15.0.0"   // ^ (caret) — accept 15.x.x, not 16.x.x
"react": "~19.0.0"  // ~ (tilde) — accept 19.0.x, not 19.1.x
"zod": "3.22.0"     // Exact version only
"eslint": ">=9.0.0" // Any version 9 or higher
"node": ">=20 <22"  // Range: 20 or 21, not 22+

The ^ caret is the default when you npm install. It allows automatic minor and patch updates but locks the major version. This means npm update will keep you on the same major version, avoiding breaking changes.

package-lock.json and node_modules

package.json defines the version ranges you accept. package-lock.json records the exact versions actually installed. This ensures everyone on your team (and your CI server) uses identical versions even if newer compatible releases are available.

Key rules:

• Commit package-lock.json to Git — it ensures reproducible builds
• Never commit node_modules/ — it is huge and regeneratable with npm install
• Add node_modules to .gitignore — AI sometimes forgets this

Common Issues AI Creates

Missing from .gitignore

AI generates a project without adding node_modules/ or .env to .gitignore. You accidentally commit 300MB of dependencies or your API keys to GitHub. Always check .gitignore after AI scaffolds a project.

Wrong dependency type

CLI tools in dependencies instead of devDependencies. This bloats your production deployment. Check: does this run as a command (npx prisma, eslint)? That is a devDependency. Does your app import it at runtime (import { PrismaClient })? That is a dependency.

Version conflicts

AI installs packages with incompatible peer dependency versions. Symptom: npm install prints long warnings about peer dependency conflicts. Fix: check the conflicting package's docs for compatible version ranges, or use npm install --legacy-peer-deps as a temporary workaround.

What to Learn Next

• Terminal Commands Guide — The npm commands that interact with package.json.
• What Is JavaScript? — Node.js is the runtime; understanding JS helps with npm.
• What Is Git? — Committing package.json and package-lock.json correctly.
• What Are Environment Variables? — .env files and their relationship to your project setup.

FAQ