Package.json – co to jest i z czego się składa?

Zrozumienie package.json jest niezbędne do pracy z Node.js. Dobrym pomysłem jest zapoznanie się z powszechnie występującymi i najważniejszymi właściwościami pliku package.json, aby móc z niego efektywnie korzystać.

Niniejszy wpis podzieliłem na kilka istotnych rozdziałów. Każdy z nich będzie zawierał opis elementów, z których składa się package.json. Ten plik to nic innego jak konfiguracja projektu w formie obiektu JSON. Na koniec wpisu pokażę jak wygląda przykładowa i kompletna zawartość naszego pliku konfiguracyjnego.

name

"name": "project"

Właściwość name zawiera nazwę naszego projektu. Nazwa tutaj zawarta musi być skonstruowana w odpowiedniej konwencji, czyli bez wielkich liter, bez podkreśleń (_), bez kropek oraz być nie dłuższa niż 214 znaków. Rzecz jasna także bez polskich znaków.

version

"version": "2.11.15"

Właściwość version to nic innego jak numer wersji naszego oprogramowania. Przyjęło się, że numer tutaj zawarty będzie w formacie „major.minor.patch”.

author

"author": "Jan Kowalski"

Właściwość author wprost mówi nam, kto jest autorem projektu. Może być to imię i nazwisko, nazwa firmy albo po prostu pseudonim autora.

license

"license": "MIT"

Pole license zawiera informację na jakiej licencji wydajemy nasze oprogramowanie. Jedną z najprostszych i chyba najczęściej spotykanych jest MIT, która daje prawo do używania, kopiowania, modyfikowania i rozpowszechniania (w tym sprzedaży) pod warunkiem zachowania warunków licencyjnych i informacje o autorze.

description

"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc auctor nisl suscipit est aliquam, a eleifend justo gravida. Ut pretium erat eu risus porta, vitae sodales ex dignissim."

Właściwość description zawiera opis projektu. Nie jest on wymagany, jednak pozwoli na zrozumienie jaką tematykę realizuje projekt. W tym miejscu można używać dowolnych znaków, oczywiście nie ma co przesadzać z długością. Forma opisu najlepiej, gdy jest zwięzła, ale treściwa.

keywords

"keywords": [
   "javascript",
   "development",
   "architecture",
   "frontend"
]

Właściwość keywords jest tablicą wartości, które zawierają słowa kluczowe. Dzięki nim, można w łatwy sposób skategoryzować projekt.

main

"main": "index.js"

Pole main zawiera ścieżkę do głównego pliku wykonywalnego. Najczęściej jest to plik index.js lub w index.ts (w zależności o technologii jaka została użyta w projekcie).

repository

"repository": {
  "type": "git",
  "url": "git@github.com:npm/npm.git"
}

Właściwość repository jest obiektem zawierającym dwie informacje. Pierwsza z nich to typ repozytorium, np. „git„, natomiast druga informacja to adres repozytorium projektu. Adres repozytorium można tutaj umieścić w formacje HTTP, ale także w formacie SSH.

scripts

"scripts": {
  "test": "echo \"Error: no test specified\" && exit 1",
  "serve": "webpack-dev-server --mode development",
  "build": "webpack -p"
},

Jednym z najważniejszych pól w package.json jest pole scripts. Jest to obiekt zawierający listę skryptów, które możemy uruchomić w projekcie. Powyższy przykład zawiera 3 takie pola, kolejno testy, uruchomienie webpack’a w trybie development oraz budowanie projektu za pomocą webpack’a. Rzecz jasna, można definiować własne. Można także do owych skryptów przekazywać parametry, które następnie webpack odbierze i odpowiednio przetworzy.

Oto jak wywołać powyższe skrypty:

$ npm run test
$ npm run serve 
$ npm run build

dependencies

Ta i następna właściwość stanowi najważniejszą część pliku package.json.

"dependencies": {
  "caniuse-lite": "^1.0.30001299",
  "jquery": "^3.5.1",
  "node-releases": "^2.0.1"
}

Obiekt dependencies zawiera zbiór pakietów użytych w projekcie potrzebnych do poprawnego działania po zbudowaniu metodą npm run build. Pakiety określamy tutaj na zasadzie klucz – wartość. Kluczem jest nazwa pakietu (taka jak w polu name), a wartością jest numer wersji (taki jak w polu version). Ważną kwestią jest, aby w miejscu wersji określić poprawny zakres lub konkretną wersję oprogramowania. Jest do tego dokładna dokumentacja.

devDependencies

"devDependencies": {
  "@babel/core": "^7.12.3",
  "@babel/plugin-transform-arrow-functions": "^7.12.1",
  "@babel/polyfill": "^7.12.1",
  "@babel/preset-env": "^7.15.8",
  "@babel/preset-react": "^7.16.0",
  "webpack": "^4.33.0",
  "webpack-cli": "^3.3.2",
  "webpack-dev-server": "^3.6.0",
  "webpack-notifier": "^1.12.0"
},

Obiekt devDependencies jest właściwie podobnym do dependencies, z tą różnicą, że zawiera pakiety potrzebne do stworzenia projektu, nie tylko do jego zbudowania. Oznacza to, że tworząc projekt wykorzystujemy różne frameworki lub preprocesory, które muszą zostać skompilowane, aby były zrozumiałe dla przeglądarek.

Pełny kod package.json

{
  "name": "webpack",
  "version": "2.11.15",
  "author": "Jan Kowalski",
  "license": "MIT",
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc auctor nisl suscipit est aliquam, a eleifend justo gravida. Ut pretium erat eu risus porta, vitae sodales ex dignissim.",
  "keywords": [
    "javascript",
    "development",
    "architecture",
    "frontend"
  ],
  "main": "index.js"
  "repository": {
    "type": "git",
    "url": "git@github.com:npm/npm.git"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "serve": "webpack-dev-server --mode development",
    "build": "webpack -p"
  },
  "dependencies": {
    "caniuse-lite": "^1.0.30001299",
    "jquery": "^3.5.1",
    "node-releases": "^2.0.1"
  },
  "devDependencies": {
    "@babel/core": "^7.12.3",
    "@babel/plugin-transform-arrow-functions": "^7.12.1",
    "@babel/polyfill": "^7.12.1",
    "@babel/preset-env": "^7.15.8",
    "@babel/preset-react": "^7.16.0",
    "webpack": "^4.33.0",
    "webpack-cli": "^3.3.2",
    "webpack-dev-server": "^3.6.0",
    "webpack-notifier": "^1.12.0"
  },
}

Jest coś jeszcze – package-lock.json

Problem z package.json polega (polegał) na tym, że menadżer pakietów npm, może znajdować różne wersje tego samego pakietu. W projekcie można nawet używać różnych wersji pomiędzy produkcją a środowiskiem deweloperskim, celem przetestowania nowego wydania pakietu. Problem ten został rozwiązany w npm od wersji 5, a rozwiązaniem było generowanie pliku package-lock.json, który zawiera konkretne numery wersji każdego z pakietów wraz z pakietami zależnymi.

Zarówno plik package.json, jak i package-lock.json należy umieszczać w repozytorium. Powodem jest spójność wersji między deweloperami, a npm wtedy będzie wiedział, jaką dokładnie wersję pakietu potrzebujemy i taką zainstaluje.