El package.json

Cada proyecto JavaScript o TypeScript tiene un package.json en su raíz. Es el archivo que tu gestor de paquetes lee para saber qué instalar, qué scripts ejecutar, y cómo está versionado tu proyecto.

Generar un package.json

La forma más rápida de empezar:

$npm init -y

O con pnpm:

$pnpm init

El flag -y responde "sí" a todas las preguntas. Obtienes un archivo mínimo que puedes editar a mano.

Ejemplo completo comentado

{
  "name": "mi-proyecto",
  "version": "1.0.0",
  "description": "Descripción corta del proyecto",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "vitest"
  },
  "dependencies": {
    "react": "^18.3.0",
    "react-dom": "^18.3.0"
  },
  "devDependencies": {
    "vite": "^5.2.0",
    "vitest": "^1.6.0",
    "@types/react": "^18.3.0"
  },
  "engines": {
    "node": ">=20.0.0"
  }
}

Los campos esenciales

name: identificador único del proyecto (en minúsculas, sin espacios). Obligatorio si publicas en npm.

version: número de versión en formato semver (MAYOR.MENOR.PARCHE). Empieza en 1.0.0 para un proyecto publicado, 0.1.0 para uno en curso.

type: "module" para usar import/export (ESM), omitido o "commonjs" para require(). El valor "module" es el estándar en 2026.

scripts: los comandos que lanzas con pnpm run <nombre>. Nombres comunes: dev, build, test, start, lint.

dependencies: paquetes necesarios en producción (runtime).

devDependencies: paquetes usados solo durante el desarrollo (compiladores, linters, tests). No se incluyen en el build final.

engines: versión mínima de Node requerida. Útil para evitar sorpresas en máquinas con una versión antigua.

peerDependencies

Existe un cuarto tipo de dependencia: peerDependencies. Se usa cuando desarrollas una biblioteca que asume que la aplicación anfitriona ya tiene instalado un paquete (ej: un plugin de React que requiere React 18). Los usuarios de tu biblioteca deben instalar estos pares por su cuenta.

Editar el package.json a mano

Contrariamente a lo que se podría pensar, editar package.json a mano es completamente habitual. Añade un script "lint": "eslint .", cambia el type, ajusta una versión. Tras cada cambio, ejecuta pnpm install para resincronizar el lockfile.