Plik package.json jest to plik JSON, który znajduje się w głównym folderze projektu Javascript / Node. Zawiera między innymi podstawowe informacje (takie jak: nazwa i opis projektu), a także wersję, czy listę zależności wymaganych przez aplikację.
Do czego służy plik package.json?
Plik package.json jest głównym miejscem konfiguracji projektu, w którym opisujemy sposób interakcji z aplikacją oraz sposób jej uruchamiania.
To właśnie plik package.json umożliwia npm uruchamianie projektu, skryptów oraz instalowanie zależności.
Przykładowy plik package.json znajdziesz tutaj.
Zarządzanie plikiem package.json
Do zarządzania plikiem package.json wykorzystujemy npm lub yarn.
W tym artykule będziemy używać komend npm CLI, z których sam korzystam, jednak różnica pomiędzy nimi jest niewielka.
Oczywiście plik package.json możesz zrobić samodzielnie od zera, jednak może to powodować niepotrzebne błędy.
Aby stworzyć plik package.json za pomocą npm wpisz w terminalu:
npm initNastępnie zostaniesz poproszony o podanie kluczowych informacji na temat projektu, takich jak: nazwa, opis, wersja.
Możesz je pominąć kilkukrotnie klikając enter (spokojnie, będziesz mógł je podać później).
W tym momencie w Twoim folderze powinien pojawić się plik pacakge.json.
Przejdźmy teraz do najważniejszej rzeczy, czyli instalacji zależności.
Wystarczy, że wpiszesz poniższą komendę wraz z nazwą paczki:
npm install <nazwa paczki>Ręczne dodanie listy zależności będzie wymagało uruchomienia npm install, zanim zależność zostanie faktycznie zainstalowana w projekcie.
Warto również wspomnieć o dwóch poniższych komendach:
npm uninstall <nazwa paczki> - usunwanie paczki
npm update <nazwa paczki> - aktualizacja paczkiPrzerywnik - chciałbym Cię serdecznie zaprosić na mojego discorda Digital Creators Community!
Właściwości pliku package.json
name
Właściwość name w pliku package.json jest jednym z podstawowych elementów struktury package.json. Jak możesz się domyślić, jest to po prostu nazwa naszego projektu.
Nazwa musi składać się wyłącznie z małych liter, nie może zawierać więcej niż 214 znaków i musi być bezpieczna dla adresów URL (nie może zawierać spacji ani innych znaków niedozwolonych w adresach URL).
"name": "myproject"version
Pole version jest istotne dla każdego projektu udostępnianego publicznie w npm. Oznacza aktualną wersję paczki, która powinna być zwiększana przy wprowadzeniu każdej zmiany.
Standardem do zapisywania wersji jest SemVer (Semantic Versioning) używany przez większość użytkowników.
W przypadku pakietów nieopublikowanych ta właściwość nie jest wymagana.
"version": "2.0.3" license
Jest to bardzo ważna, ale często pomijana właściwość. Pole license pozwala określić, jaka licencja dotyczy naszego kodu.
Jest to bardzo ważne, gdy publikujemy projekt w npm, ponieważ licencja pomaga jasno określić, na jakich zasadach użytkownicy mogą korzystać z naszego oprogramowania.
Jeśli nie chcesz podawać licencji czy nie chcesz zezwolić na używanie prywatnego lub niepublikowanego pakietu, możesz wpisać "UNLICENSED" jako licencję.
To pole również nie jest wymagane, jeśli nie publikujesz swojego projektu w npm.
Nie wiesz jaką licencję wybrać? Zajrzyj tutaj.
"license": "MIT" description
Pole description jest:
- Krótkim podsumowaniem tego, do czego służy paczka.
- Używane przez npm do opisania paczki w wynikach wyszukiwania.
- Pomaga w wyszukiwaniu paczki przez użytkowników na stronie npmjs.com.
Może to być również użyteczne jako prosta dokumentacja projektu, nawet jeśli nie publikujesz go w npm.
"description": "Lorem ipsum"keywords
Pole keywords jest tablicą słów kluczowych i służy w podobnym celu co description.
To pole jest indeksowane przez npm, aby pomóc w znalezieniu paczki przez użytkowników.
Jeśli nie publikujesz paczki w npm, to możesz je śmiało pominąć.
"keywords": [
"lorem",
"ipsum"
]main
Pole main określa punkt wejścia i zazwyczaj jest to plik używany do uruchomienia projektu.
Przeważnie jest to plik index.js znajdujący się w katalogu głównym projektu, ale tak naprawdę może to być dowolny plik, który odpowiada za uruchomienie Twojego projektu.
"main": "app.js"repository
To pole jest obiektem, który określa adres url, pod którym znajduje się kod źródłowy oraz rodzaj systemu kontroli wersji, z którego korzysta.
Jedyną rzeczą, na którą należy zwrócić uwagę, jest to, że jest to pełny adres URL, z którego można uzyskać dostęp do kontroli wersji (.git na końcu adresu URL).
"repository": {
"type": "git",
"url": "https://github.com/Woskus/gatsby-graphcms-blog-starter.git"
}scripts
Właściwość scripts przyjmuje obiekt, którego kluczem są skrypty, które możemy uruchomić za pomocą:
npm run scriptNameWartością jest faktyczne polecenie, które jest uruchamiane.
Skrypty są potężnymi narzędziami, które npm może wykorzystać do uruchamiania zadań w projekcie.
Skrypty są często używane do testowania, budowania i startu serwera developerskiego.
"scripts": {
"build": "gatsby build",
"dev": "gatsby develop"
}W tym wypadku, aby uruchomić serwer deweloperki Gatsby.js, wystarczy, że w terminalu wpiszę:
npm start devA w rzeczywistości zostanie wywołana wartość klucza "dev", czyli "gatsby develop".
dependencies
Jedno z najważniejszych pól w pliku package.json i prawdopodobnie jedyny powód, dla którego go potrzebujesz.
Są tu wymienione wszystkie zależności, z których korzysta Twoja aplikacja.
Kiedy pakiet jest instalowany za pomocą npm, jest pobierany do folderu node_modules, a do właściwości dependencies dodawany jest wpis z nazwą pakietu i zainstalowaną wersją.
Pole dependencies jest obiektem z nazwami pakietów jako kluczami i wersją lub zakresem wersji jako wartością.
Z tej listy npm wie, jakie pakiety pobrać i zainstalować (i w jakich wersjach), gdy uruchamiamy npm install.
"dependencies": {
"gatsby": "^4.1.4",
"mysql": "^2.18.1",
"react": "^17.0.2",
"react-dom": "^17.0.2",
}devDependencies
Pole devDependencies w pliku package.json jest niemal takie jak pole dependencies pod względem struktury.
Główna różnica polega na tym, że podczas gdy właściwość dependencies jest używana do definiowania zależności, których moduł potrzebuje, aby działać na produkcji, właściwość devDependencies jest powszechnie używana do definiowania zależności, których aplikacja potrzebuje, aby działać podczas developmentu.
Przykładem może być używanie narzędzia do przeładowywania projektu podczas jego tworzenia, takiego jak nodemon, którego nie będziemy używać, gdy aplikacja zostanie wdrożona na produkcji.
Aby dodać paczkę jako devDependency, wystarczy, że podczas jego instalacji dodamy flagę --save-dev, czyli:
npm install <nazwa paczki> --save-devW package.json wygląda to w ten sposób:
"devDependencies": {
"eslint": "^7.32.0"
}Pozostałe
- bugs - służy do wskazywania repozytorium aplikacji, w którym można zgłaszać problemy w projekcie
"bugs": {
"url": "https://github.com/Woskus/gatsby-graphcms-blog-starter/issues"
}- homepage - służy do określania strony głównej dla aplikacji/paczki
"homepage": "https://mwebs.pl/",- private - domyślnie właściwość private ma wartość false, ale można ją ustawić na true, aby uniemożliwić publikację aplikacji
"private": true- engines - właściwość engines jest obiektem JSON zawierającym pary klucz-wartość, które są używane do określania wersji bibliotek, na których ma działać aplikacja.
"engines": {
"npm": "6.10.0",
"node": "10.14.1"
}- browserslist - służy do określania, które przeglądarki (i ich wersje) mają być obsługiwane
"browserslist": ["> 1%", "last 2 versions", "not ie <= 8"]- author & contributors - służy do określenia autora, oraz współpracowników projektu. Oba pola mogą mieć występować w formacie "<name> <email> <url>" lub obiektu z polami name, email, url.
"author": "Mateusz Woskowicz mateusz@mwebs.pl https://mwebs.pl/o-mnie",
"contributors": [{
"name": "Mateusz Woskowicz",
"email": "mateusz@mwebs.pl",
"url": "https://mwebs.pl/o-mnie"
}]Czym jest package.lock.json?
Package.lock.json jest to również plik JSON, który pojawia się przy instalacji zależności do naszego projektu.
Celem pliku package-lock.json jest śledzenie dokładnej wersji każdej zależności, która jest zainstalowana, tak aby projekt był w 100% odtwarzany w ten sam sposób.
Rozwiązuje to specyficzny problem, który powstaje w pliku package.json.
W polu "dependencies" package.json oprócz wersji zależności możemy określić, czy akceptujemy jej aktualizacje, np.:
Jeśli napiszesz ~0.13.0, chcesz aktualizować tylko wersje z poprawkami, czyli 0.13.1, 0.13.2, ..., ale 0.14.0 już nie.
Jeśli napiszesz ^1.13.0, otrzymasz poprawki i pomniejsze wersje: 1.13.1, 1.14.0 i tak dalej, ale nie 2.0.0.
Jeśli napiszesz 0.13.0, to jest to dokładna wersja, która będzie używana zawsze.
Problem pojawia się, gdy Twórca projektu użyje na przykład ~0.13.0 przy jednej z paczek. Gdy pojawi się wersja z poprawkami, czyli na przykład 0.13.1 jeśli nasz współpracownik wpisze npm install pobierze właśnie tę wersję.
W skrócie: istnieje możliwość, że różni kontrybutorzy projektu będą mieli różne wersje poszczególnych paczek.
Package-lock.json ustawia na stałe aktualnie zainstalowaną wersję każdego pakietu, a npm użyje dokładnie tych wersji.
Plik package-lock.json musi zostać przesłany do Twojego repozytorium Git, aby mógł być pobrany przez innych współpracowników.
Podsumowanie
Package.json jest kluczowym plikiem każdego projektu Javascript / Node.
Zapisuje ważne metadane o projekcie, a także pozwala npm na instalowanie zależności, uruchamianie skryptów oraz start naszej aplikacji.
Jeśli chcesz być na bieżąco z aktualizacjami najpopularniejszych paczek, zapisz się do mojego newslettera i zacznij otrzymywać je regularnie wprost na swoją skrzynkę 🚀