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

Početna » Piton » Sve što trebate znati o npm paketima i nodebbs-ima

Ako pokušavate shvatiti kako npm paket poput "nodebbs" uklapa se u Node.js ekosustav, prvo vam je potrebno dobro razumijevanje što je npm, kako su paketi strukturirani i kako Node rješava i izlaže module. Moderni Node.js projekti uvelike ovise o npm-u, ne samo za instaliranje koda već i za upravljanje skriptama, sigurnošću, verzijama i načinom na koji drugi koriste vaš paket.

Ovaj vodič vodi kroz npm od temelja — što je to, kako funkcioniraju lokalni i globalni paketi, kako ih instalirati, ažurirati i ukloniti, kako package.json je strukturiran i kako napredne značajke poput exports i imports Polja kontroliraju što vaš paket (na primjer, forumski mehanizam poput nodebbsa) 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.

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

npm (Upravitelj paketa čvorova) je i alat naredbenog retka i ogroman online registar Node.js paketa otvorenog koda. Kada instalirate Node.js na svoj sustav, npm se instalira automatski, dajući vam trenutni pristup milijunima modula za višekratnu upotrebu koje je objavila zajednica na npmjs.com.

The npm registar je zapravo najveće jednomezično spremište koda na planetu, s preko milijun objavljenih paketa koji pokrivaju gotovo svaki zamislivi zadatak. Ovi paketi se kreću od malih uslužnih programa (jedna funkcija) do cjelovitih okvira, CLI-jeva i aplikacijskih kostura koji svakodnevno pokreću produkcijske aplikacije.

Izvorno, npm je dizajniran isključivo za upravljanje ovisnostima za backend Node.js projekte, ali danas je i osnovni alat za frontend tijekove 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 specifičnim paketom kao što je nodebbs, npm je odgovoran za preuzimanje svog koda, rješavanje njegovih ovisnosti, održavanje dosljednosti verzija u cijelom 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 rašireni napad na lanac opskrbe NPM-a.

Node.js, npm i kako ih instalirati

Za korištenje bilo kojeg npm paketa - uključujući nodebbs - potrebno vam je Node.js i npm instalirani na vašem računalu. 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 instalirati Node.js putem upravitelja verzija poput nvm, što vam omogućuje prebacivanje između više verzija Nodea i npm-a. To olakšava testiranje vašeg projekta s različitim verzijama Nodea i izbjegava probleme s dozvolama koji se mogu pojaviti kod instalacijskih programa na razini sustava.

Možete brzo provjeriti je li Čvor i npm su već prisutni otvaranjem terminala i pokretanjem: node -v provjeriti verziju čvora i npm -v kako bi se potvrdila npm verzija.

Ako nedostaje Node.js ili je vaša verzija prestara, preuzmite Izdanje za dugoročnu podršku (LTS) iz nodejs.org za vaš operativni sustav. Na Windowsima i macOS-u, instalacijski program postavlja sve; 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 s package.json datoteka koja opisuje što sadrže.

A "modul" je jedinica koda koju možete uvesti u Node.js pomoću 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 poput nodebbs može izložiti više ulaznih točaka za svoje poslužiteljske i klijentske dijelove.

Paketi su javno objavljeni npm registar (ili u privatne registre) kako bi ih drugi programeri mogli instalirati jednostavnom naredbom. Unutar sustava, npm preuzima datoteke, provjerava stablo ovisnosti i pohranjuje sve 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 Lodasha i Chalka, pomoćni programi za pozadinske sustave poput Mongoosea i Socket.io te alati poput Jesta, Webpacka, Babela, Nodemona i Axiosa. Paket poput nodebbsa nalazio bi se uz njih kao još jedna instalacijska ovisnost koju uključujete u svoj stog aplikacije.

Rad s npm-om u komandnoj liniji

The npm sučelje naredbenog retka (CLI) je način na koji instalirate, uklanjate, ažurirate i pregledavate pakete, kao i način pokretanja projektnih skripti. U sustavu Windows obično ćete otvoriti naredbeni redak ili PowerShell; na macOS-u i Linuxu koristit ćete terminal.

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

Za lokalnu instalaciju novog paketa u vašem projektu obično se pokreće naredba npm install <package-name> iz korijena projekta. Ovim se paket preuzima u node_modules i, s modernim npm-om, automatski dodaje unos pod dependencies in package.json.

Globalne instalacije, korištenjem npm install -g <package-name>, rezervirani su za alate koje želite da budu dostupni svugdje na vašem sustavu - stvari poput nodemon, typescriptili druge CLI-je. Vaše biblioteke na razini aplikacije (uključujući nodebb-ove) gotovo uvijek pripadaju lokalno dependencies umjesto.

Inicijalizacija Node projekta i uloga package.json datoteke

Svaki ozbiljan Node.js projekt počinje s package.json datoteka koja služi kao manifest za vašu aplikaciju ili biblioteku. Pohranjuje metapodatke (naziv, verziju, opis), skripte, ovisnosti i informacije o tome kako bi se paket trebao učitati.

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 s razumnim zadanim postavkama koje kasnije možete urediti.

Jednom package.json postoji, svaki paket koji instalirate zapisuje se pod bilo kojim od dependencies, devDependenciesili druge namjenske odjeljke. To omogućuje drugom programeru da klonira vaš repozitorij i jednostavno ga pokrene npm install za vraćanje cijelog stabla ovisnosti.

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

Lokalna vs globalna instalacija npm paketa

Lokalni paketi se instaliraju u trenutni projekt 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 ovisnosti te aplikacije.

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

Globalni paketi, instalirani s npm install -g, smješteni su na lokaciju na razini sustava i obično otkrivaju alate naredbenog retka. To biste mogli koristiti za nodemon, typescript, ili za generatore globalnih projekata, ali rijetko želite da aplikacijski kod poput nodebbs-a bude globalan.

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

Upravljanje ovisnostima: instaliranje, ažuriranje i uklanjanje

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

Instaliranje svih ovisnosti u postojećem projektu jednostavno je kao pokretanje npm install u direktoriju gdje package.json života. npm čita popis ovisnosti i devDependencies te ponovno stvara node_modules mapu u skladu s tim.

Za dodavanje jedne ovisnosti, pokrećete npm install <package-name> (Ili npm i <package-name> skraćeno), opcionalno sa zastavicama poput --save-dev, --save-optional, ili --no-saveOve zastavice kontroliraju je li paket zabilježen kao regularna ovisnost, ovisnost samo za razvoj ili se uopće ne zapisuje.

Ažuriranje ovisnosti može se obaviti na razini 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 s npm update <package-name>, ili dodajte -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 ovisnosti, razvojnih ovisnosti i opcionalnih ovisnosti

In package.json, npm razlikuje različite vrste ovisnosti ovisno o tome kada i kako su potrebne. Ispravnim odvajanjem vaš proizvodni paket ostaje vitak, a alati fleksibilni.

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 svog poslužiteljskog paketa.

devDependencies sadrži pakete koji su potrebni samo tijekom 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 instalacija opcionalne ovisnosti ne uspije, npm je neće tretirati kao fatalnu pogrešku; očekuje se da će vaš kod elegantno riješiti njezinu odsutnost.

Zastave kao što su --save-prod (zadano), --save-dev (Ili -D), A --save-optional kontrolirati gdje se novoinstalirani paket zapisuje. Povijesno gledano, postojala je eksplicitna --save zastava, ali moderni npm tretira npm install <name> kao operacija spremanja u ovisnosti 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 ovisite o složenim bibliotekama ili o paketu poput nodebbs-a koji se može razvijati tijekom vremena. Semver koristi obrazac MAJOR.MINOR.PATCH (na primjer, 1.4.3).

U sjemveru, GLAVNI broj prirasti kada dođe do kritičnih promjena, MALO za dodavanje značajki kompatibilnih s prethodnim verzijama i KRPICA za ispravke programskih pogrešaka koje ne bi trebale narušavati postojeći kod. Ovaj model omogućuje razvoj paketa bez stalnog narušavanja aplikacija u nizvodnom kodu.

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

Unutar package.json, možete odrediti fleksibilne raspone pomoću znakova poput ^ i ~ ili koristiti "latest" or * kako biste uvijek preuzeli 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 naredbenog retka koje želite da budu dostupne bez obzira na kojem projektu radite. Ovi alati registriraju izvršne datoteke na vašem PATH-u tako da ih možete pozvati izravno iz terminala.

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

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

Ažuriranje ili uklanjanje globalnih alata funkcionira 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 najnovije ispravke i sigurnosne zakrpe.

Popisivanje, pregled i revizija instaliranih paketa

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

npm list prikazuje hijerarhiju lokalno instaliranih paketa u trenutnom projektu, uključujući ugniježđene ovisnosti na koje se vaše izravne ovisnosti 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še razine. To održava izlaz čitljivim, posebno kada postoji mnogo ugniježđenih ovisnosti.

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

Redovite revizije i ažuriranja drastično smanjuju rizik izlaganja vaše aplikacije poznatim ranjivostima skrivenim u modulima trećih strana - na primjer, pogledajte lažno predstavljanje zlonamjernog npm paketaTo je posebno važno kada se oslanjate na velike pakete poput nodebbs što može dovesti do dubokog lanca ovisnosti.

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

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

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

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 točaka, pa 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 s package.json

Osim upravljanja ovisnostima, npm služi i kao jednostavan izvršavač zadataka putem scripts dio package.jsonSkripte vam omogućuju definiranje kratkih aliasa za uobičajene naredbe koje želite pokrenuti tijekom razvoja ili implementacije.

Osnovni primjer je definiranje "start": "node app.js" pod scripts, koji zatim pokrećete pomoću npm startOvo je puno lakše zapamtiti i dijeliti nego dugu naredbenu liniju, a radi dosljedno 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 poput nodebbsNa primjer, možda imate skriptu za pokretanje migracija baze podataka prije pokretanja forumskog poslužitelja.

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

Napredne točke unosa paketa: glavni, izvoz i uvoz

Za pakete koje objavljujete - poput hipotetskog nodebbs modul — kontrola datoteka koje su vidljive korisnicima ključna je za stabilnost i sigurnost API-ja — incidenti poput tipografsko kodiranje u npm-u ilustrirati rizik.

Stariji main polje jednostavno pokazuje na primarnu datoteku unosa, 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 prema zadanim postavkama.

Noviji exports Polje je daleko moćnije: može definirati više ulaznih točaka, podržavati uvjetni izvoz na temelju okruženja ili sustava modula i blokirati pristup internim putovima na koje ne želite da se korisnici oslanjaju. Kada exports prisutan, samo su eksplicitno navedeni putevi dostupni putem golog uvoza poput 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. To vam omogućuje pažljivo oblikovanje vaše javne API površine, a istovremeno čuvanje privatnosti detalja implementacije.

Izvoz uzoraka s * omogućuju vam da otkrijete cijele mape bez navođenja svake datoteke; na primjer, "./lib/*": "./lib/*.js" mapirat će sve odgovarajuće podpute. Također možete eksplicitno blokirati određene podmape mapiranjem na null, što sprječava potrošače da uvoze te putove.

Uvjetni izvoz i ekološki osviještene izgradnje

Uvjetni izvoz omogućuju vam davanje različitih datoteka ovisno o tome kako ili gdje se vaš paket koristi. Možete poslati jednu verziju optimiziranu za import (ESM) i još jedan za require() (CommonJS) ili čak odvojene verzije za Node i preglednike.

Uvjeti 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 uvjeti se ocjenjuju redom, pa ih trebate navesti od od najspecifičnijeg do najmanje specifičnog, završavajući s "default" rezervna opcija za nepoznata okruženja. To 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ćuje 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 ovisi o izvornim dodacima u Nodeu, ali koristi polyfill negdje drugdje - pogledajte NPM sigurnost pod pritiskom.

Osim ugrađenih uvjeta, Node podržava korisnički definirane uvjete koji se prosljeđuju putem node --conditions=<name>, a širi ekosustav se usredotočio na ključeve poput "browser", "types", "development"i "production" za specijaliziranije scenarije. To pomaže u koordinaciji ponašanja između programa za generiranje paketa, provjera tipova i okruženja za izvođenje.

Uvoz podputanja i interni aliasi modula

Osim exports je imports polje u package.json omogućuje vam definiranje privatnih specifikatora uvoza koji su valjani samo unutar samog paketa. Ovi specifikatori uvijek počinju s # kako bi se izbjegao sukob s vanjskim paketima.

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

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

Pravila rješavanja za imports odražavaju one od exports, uključujući ograničenja koja drže putanje unutar korijena paketa i ne dopuštaju prelazak prema van node_modulesTo održava enkapsulaciju i sprječava iznenađujuće ponašanje.

Samoreferenciranje je još jedna napredna značajka koja omogućuje 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 točku koju dobivaju potrošači.

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

Značajke npm-a i Node-ovog rješavanja modula daju vam strogu kontrolu nad načinom na koji se složeni paketi - uključujući forumske mehanizme poput nodebbsa - strukturiraju, distribuiraju i koriste. Savladavanjem načina instalacije, upravljanja ovisnostima, semantičkog verzijanja, sigurnosnih revizija i napredne konfiguracije ulaznih točaka s 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 ekosustav oko nje nastavljaju razvijati.