scripts

Leírás

A fájl "scripts" tulajdonsága számos beépített szkriptet és azok előre beállított életciklus eseményeit, valamint tetszőleges szkripteket támogat. Ezek mindegyike a npm run-script <stage> vagy röviden npm run <stage> futtatásával hajtható végre. A megfelelő nevű pre és post parancsok ezekhez is lefutnak (pl. premyscript, myscript, postmyscript). A függőségekből származó szkriptek a npm explore <pkg> -- npm run <stage> paranccsal futtathatók.

Pre & Post szkriptek

A "scripts" szakaszban definiált bármely szkripthez “pre” vagy “post” szkriptek létrehozásához egyszerűen hozzon létre egy másik szkriptet megfelelő névvel, és adja hozzá a “pre” vagy “post” parancsot azok elejéhez.

 { 
 "szkriptek":  "{{ a `compress` szkript előtt hajtódik végre }}", 
 "compress": 
 "postcompress": "{{ parancs végrehajtása a fájlok tömörítéséhez }}", 
 "postcompress": "{{ executes AFTER `compress` script }}}" 
 } 
 } 

Életciklus szkriptek

Vannak speciális életciklus szkriptek, amelyek csak bizonyos helyzetekben történnek. Ezek a szkriptek a “pre” és “post” szkriptek mellett történnek.

• prepare, prepublish, prepublishOnly, prepack, postpack

prepare ([email protected] óta)

• Fut a csomag becsomagolása ELŐTT
• Fut a csomag közzététele ELŐTT
• Fut a helyi npm install-n mindenféle argumentum nélkül
• Fut a prepublish után, de prepublishOnly
• MEGJEGYZÉS: Ha egy git-en keresztül telepítendő csomag tartalmaz egy prepare szkriptet, akkor annak dependencies és devDependencies szkriptje telepítésre kerül, és a prepare szkript lefut, mielőtt a csomag csomagolása és telepítése megtörténne.

prepublish (DEPRECATED)

• Ugyanaz, mint prepare

prepublishOnly

• Fut a csomag előkészítése és csomagolása ELŐTT, CSAK npm publish esetén.

prepack

• Fut a tarball csomagolása ELŐTT (a “npm pack“, “npm publish” és a git függőségek telepítésekor).
• MEGJEGYZÉS: A “npm run pack” NEM azonos a “npm pack“-val. A “npm run pack” egy tetszőleges, felhasználó által definiált szkriptnév, míg a “npm pack” egy CLI által definiált parancs.

postpack

• Fut azután, hogy a tarball elkészült és a végső célállomásra került.

Prepare and Prepublish

Deprecation Megjegyzés: prepublish

Az npm CLI [email protected] óta npm publish és npm install esetén is futtatja a prepublish szkriptet, mivel ez egy kényelmes módja a csomag használatra való előkészítésének (néhány gyakori felhasználási esetet az alábbi részben ismertetünk). Az is kiderült, hogy a gyakorlatban nagyon zavaró. A [email protected]-tól kezdve bevezetésre került egy új esemény, a prepare, amely megőrzi ezt a meglévő viselkedést. Egy új esemény, a prepublishOnly egy átmeneti stratégiaként lett hozzáadva, hogy a felhasználók elkerülhessék a meglévő npm-verziók zavaró viselkedését, és csak a npm publish-nél fussanak (például még egyszer utoljára lefuttatva a teszteket, hogy biztosítsák, hogy azok jó állapotban vannak).

Az https://github.com/npm/npm/issues/10074-ben található egy sokkal hosszabb indoklás, további olvasnivalókkal, erre a változtatásra.

Használati esetek

Ha a csomagon a használat előtt olyan műveleteket kell végrehajtani, amelyek nem függnek a célrendszer operációs rendszerétől vagy architektúrájától, használjon egy prepublish szkriptet. Ide tartoznak az olyan feladatok, mint:

• A CoffeeScript forráskód JavaScriptre történő fordítása.
• A JavaScript forráskód kicsinyített változatainak létrehozása.
• A csomagod által használt távoli erőforrások lekérése.

Az ilyen dolgok prepublish időben történő elvégzésének előnye, hogy egyszer, egyetlen helyen elvégezhetők, így csökkenthető a bonyolultság és a változékonyság. Továbbá ez azt jelenti, hogy:

• Függhetsz a coffee-script-től mint devDependency-től, és így a felhasználóidnak nem kell telepíteniük.
• Nem kell minifikátorokat beépítened a csomagodba, csökkentve ezzel a felhasználók számára a méretet.
• Nem kell arra támaszkodnod, hogy a felhasználóidnak curl vagy wget vagy más rendszereszközök legyenek a célgépeken.

Életciklus Működési sorrend

npm publish

• prepublishOnly
• prepare
• prepublish
• publish
• postpublish

npm pack

• prepack
• postpack

npm install

• preinstall
• install
• postinstall

Ez is kiváltja

• prepublish (ha a helyi)
• prepare (ha a helyi)

npm start

npm run start van egy npm start rövidítés.

• prestart
• start
• poststart

Alapértelmezett értékek

Az npm a csomagok tartalma alapján alapértelmez néhány szkript értéket.

• "start": "node server.js":

  Ha a csomag gyökerében van egy server.js fájl, akkor az npmwill a start parancsot node server.js-re fogja alapértelmezni.

• "install": "node-gyp rebuild":

  Ha van egy binding.gyp fájl a csomagja gyökerében, és nem definiált saját install vagy preinstall szkripteket, akkor az npm a install parancsot a node-gyp segítségével fordítja le.

User

Ha az npm-et root jogosultságokkal hívta meg, akkor az uid-et a user config által megadott felhasználói fiókra vagy uid-re változtatja, ami alapértelmezés szerint nobody. A szkriptek root jogosultságokkal történő futtatásához állítsa be a unsafe-perm flaget.

Environment

A csomagszkriptek egy olyan környezetben futnak, ahol számos információ elérhetővé válik az npm beállításával és a folyamat aktuális állapotával kapcsolatban.

path

Ha olyan moduloktól függ, amelyek futtatható szkripteket határoznak meg, mint például a testsuites, akkor a szkriptek futtatásához a PATH-hoz hozzáadja ezeket a futtatható fájlokat. Tehát, ha a package.json-ban ez van:

 { 
 "name" : "foo", 
 "dependencies" : { 
 "bar" : "0.1.x" 
 }, 
 "scripts": { 
 "start" : "bar ./test" 
 } } 
 } 

akkor a npm start futtathatja a bar szkriptet, amely a npm install könyvtárba exportálódik a node_modules/.bin könyvtárba npm install.

package.json vars

A package.json mezők a npm_package_ előtagra vannak ragasztva. Így például, ha apackage.json fájlodban {"name":"foo", "version":"1.2.5"} lenne, akkor a csomag szkriptjeidben anpm_package_name környezeti változó “foo”-ra, anpm_package_version pedig “1.2.5”-re lenne állítva. Ezeket a változókat a kódodban process.env.npm_package_name ésprocess.env.npm_package_version segítségével érheted el, és így tovább a többi mező esetében.

configuration

A konfigurációs paraméterek anpm_config_ előtaggal kerülnek a környezetbe. Például a tényleges rootkonfigurációt a npm_config_root környezeti változó ellenőrzésével tekintheti meg.

Speciális: package.json “config” objektum

A package.json “config” kulcsok felülíródnak a környezetben, ha van egy <name>:<key> config paraméter. Például,ha a package.jsonban ez van:

 { 
 "name" : "foo", 
 "config" : { 
 "port" : "8080" 
 }, 
 "scripts" : { 
 "start" : "node server.js" 
 } } 
 } 

és a server.js ez:

 http.createServer(....).listen(process.env.npm_package_config_port) 

akkor a felhasználó megváltoztathatja a viselkedést a következővel:

 npm config set foo:port 80 

aktuális életciklus esemény

Végül a npm_lifecycle_event környezeti változót állítja be, hogy a ciklus melyik szakaszát hajtja végre. Így egyetlen szkriptet használhatsz a folyamat különböző részeire, amely az aktuális esemény alapján vált.

Az objektumok ezt a formátumot követve laposodnak, tehát ha a csomagodban {"scripts":{"install":"foo.js"}} lenne.json, akkor ezt látnád a szkriptben:

 process.env.npm_package_scripts_install === "foo.js" 

Példák

Ha például a package.json ezt tartalmazza:

 { 
 "scripts" : { 
 "install" : "scripts/install.js", 
 "postinstall" : "scripts/install.js", 
 "uninstall" : "scripts/uninstall.js" 
 } } 
 } 

akkor a scripts/install.js meghívásra kerül az életciklus telepítési és telepítés utáni szakaszában, és a scripts/uninstall.js meghívásra kerül a csomag eltávolításakor. Mivel ascripts/install.js két különböző fázisban fut, ebben az esetben célszerű lenne megnézni a npm_lifecycle_event környezeti változót.

Ha egy make parancsot akarsz futtatni, megteheted. Ez tökéletesen működik:

 { 
 "scripts" : { 
 "preinstall" : "./configure", 
 "install" : "make && make install", 
 "test" : "make test" 
 } } 
 } 

Kilépés

A szkriptek futtatása úgy történik, hogy a sort átadjuk a sh szkript argumentumként.

Ha a szkript 0-tól eltérő kóddal lép ki, akkor ez megszakítja afolyamatot.

Megjegyezzük, hogy ezeknek a szkriptfájloknak nem kell nodejs vagy akárjavascript programoknak lenniük. Csak valamilyen futtatható fájlnak kell lenniük.

Hook szkriptek

Ha egy adott szkriptet akar futtatni egy adott életciklus eseménynél MINDEN csomagra, akkor használhat egy hook szkriptet.

Tegyünk egy futtatható fájlt a node_modules/.hooks/{eventname} pontra, és ez minden csomagra lefut, amikor a csomag életciklusában ezen a ponton keresztülmennek az adott gyökérbe telepített összes csomagra.

A hook szkriptek pontosan ugyanúgy futnak, mint a package.json szkriptek.Vagyis egy külön gyermekfolyamatban vannak, a fentebb leírt env-vel.

Legjobb gyakorlatok

• Ne lépjen ki nem nulla hibakóddal, hacsak nem gondolja komolyan.Az uninstall szkriptek kivételével ez az npm művelet sikertelenségét és esetleges visszafordítását eredményezi. Ha a hiba kisebb, vagy csak néhány opcionális funkciót akadályoz meg, akkor jobb, ha csak egy figyelmeztetést ír ki, és sikeresen kilép.
• Próbálj meg nem szkripteket használni arra, amit az npm megtehet helyetted. Olvassa végigpackage.json, hogy lássa, mennyi mindent megadhat és engedélyezhet egyszerűen azzal, hogy megfelelően leírja a csomagját. Általában ez egy robusztusabb és konzisztensebb állapothoz fog vezetni.
• Nézd meg az env-t, hogy meghatározd, hova tedd a dolgokat. Például, haa npm_config_binroot környezeti változó /home/user/bin-ra van beállítva, akkor ne próbáljon futtatható fájlokat telepíteni a /usr/local/bin-ba. A felhasználó valószínűleg okkal állította be így.
• Ne írja be a szkriptparancsok elé a “sudo” szót. Ha valamilyen oknál fogva root jogosultságok szükségesek, akkor ezzel a hibával sikertelen lesz, és a felhasználó sudo-zni fogja a kérdéses npm parancsot.
• Ne használd a install-t. Használjon .gyp fájlt a fordításhoz, és prepublishminden máshoz. Szinte soha nem kell explicit módon beállítania apreinstall vagy install scriptet. Ha ezt teszi, kérjük, fontolja meg, hogy van-e más lehetőség. A install vagy preinstallszkriptek egyetlen érvényes használata a fordításhoz szükséges, amit a célarchitektúrán kell elvégezni.

Lásd még

• npm run-script
• package.json
• npm developers
• npm install

.