Что такое Package.json?

Package.json

package.json — это файл конфигурации проекта в экосистеме Node.js/JavaScript. Он описывает метаданные проекта, зависимости, скрипты и конфигурацию. Хотя это JavaScript инструмент, Java разработчику полезно его понимать, особенно работая в полнофункциональных командах с фронтенд и бэкэнд частями.

Структура package.json

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "My application description",
  "main": "index.js",
  "author": "John Doe",
  "license": "MIT",
  
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest",
    "build": "webpack --mode production"
  },
  
  "dependencies": {
    "express": "^4.18.0",
    "lodash": "^4.17.21"
  },
  
  "devDependencies": {
    "jest": "^27.0.0",
    "webpack": "^5.0.0"
  },
  
  "keywords": ["app", "node"],
  
  "repository": {
    "type": "git",
    "url": "https://github.com/user/repo.git"
  },
  
  "engines": {
    "node": ">=14.0.0",
    "npm": ">=6.0.0"
  }
}

Основные поля

1. Метаинформация

{
  "name": "my-app",              // Имя пакета
  "version": "1.0.0",            // Версия (semver)
  "description": "...",           // Описание
  "author": "John Doe",          // Автор
  "license": "MIT",              // Лицензия
  "repository": {                // Репозиторий
    "type": "git",
    "url": "https://github.com/..."
  }
}

2. Scripts - команды для запуска

{
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest",
    "build": "webpack",
    "lint": "eslint .",
    "deploy": "npm run build && pm2 restart app"
  }
}

Запускаются через: npm run start, npm run dev и т.д.

3. Dependencies - зависимости для продакшена

{
  "dependencies": {
    "express": "^4.18.0",        // ^4.x.x (совместимо с 4.x)
    "lodash": "~4.17.21",        // ~4.17.x (patch обновления)
    "axios": "1.4.0"             // Точная версия
  }
}

4. DevDependencies - зависимости для разработки

{
  "devDependencies": {
    "jest": "^27.0.0",          // Тестирование
    "webpack": "^5.0.0",        // Bundler
    "eslint": "^8.0.0",         // Linter
    "babel": "^7.0.0"           // Transpiler
  }
}

5. Версионирование (Semantic Versioning)

^1.2.3  = >= 1.2.3 && < 2.0.0 (совместимо с мажором)
~1.2.3  = >= 1.2.3 && < 1.3.0 (совместимо с минором)
1.2.3   = точно 1.2.3

Аналогия с Java экосистемой

Пример для Backend разработчика

Если Java разработчик работает с Node.js бэкэндом:

{
  "name": "order-service",
  "version": "2.1.0",
  "description": "Order processing microservice",
  
  "scripts": {
    "start": "node src/server.js",
    "dev": "nodemon src/server.js",
    "test": "jest --coverage",
    "lint": "eslint src",
    "build": "tsc",
    "docker:build": "docker build -t order-service:latest ."
  },
  
  "dependencies": {
    "express": "^4.18.0",
    "postgres": "^14.5.0",
    "redis": "^4.5.0",
    "kafka-node": "^5.0.0",
    "joi": "^17.0.0",
    "dotenv": "^16.0.0"
  },
  
  "devDependencies": {
    "jest": "^29.0.0",
    "typescript": "^4.9.0",
    "eslint": "^8.0.0",
    "nodemon": "^2.0.0"
  },
  
  "engines": {
    "node": ">=16.0.0",
    "npm": ">=8.0.0"
  }
}

Очень похоже на:

<!-- pom.xml в Maven -->
<project>
    <name>order-service</name>
    <version>2.1.0</version>
    
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
    </dependencies>
</project>

Управление зависимостями

Установка всех зависимостей:

npm install
# Создаст node_modules папку и package-lock.json

Добавление новой зависимости:

# Для продакшена
npm install express --save
# Эквивалент: mvn dependency:resolve

# Для разработки
npm install jest --save-dev
# Эквивалент: добавить в <scope>test</scope> в Maven

Обновление версии:

npm update express
# Обновит до последней совместимой версии

package-lock.json - Lock file

{
  "requires": true,
  "lockfileVersion": 2,
  "dependencies": {
    "express": {
      "version": "4.18.2",
      "resolved": "https://registry.npmjs.org/express/-/express-4.18.2.tgz",
      "integrity": "sha512-...",
      "dependencies": {
        "body-parser": {
          "version": "1.20.0",
          ...
        }
      }
    }
  }
}

Это аналог maven.lock файла в Java - гарантирует, что все разработчики установят точно такие же версии.

Запуск скриптов из package.json

# Стартовый скрипт
npm start

# Скрипт разработки
npm run dev

# Запуск тестов
npm test

# Custom скрипт
npm run build
npm run deploy

Аналог mvn clean package или gradle build

Пример полноценного Node.js проекта

{
  "name": "full-stack-app",
  "version": "1.0.0",
  "type": "module",
  
  "scripts": {
    "start": "node src/index.js",
    "dev": "nodemon src/index.js",
    "test": "jest --coverage --detectOpenHandles",
    "test:watch": "jest --watch",
    "lint": "eslint src",
    "lint:fix": "eslint src --fix",
    "format": "prettier --write \"src/**/*.js\"",
    "build:docker": "docker build -t app:latest .",
    "deploy": "npm run test && npm run build:docker && docker push registry/app:latest"
  },
  
  "dependencies": {
    "express": "^4.18.2",
    "cors": "^2.8.5",
    "dotenv": "^16.0.3",
    "pg": "^8.8.0",
    "redis": "^4.5.1",
    "axios": "^1.3.0",
    "joi": "^17.8.0",
    "winston": "^3.8.0",
    "socket.io": "^4.6.0"
  },
  
  "devDependencies": {
    "jest": "^29.4.0",
    "nodemon": "^2.0.20",
    "eslint": "^8.33.0",
    "prettier": "^2.8.3"
  },
  
  "engines": {
    "node": ">=18.0.0",
    "npm": ">=8.0.0"
  },
  
  "keywords": [
    "api",
    "microservice",
    "express"
  ]
}

Заключение

Hотя package.json это инструмент JavaScript экосистемы, Java разработчику полезно его понимать для:

1. Сотрудничества с фронтенд-командой - знать, как они управляют зависимостями
2. Fullstack разработки - если работаешь с Node.js бэкэндом
3. Микросервисной архитектуре - когда один микросервис на Node.js, другой на Java
4. DevOps - понимание как собираются и деплоятся JavaScript приложения

Аналогия с Maven pom.xml и Gradle build.gradle поможет быстро разобраться в структуре package.json.