Sve što trebate znati o npm paketima i nodebbs-u

Početna » piton » Sve što trebate znati o npm paketima i nodebbs-u

Ako pokušavate shvatiti kako npm paket kao što je „nodebbs“ uklapa se u Node.js ekosistem, prvo vam je potrebno dobro razumijevanje Šta je npm, kako su paketi strukturirani i kako Node rješava i izlaže module. Moderni Node.js projekti uveliko zavise od npm-a, ne samo za instaliranje koda već i za upravljanje skriptama, sigurnošću, verzijama i načinom na koji drugi koriste vaš paket.

Ovaj vodič vas vodi kroz npm od temelja — šta je to, kako funkcionišu lokalni i globalni paketi, kako ih instalirati, ažurirati i ukloniti, kako package.json je strukturiran i kako napredne funkcije poput exports i imports Polja kontrolišu šta vaš paket (na primjer, forumski mehanizam kao što je nodebbs) stavlja na raspolaganje korisnicima. Sve je objašnjeno jednostavnim jezikom s mnoštvom primjera tako da možete s pouzdanjem objavljivati ​​i koristiti npm pakete.

Šta je npm i zašto je važan za pakete poput nodebbs-a

npm (Node Package Manager) je i alat komandne linije i ogroman online registar Node.js paketa otvorenog koda. Kada instalirate Node.js na svoj sistem, npm se instalira automatski, dajući vam trenutni pristup milionima modula za višekratnu upotrebu koje je objavila zajednica na npmjs.com.

The npm registar je efektivno najveći repozitorij jednomezičnog koda na planeti, sa preko milion objavljenih paketa koji pokrivaju gotovo svaki zamislivi zadatak. Ovi paketi se kreću od malih uslužnih programa (jedna funkcija) do kompletnih okvira, CLI-jeva i aplikacijskih kostura koji svakodnevno pokreću produkcijske aplikacije.

izvorno, npm je dizajniran isključivo za upravljanje zavisnostima za backend Node.js projekte, ali danas je i osnovni alat za frontend tokove rada. Možete instalirati React, alate poput Webpacka ili Vitea, CSS frameworkove, programe za testiranje i još mnogo toga - sve distribuirano kao npm paketi.

Prilikom rada sa određenim paketom kao što je nodebbs, npm je odgovoran za preuzimanje svog koda., rješavanje njegovih zavisnosti, održavanje konzistentnosti verzija u vašem timu i povezivanje svih skripti ili CLI-jeva koje izlaže. Zato je razumijevanje npm-a ključno ako želite sami procijeniti, prilagoditi ili čak objaviti paket - pogledajte široko rasprostranjeni napad na lanac snabdijevanja NPM-a.

Node.js, npm i kako ih instalirati

Da biste koristili bilo koji npm paket — uključujući nodebbs — potrebno vam je Node.js i npm instalirani na vašem računaru. npm dolazi u paketu s Nodeom, tako da samo instalirate Node sa službene stranice i spremni ste za korištenje.

Preporučeni pristup je instaliranje Node.js-a putem upravitelja verzija kao što je nvm, što vam omogućava prebacivanje između više Node i npm verzija. Ovo olakšava testiranje vašeg projekta s različitim Node verzijama i izbjegava probleme s dozvolama koji se mogu pojaviti kod instalacijskih programa na nivou sistema.

Možete brzo provjeriti da li Čvor i npm su već prisutni otvaranjem terminala i pokretanjem: node -v da provjerite verziju Node-a i npm -v da potvrdi npm verziju.

Ako nedostaje Node.js ili je vaša verzija prestara, preuzmite Izdanje za dugoročnu podršku (LTS) od nodejs.org za vaš operativni sistem. Na Windowsu i macOS-u, instalacijski program sve postavlja; na Linuxu možete koristiti NodeSource ili preferiranu metodu vaše distribucije, ili opet upravitelj verzija poput nvm.

Osnovni npm koncepti: paketi, moduli i registar

U Node.js svijetu, a "paket" je dio koda u paketu koji uključuje sve što je potrebno za modul ili aplikaciju: JavaScript datoteke, metapodatke, dokumentaciju, a ponekad i artefakte izgradnje. Paketi se obično nalaze u direktoriju sa package.json datoteka koja opisuje šta sadrže.

A "modul" je jedinica koda koju možete uvesti u Node.js koristeći require() or import, a npm paket obično izlaže jedan ili više modula za korištenje od strane korisnika. Na primjer, uslužna biblioteka može izvesti jedan glavni modul, dok složeni paket kao što je nodebbs može izložiti više ulaznih tačaka za svoje serverske i klijentske dijelove.

Paketi su javno objavljeni npm registar (ili u privatne registre) kako bi ih drugi programeri mogli instalirati jednostavnom naredbom. Unutar haube, npm preuzima datoteke, provjerava stablo zavisnosti i sve pohranjuje u node_modules mapu kako bi je vaša aplikacija mogla uvesti.

Popularni primjeri npm paketa uključuju okvire poput Express, React i Vue, uslužni programi poput Lodash i Chalk, backend pomoćnici poput Mongoose i Socket.io, te alati poput Jest, Webpack, Babel, Nodemon i Axios. Paket poput nodebbs bi se nalazio uz ove kao još jedna instalirajuća zavisnost koju uključujete u svoj aplikacijski stek.

Rad sa npm-om u komandnoj liniji

The npm interfejs komandne linije (CLI) je način na koji instalirate, uklanjate, ažurirate i pregledavate pakete, kao i kako pokrećete skripte projekta. Na Windowsu ćete obično otvoriti komandni redak ili PowerShell; na macOS-u i Linuxu ćete koristiti terminal.

Neke od najčešće korištenih npm naredbi su npm install, npm uninstall, npm update, npm init, npm start, npm test, I npm publishZajedno, ove naredbe pokrivaju gotovo sve što vam je potrebno za upravljanje zavisnostima Node.js projekta i zadacima životnog ciklusa.

Da biste instalirali novi paket lokalno u vašem projektu, obično pokrećete npm install <package-name> iz korijena projekta. Ovo preuzima paket u node_modules i, uz moderni npm, automatski dodaje unos pod dependencies in package.json.

Globalne instalacije, korištenjem npm install -g <package-name>, su rezervisani za alate koje želite da budu dostupni svugdje na vašem sistemu - stvari poput nodemon, typescript, ili druge CLI-je. Vaše biblioteke na nivou aplikacije (uključujući nodebb-ove) gotovo uvijek pripadaju lokalnom dependencies Umjesto toga.

Inicijalizacija Node projekta i uloga package.json datoteke

Svaki ozbiljan Node.js projekat počinje sa package.json datoteka, koja služi kao manifest za vašu aplikaciju ili biblioteku. Ona pohranjuje metapodatke (naziv, verziju, opis), skripte, zavisnosti i informacije o tome kako paket treba biti učitan.

Ovu datoteku kreirate pokretanjem npm init u praznoj mapi, a zatim odgovorite na nekoliko pitanja o projektu. Ako želite preskočiti pitanja, npm init -y generira minimalno package.json sa razumnim zadanim postavkama koje kasnije možete urediti.

jednom package.json postoji, svaki paket koji instalirate se zapisuje pod bilo kojim od dependencies, devDependencies, ili druge namjenske dijelove. Ovo omogućava drugom programeru da klonira vaš repozitorij i jednostavno ga pokrene npm install da se obnovi cijelo stablo zavisnosti.

Za paket poput nodebbs koji biste možda željeli objaviti, package.json također deklarira naziv paketa, ulazne tačke i sva polja poput main, exports, ili type koji kontrolišu kako Node rješava svoje module. To čini package.json centralno i za korištenje i za proizvodnju npm paketa.

Lokalna vs globalna instalacija npm paketa

Lokalni paketi se instaliraju u trenutni projekat node_modules direktorij i dostupni su samo unutar tog projekta. Kada pokrenete npm install express or npm install nodebbs U mapi vašeg projekta, paket postaje dio grafa zavisnosti te aplikacije.

Ova strategija lokalne instalacije sprečava konflikti verzija između projekata jer svaki projekat održava vlastite kopije zavisnosti. Jedna aplikacija može koristiti Express 4, dok druga koristi Express 5, i neće se međusobno miješati.

Globalni paketi, instalirani sa npm install -g, se smještaju na lokaciju na nivou sistema i obično izlažu alate komandne linije. Ovo možete koristiti za nodemon, typescript, ili za generatore globalnih projekata, ali rijetko želite da kod aplikacije poput nodebbs-a bude globalan.

npm vam također omogućava promjenu globalnog prefiksa instalacije pomoću npm config set prefix <path>, što je praktično ako nemate administratorska prava ili želite izbjeći greške u dozvolama prilikom instaliranja globalnih CLI-jeva. Na taj način, vaši globalni alati se nalaze u direktoriju u koji korisnik može pisati.

Upravljanje zavisnostima: instaliranje, ažuriranje i uklanjanje

U svakodnevnom radu, provodit ćete mnogo vremena dodavanje, ažuriranje i povremeno uklanjanje npm zavisnosti.npm pruža jednostavne naredbe za svaku od ovih operacija, i lokalno i globalno.

Instaliranje svih zavisnosti u postojećem projektu je jednostavno kao pokretanje npm install u direktoriju gdje package.json života. npm čita listu zavisnosti i devDependencies i ponovo kreira node_modules fasciklu u skladu s tim.

Da biste dodali jednu zavisnost, pokrenete npm install <package-name> (ili npm i <package-name> skraćeno), opcionalno sa zastavicama poput --save-dev, --save-optional, ili --no-saveOve zastavice kontrolišu da li se paket zapisuje kao regularna zavisnost, zavisnost samo za razvoj ili se uopšte ne zapisuje.

Ažuriranje zavisnosti može se izvršiti na nivou cijelog projekta pomoću npm update, koji nadograđuje pakete na novije verzije koje i dalje zadovoljavaju raspone verzija u package.jsonTakođer možete ciljati jedan paket sa npm update <package-name>, ili dodati -g ako ažurirate globalni alat.

Deinstalacija paketa je simetrična: npm uninstall <package-name> uklanja ga iz node_modules i čisti package.json unos. Korištenje npm uninstall -g radi isto za globalno instalirane pakete.

Razumijevanje zavisnosti, razvojnih zavisnosti i opcionalnih zavisnosti

In package.json, npm razlikuje različite tipove zavisnosti u zavisnosti od toga kada i kako su potrebne. Pravilno razdvajanje održava vaš proizvodni paket vitkim, a vaše alate fleksibilnim.

dependencies navodi pakete potrebne za pokretanje vaše aplikacije u produkciji. Za web aplikaciju, to može uključivati ​​Express, Mongoose ili čak sam nodebbs ako ga ugrađujete kao dio vašeg serverskog paketa.

devDependencies sadrži pakete koji su potrebni samo tokom razvoja ili izgradnje, kao što su Jest, ESLint, Webpack, Babel ili Nodemon. Oni se ne instaliraju kada pokrenete npm install --production, što vaše proizvodno okruženje održava lakšim.

optionalDependencies sadrži pakete koji poboljšavaju vašu aplikaciju, ali nisu strogo obavezni. Ako se opcionalna zavisnost ne instalira, npm je neće tretirati kao fatalnu grešku; očekuje se da će vaš kod elegantno obraditi njeno odsustvo.

Zastave kao što su --save-prod (podrazumevano), --save-dev (ili -D), I --save-optional kontrola gdje se novoinstalirani paket zapisuje. Historijski gledano, postojala je eksplicitna --save zastava, ali moderni npm tretira npm install <name> kao operacija spremanja u zavisnosti prema zadanim postavkama.

Semver i instaliranje specifičnih verzija paketa

npm koristi semantičko verzioniranje (semver) za upravljanje verzijama paketa, što je ključno kada se oslanjate na složene biblioteke ili na paket poput nodebbs-a koji se može razvijati tokom vremena. Semver koristi obrazac MAJOR.MINOR.PATCH (na primjer, 1.4.3).

U semestru, GLAVNI broj prirasti kada dođe do kritičnih promjena, MALO za dodavanje funkcija kompatibilnih s prethodnim verzijama i PATCH za ispravke grešaka koje ne bi trebale narušavati postojeći kod. Ovaj model omogućava paketima da se razvijaju bez stalnog narušavanja aplikacija koje se koriste u budućnosti.

Možete instalirati tačnu verziju paketa pomoću npm install package@version, na primjer npm install express@4.17.1Ovo je korisno ako želite zaključati svoj projekat na poznatu ispravnu verziju dok zasebno testirate nova izdanja.

u package.json, možete odrediti fleksibilne raspone koristeći znakove poput ^ i ~ ili koristiti "latest" or * da uvijek preuzmete najnovije kompatibilno izdanje. Na primjer, "express": "^4.1.1" govori npm-u da koristi bilo koju kompatibilnu 4.x verziju iznad 4.1.1, ali ne 5.x.

Globalni paketi i CLI alati

Globalni npm paketi se prvenstveno koriste za instalaciju alati komandne linije koje želite da budu dostupne bez obzira na koji projekat radite. Ovi alati registruju izvršne datoteke na vašem PATH-u tako da ih možete pozvati direktno iz terminala.

Primjeri korisnih globalnih paketa uključuju nodemon za automatsko ponovno pokretanje Node servera tokom razvoja i typescript za kompajliranje TypeScript-a sa bilo kojeg mjesta na vašem računaru. Instalacija se vrši sa npm install -g <package-name>.

Možete provjeriti koji su globalni paketi instalirani pokretanjem npm list -g --depth=0, koji ispisuje ravnu listu globalno dostupnih modula i njihovih verzija. Ovo je korisno za reviziju vaših postavki ili otklanjanje grešaka u CLI problemima.

Ažuriranje ili uklanjanje globalnih alata funkcioniše na isti način kao i lokalnih: koristite npm update -g <package-name> ažurirati i npm uninstall -g <package-name> da ih uklonite. Ažuriranjem globalnih alata osiguravate da dobijete najnovije ispravke i sigurnosne zakrpe.

Listanje, inspekcija i revizija instaliranih paketa

Kako vaš projekat raste, praćenje instaliranih paketa i verzija koje koriste postaje sve važnije. npm pruža komande za popis i pregled vaše stablo zavisnosti.

npm list prikazuje hijerarhiju lokalno instaliranih paketa u trenutnom projektu, uključujući ugniježđene zavisnosti na koje se vaše direktne zavisnosti oslanjaju. Možete vidjeti koje su verzije na kraju instalirane i kako su povezane.

npm list -g Radi slično, ali za globalno instalirane pakete i dodavanjem --depth=0 ograničava izlaz samo na unose najvišeg nivoa. Ovo održava izlaz čitljivim, posebno kada je prisutno mnogo ugniježđenih zavisnosti.

Radi sigurnosti, npm uključuje funkcija revizijetrčanje npm audit skenira vaše stablo zavisnosti u odnosu na bazu podataka ranjivosti i ispisuje izvještaj o poznatim problemima - pogledajte Incident sa crvom Shai HuludČesto ih možete automatski popraviti pomoću npm audit fix, koji prebacuje verzije zavisnosti na sigurna izdanja gdje je to moguće.

Redovne revizije i ažuriranja drastično smanjuju rizik od izlaganja vaše aplikacije poznatim ranjivostima skrivenim u modulima trećih strana - na primjer, pogledajte Zlonamjerno predstavljanje NPM paketaOvo je posebno važno kada se oslanjate na velike pakete poput nodebbs što može dovesti do dubokog lanca zavisnosti.

Korištenje instaliranih paketa u vašem Node.js kodu

Nakon što ste lokalno instalirali paket, on je spreman za uvoz u vašu Node.js aplikaciju i korištenje baš kao i bilo koji drugi modul. Node je historijski koristio CommonJS moduli preko require(), ali moderni projekti se često oslanjaju i na ECMAScript module sa import.

Za CommonJS, možete napisati const express = require('express') or const nodebbs = require('nodebbs') na vrhu vaše datoteke da biste unijeli glavni izvoz paketa. Odatle koristite njegov dokumentirani API za konfiguriranje ruta, middlewarea ili u Nodebbsov slučaj, forumske teme.

Za ECMAScript module (kada vaš package.json ima "type": "module" ili koristite .mjs datoteke), umjesto toga radite import express from 'express'Mnogi moderni paketi sada objavljuju ESM verzije, a Node podržava oba formata.

Imajte na umu da veliki paketi često otkrivaju više ulaznih tačaka, tako da biste mogli uvesti podmodule poput import { Router } from 'express' or import feature from 'nodebbs/feature.js', ovisno o tome kako je autor paketa strukturirao svoje izvoze. Ovdje se exports polje u paketu package.json postaje važno.

npm skripte: automatizacija zadataka pomoću package.json datoteke

Pored upravljanja zavisnostima, npm služi i kao jednostavan izvršavač zadataka putem... scripts odeljak package.jsonSkripte vam omogućavaju da definišete kratke aliase za uobičajene komande koje želite da se izvršavaju tokom razvoja ili implementacije.

Osnovni primjer je definiranje "start": "node app.js" pod scripts, koji zatim pokrećete koristeći npm startOvo je mnogo lakše zapamtiti i dijeliti nego dugu komandnu liniju, a radi konzistentno u svim okruženjima.

Možete postaviti skripte za pokretanje testova, izgradnju frontend resursa, povezivanje, pokretanje razvojnih servera, postavljanje baza podataka ili čak orkestriranje zadataka povezanih s paketom kao što je nodebbsNa primjer, možda imate skriptu za pokretanje migracija baze podataka prije pokretanja forum servera.

npm rezerviše prečice za start, test, restart, I stop, ali se bilo koja druga prilagođena skripta pokreće sa npm run <script-name>Ispod haube, npm postavlja okruženje tako da se lokalno instalirani CLI-ji nalaze na PATH-u, zbog čega su komande poput webpack or jest često rade bez pune putanje.

Napredne ulazne tačke paketa: glavni, izvoz i uvoz

Za pakete koje objavljujete — kao hipotetički nodebbs modul — kontrola datoteka koje su vidljive korisnicima ključna je za stabilnost i sigurnost API-ja — incidenti poput npm tiposquatting ilustruju rizik.

Stariji main polje jednostavno ukazuje na primarnu ulaznu datoteku, kao što je "main": "./index.js"i podržan je u svim Node verzijama. Potrošači koji to rade require('your-package') će dobiti tu datoteku po defaultu.

Novije exports Polje je daleko moćnije: može definirati više ulaznih tačaka, podržavati uslovni izvoz na osnovu okruženja ili sistema modula i blokirati pristup internim putanjama na koje ne želite da se korisnici oslanjaju. Kada exports prisutan, samo su eksplicitno navedene putanje dostupne putem golog uvoza kao što je require('pkg/subpath').

An exports mapa može specificirati korijenski unos na ".", dodatne podpute kao što su "./feature", pa čak i eksplicitno izlaganje ./package.json ako je potrebno. Ovo vam omogućava da pažljivo oblikujete svoju javnu API površinu, a da pritom detalji implementacije ostanu privatni.

Izvoz obrazaca sa * omogućavaju vam da otkrijete cijele mape bez navođenja svake datoteke; na primjer, "./lib/*": "./lib/*.js" će mapirati sve odgovarajuće podputanje. Također možete eksplicitno blokirati određene podmape mapiranjem na null, što sprečava potrošače da uvoze te putanje.

Uslovni izvoz i ekološki osviještene izgradnje

Uslovni izvoz omogućavaju vam da obezbijedite različite datoteke u zavisnosti od toga kako ili gdje se vaš paket koristi. Možete isporučiti jednu verziju optimizovanu za import (ESM) i još jedan za require() (CommonJS), ili čak odvojene verzije za Node i preglednike.

Uslovi kao što su "import", "require", "node", "node-addons", "module-sync", I "default" može se pojaviti u exports objekt za odabir ispravne mete. Na primjer, "import": "./index-module.js" i "require": "./index-require.cjs" pružaju dvostruku podršku za ESM/CommonJS.

Ovi uslovi se procenjuju redom, tako da ih treba navesti od od najspecifičnijeg do najmanje specifičnog, završavajući sa "default" rezervna opcija za nepoznata okruženja. Ovo osigurava da druga okruženja (na primjer, učitavači preglednika koji koriste mape uvoza) i dalje mogu koristiti vaš paket.

Node vam također omogućava ugniježđivanje uvjeta, kao što je posjedovanje "node" grana koja sadrži oboje "import" i "require", plus zaseban "default" koji cilja univerzalnu izgradnju. Ova fleksibilnost je posebno korisna kada vaš paket zavisi od izvornih dodataka u Node-u, ali koristi polyfill negdje drugdje — pogledajte NPM sigurnost pod pritiskom.

Pored ugrađenih uslova, Node podržava korisnički definisane uslove koji se prosleđuju putem node --conditions=<name>, a širi ekosistem se koncentrirao na ključeve poput "browser", "types", "development", I "production" za specijaliziranije scenarije. Ovo pomaže u koordinaciji ponašanja između paketa, provjerivača tipova i okruženja za izvršavanje.

Uvoz podputanja i interni aliasi modula

Dodatno exports, u imports polje u package.json Omogućava vam definiranje privatnih specifikatora uvoza koji su važeći samo unutar samog paketa. Ovi specifikatori uvijek počinju sa # kako bi se izbjegao sukob s vanjskim paketima.

Na primjer, mogli biste mapirati "#dep" na Node-native zavisnost u jednom okruženju i polyfill u drugom korištenjem uvjetnih mapiranja pod importsKod unutar vašeg paketa tada radi import '#dep' i automatski dobija ispravnu implementaciju.

Podputni obrasci se također mogu koristiti unutar imports mapirati grupe internih datoteka, kao što su "#internal/*.js": "./src/internal/*.js"Ovo stvara čiste, stabilne putanje uvoza za interne module i omogućava upravljanje refaktorisanjem bez curenja detalja implementacije vašim korisnicima.

Pravila rješavanja za imports ogledalo onih od exports, uključujući ograničenja koja drže putanje unutar korijena paketa i ne dozvoljavaju prelazak van node_modulesOvo održava enkapsulaciju i sprječava iznenađujuće ponašanje.

Samoreferenciranje je još jedna napredna funkcija koja omogućava kodu unutar paketa da se sam uvozi po imenu sve dok je exports mapa je definirana. Na primjer, ako je vaš paket nazvan "a-package" i izvoz "." i "./foo.js", interne datoteke mogu pisati import { something } from 'a-package' i koriste istu ulaznu tačku koju dobijaju potrošači.

Ova tehnika izbjegava duboke relativne putanje i osigurava da interni uvozi uvijek odražavaju granice javnog API-ja definirane od strane exportsTakođer radi sa CommonJS-om putem require('a-package/foo.js') kada se ta podputnja izvozi.

npm i Node-ove mogućnosti rezolucije modula daju vam strogu kontrolu nad načinom na koji se složeni paketi - uključujući forumske mehanizme poput nodebbs-a - strukturiraju, distribuiraju i koriste. Savladavanjem načina instalacije, upravljanja ovisnostima, semantičkog verzioniranja, sigurnosnih revizija i napredne konfiguracije ulaznih tačaka pomoću exports i imports, možete s pouzdanjem graditi, integrirati i održavati sofisticirane npm pakete koji ostaju stabilni i predvidljivi kako se vaša kodna baza i ekosistem oko nje nastavljaju razvijati.