Understanding package.json in a JavaScript or TypeScript App

Every JavaScript or TypeScript project has a file called package.json at its root.
It’s the heart of your project configuration — describing everything from your app’s name and version to its dependencies, scripts, and build settings.

In this post, we’ll break down package.json line by line — what it is, why it matters, and how you can use it effectively across Node.js, Bun, and TypeScript projects.

1) What is package.json?

It’s a simple JSON file that defines your project’s metadata, scripts, and dependencies.

{
  "name": "my-awesome-app",
  "version": "1.0.0",
  "description": "A cool project using JavaScript and TypeScript",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "start": "node src/index.js",
    "dev": "bun run dev",
    "build": "tsc"
  },
  "dependencies": {
    "express": "^4.18.2"
  },
  "devDependencies": {
    "typescript": "^5.3.0"
  }
}

It tells Node or Bun how to run, build, and understand your app.

2) Key Sections Explained

🏷️ name and version

Every package needs a name and version (especially if published to npm).

"name": "my-awesome-app",
"version": "1.0.0"

Use lowercase and hyphens for the name.
Versions follow Semantic Versioning (SemVer) — MAJOR.MINOR.PATCH.

📦 dependencies and devDependencies

These define external libraries your app uses.

"dependencies": {
  "express": "^4.18.2",
  "axios": "^1.6.0"
},
"devDependencies": {
  "typescript": "^5.3.0",
  "@types/node": "^20.0.0"
}

• dependencies → needed in production.
• devDependencies → used only during development (e.g. TypeScript, linters, test libs).

💡 In Bun or npm, install with --save-dev for dev dependencies:
npm install typescript --save-dev or bun add -d typescript

⚙️ scripts — Your Project Commands

Define short aliases for CLI commands.

"scripts": {
  "start": "node src/server.js",
  "dev": "nodemon src/server.js",
  "build": "tsc",
  "test": "vitest"
}

Run with:

npm run dev
# or
bun run dev

Special case: "start" can be run directly with npm start or bun start.

🔄 type — Module System (CommonJS vs ESM)

Determines how Node interprets files (require vs import).

"type": "module"

Options:

If not set, Node assumes "commonjs".
This setting affects .js files, not .ts (TS compiles based on tsconfig.json).

🚀 main, module, and types

These tell consumers which file to load.

Example for a TypeScript library:

"main": "dist/index.js",
"module": "dist/index.mjs",
"types": "dist/index.d.ts"

🧩 engines

Specifies the runtime versions supported by your app.

"engines": {
  "node": ">=18",
  "bun": ">=1.0.0"
}

🧰 scripts + Tool Integration

Many tools (like TypeScript, ESLint, Vite, Next.js) read configuration from package.json.

Example — Vite project:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "vite": {
    "port": 5173
  }
}

3) Using package.json in TypeScript Projects

When using TypeScript, package.json works hand-in-hand with tsconfig.json.

Example folder structure:

my-ts-app/
├── package.json
├── tsconfig.json
├── src/
│   └── index.ts
└── dist/
    └── index.js

scripts section:

"scripts": {
  "build": "tsc",
  "start": "node dist/index.js"
}

After running npm run build, TypeScript compiles .ts → .js.

4) Managing Packages (npm, pnpm, Bun)

npm

npm install express
npm run dev

pnpm (faster, space-efficient)

pnpm add express
pnpm dev

Bun (fast runtime + package manager)

bun add express
bun run dev

All of these update your package.json automatically and lock dependencies in a package-lock.json, pnpm-lock.yaml, or bun.lockb file.

5) Optional Fields Worth Knowing

6) Advanced: exports Field

Used in modern packages to control module entry points (ESM + CJS).

"exports": {
  ".": {
    "import": "./dist/index.mjs",
    "require": "./dist/index.cjs"
  }
}

This ensures compatibility across environments (Node, bundlers, Bun).

7) Validating and Formatting

To validate your file:

npm pkg check

To inspect a value:

npm pkg get name

You can also format automatically using:

npm pkg fix

8) Real Example: Next.js or Bun Project

Next.js

{
  "name": "my-next-app",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "14.0.0",
    "react": "18.3.0",
    "react-dom": "18.3.0"
  }
}

Bun

{
  "name": "bun-server",
  "type": "module",
  "scripts": {
    "dev": "bun run src/server.ts"
  },
  "dependencies": {
    "hono": "^3.7.0"
  }
}

9) Summary

10) References

• npm Docs — package.json
• MDN — Package management basics
• TypeScript Docs — Module Resolution
• Bun Docs — Package Manager

package.json is more than just a dependency list — it’s the blueprint of your project’s lifecycle.
Understanding it deeply helps you automate builds, streamline workflows, and manage your JavaScript or TypeScript apps like a pro.