skriptit

Kuvaus

Tiedoston package.json "scripts" ominaisuus tukee useita sisäänrakennettuja skriptejä ja niiden esiasetettuja elinkaaren tapahtumia sekä mielivaltaisia skriptejä. Nämä kaikki voidaan suorittaa ajamalla npm run-script <stage> tai lyhyesti npm run <stage>. Niitä varten ajetaan myös samannimiset esi- ja jälkikomennot (esim. premyscript, myscript, postmyscript). Riippuvuuksien komentosarjat voidaan ajaa komennolla npm explore <pkg> -- npm run <stage>.

Pre & Post Scripts

Luodaksesi ”pre”- tai ”post”-komentosarjoja mille tahansa komentosarjalle, joka on määritelty :n "scripts"-osiossa, luo yksinkertaisesti toinen komentosarja, jolla on yhteensopiva nimi, ja lisää niiden alkuun komentosarjat ”pre” tai ”post”.

 { 
 "scripts": { 
 "precompress": "{{ suoritetaan ENNEN `compress`-skriptiä }}", 
 "compress": "{{ suorittaa komennon tiedostojen pakkaamiseksi }}", 
 "postcompress": "{{ executes AFTER `compress` script }}" 
 } 
 } 

Elinkaaren skriptit

On joitakin erityisiä elinkaaren skriptejä, jotka tapahtuvat vain tietyissä tilanteissa. Nämä skriptit tapahtuvat ”pre”- ja ”post”-skriptien lisäksi.

• prepare, prepublish, prepublishOnly, prepack, postpack

prepare (vuodesta [email protected])

• Se suoritetaan ENNEN kuin paketti pakataan
• Se suoritetaan ENNEN kuin paketti julkaistaan
• Se suoritetaan paikallisesti npm install ilman argumentteja
• Se suoritetaan ENNEN kuin prepublish, mutta ENNEN kuin prepublishOnly
• Huom: Jos Gitin kautta asennettava paketti sisältää prepare-skriptin, sen dependencies ja devDependencies asennetaan ja prepare-skripti ajetaan, ennen kuin paketti paketoidaan ja asennetaan.

prepublish (DEPRECATED)

• Sama kuin prepare

prepublishOnly

• Suorittuu ENNEN kuin prepare

prepublishOnly

• VARRANTAA, ETTÄ paketti valmistellaan ja paketoidaan, AINOASTAAN osoitteessa npm publish.

prepack

• Suorittuu ENNEN kuin tarball pakataan (päällä ”npm pack”, ”npm publish” ja asennettaessa git-riippuvuuksia).
• Huomautus: ”npm run pack” EI ole sama kuin ”npm pack”. ”npm run pack” on mielivaltainen käyttäjän määrittelemä komentosarjan nimi, kun taas ”npm pack” on CLI:n määrittelemä komento.

postpack

• Ajetaan sen jälkeen, kun tarball on luotu ja siirretty lopulliseen määränpäähänsä.

Prepare and Prepublish

Deprecation Huomautus: prepublish

Npm CLI on vuodesta [email protected] lähtien ajanut prepublish-skriptin sekä npm publish että npm install, koska se on kätevä tapa valmistella paketti käyttöä varten (joitain yleisiä käyttötapauksia kuvataan alla olevassa kappaleessa). Se on myös osoittautunut käytännössä hyvin sekavaksi. [email protected] alkaen on otettu käyttöön uusi tapahtuma, prepare, joka säilyttää tämän nykyisen käyttäytymisen. Uusi tapahtuma, prepublishOnly, on lisätty siirtymäkauden strategiaksi, jotta käyttäjät voivat välttää nykyisten npm-versioiden hämmentävää käyttäytymistä ja ajaa vain npm publish (esimerkiksi ajaa testit vielä kerran varmistaakseen, että ne ovat kunnossa).

Katso https://github.com/npm/npm/issues/10074, jossa on paljon pidemmät perustelut tälle muutokselle lisälukemistoineen.

Käyttökohteet

Jos sinun on tehtävä paketillesi operaatioita ennen sen käyttöä tavalla, joka ei ole riippuvainen kohdejärjestelmän käyttöjärjestelmästä tai arkkitehtuurista, käytä prepublish-skriptiä. Tällaisia tehtäviä ovat esimerkiksi:

• KahviScript-lähdekoodin kääntäminen JavaScriptiksi.
• Javaskriptin lähdekoodin pienennettyjen versioiden luominen.
• Pakettisi käyttämien etäresurssien noutaminen.

Etuna näiden toimintojen tekemisessä prepublish-ajankohtana on se etu, että ne voidaan tehdä vain kerran, samassa paikassa, ja näin vähennetään mutkikkuutta ja vaihtelua. Lisäksi tämä tarkoittaa, että:

• Voit olla riippuvainen coffee-script:stä devDependency, jolloin käyttäjilläsi ei tarvitse olla sitä asennettuna.
• Pakettiisi ei tarvitse sisällyttää pienentäjiä, mikä pienentää paketin kokoa käyttäjiäsi varten.
• Sinun ei tarvitse luottaa siihen, että käyttäjilläsi on kohdekoneissa curl tai wget tai muita järjestelmätyökaluja.

Elinkaaren toimintajärjestys

npm publish

• prepublishOnly
• prepare
• prepublish
• publish
• postpublish

npm pack

• prepack
• postpack

npm install

• preinstall
• install
• postinstall

Also triggers

• prepublish (kun paikallisessa)
• prepare (kun paikallisessa)

npm start

npm run start on npm start lyhenne.

• prestart
• start
• poststart

Oletusarvot

npm olettaa joitakin skriptien arvoja paketin sisällön perusteella.

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

  Jos paketin juuressa on server.js-tiedosto, npmwill olettaa start-komennolle node server.js.

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

  Jos pakettisi juuressa on binding.gyp-tiedosto, etkä ole määritellyt omia install– tai preinstall-skriptejäsi, npm olettaa install-komennon käännettäväksi käyttäen node-gyp:tä.

User

Jos npm:ää kutsuttiin pääkäyttäjän oikeuksin, se muuttaa uid:n user konfiguraatiossa määritetyksi käyttäjätiliksi tai uid:ksi, jonka oletusarvo on nobody. Aseta unsafe-perm -lippu suorittaaksesi skriptejä root-oikeuksilla.

Environment

Pakettiskriptit suoritetaan ympäristössä, jossa monet tiedot ovat saatavilla npm:n asetuksista ja prosessin senhetkisestä tilasta.

path

Jos olet riippuvainen moduuleista, jotka määrittelevät suoritettavia skriptejä, kuten testsuites, nämä suoritettavat skriptit lisätään PATH:een suoritettavien skriptien suorittamiseksi. Jos siis package.jsonissasi on tämä:

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

tällöin voit ajaa npm start suorittaaksesi bar skriptin, joka viedään node_modules/.bin hakemistoon npm install.

package.json vars

Package.json-kentät on tarttunut npm_package_ etuliitteeseen. Eli jos sinulla olisi esimerkiksi {"name":"foo", "version":"1.2.5"}package.json-tiedostossa, pakettiskripteissäsi olisi npm_package_name-ympäristömuuttujaksi asetettu ”foo” ja npm_package_version-muuttujaksi ”1.2.5”. Voit käyttää näitä muuttujia koodissasi process.env.npm_package_name:llä japrocess.env.npm_package_version:llä, ja niin edelleen muiden kenttien kohdalla.

configuration

Konfiguraatioparametrit laitetaan ympäristöön npm_config_-etuliitteellä. Voit esimerkiksi tarkastella tehokasta rootkonfigia tarkistamalla ympäristömuuttujan npm_config_root.

Erikoinen: package.json ”config”-objekti

Package.json ”config”-avaimet ylikirjoitetaan ympäristössä, joson config-parametrina <name>:<key>. Jos esimerkiksi package.jsonissa on tämä:

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

ja server.js on tämä:

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

jolloin käyttäjä voisi muuttaa käyttäytymistä tekemällä:

 npm config set foo:port 80 

nykyisen elinkaaren tapahtuma

Viimeiseksi ympäristömuuttuja npm_lifecycle_event asetetaan siihen, mikä elinkaaren vaihe on suorituksessa. Sinulla voi siis olla yksi skripti, jota käytetään prosessin eri vaiheisiin ja joka vaihtaa sen mukaan, mitä parhaillaan tapahtuu.

Objektit tasoitetaan tätä muotoa noudattaen, joten jos paketissasi olisi {"scripts":{"install":"foo.js"}}.json, niin näkisit skriptissä tämän:

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

Esimerkkejä

Jos esimerkiksi paketti.jsonissasi on tämä:

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

tällöin scripts/install.js kutsutaan elinkaaren asennus- ja asennuksen jälkeisissä vaiheissa ja scripts/uninstall.js kutsutaan, kun paketti poistetaan. Koskascripts/install.js suoritetaan kahdessa eri vaiheessa, olisi tässä tapauksessa viisasta tarkastella ympäristömuuttujaa npm_lifecycle_event.

Jos haluat suorittaa make-komennon, voit tehdä sen. Tämä toimii hienosti:

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

Poistuminen

Skriptit ajetaan välittämällä rivi skriptiargumenttina kohtaan sh.

Jos skripti poistuu muulla koodilla kuin 0, tämä keskeyttää prosessin.

Huomaa, että näiden skriptitiedostojen ei tarvitse olla nodejs- tai edesjavascript-ohjelmia. Niiden on vain oltava jonkinlainen suoritettava tiedosto.

Koukkuskriptit

Jos haluat ajaa tietyn skriptin tietyssä elinkaaritapahtumassa KAIKILLE paketeille, voit käyttää koukkuskriptia.

Sijoita suoritettava tiedosto kohtaan node_modules/.hooks/{eventname}, niin se ajetaan kaikille paketeille, kun ne kulkevat tuon pisteen läpi pakettien elinkaaressa kaikkien kyseiseen juureen asennettujen pakettien osalta.

Hook-skriptit ajetaan täsmälleen samalla tavalla kuin package.json-skriptit. eli ne ovat erillisessä lapsiprosessissa, jossa on edellä kuvattu env.

Parhaat käytännöt

• Älä poistu nollasta poikkeavalla virhekoodilla, ellet tosissasi tarkoita sitä. paitsi uninstall-skriptien kohdalla, tämä aiheuttaa npm-toiminnon epäonnistumisen ja mahdollisen palautuksen. Jos virhe on vähäinen tai estää vain joitakin valinnaisia ominaisuuksia, on parempi vain tulostaa varoitus ja poistua onnistuneesti.
• Yritä olla käyttämättä skriptejä siihen, mitä npm voi tehdä puolestasi. Lue läpipackage.json nähdäksesi kaikki asiat, jotka voit määrittää ja ottaa käyttöön yksinkertaisesti kuvaamalla pakettisi asianmukaisesti. Yleensä tämä johtaa vankempaan ja johdonmukaisempaan tilaan.
• Tarkastele env:tä määrittääksesi, mihin asiat kannattaa laittaa. Jos esimerkiksi ympäristömuuttujan npm_config_binroot arvoksi on asetettu /home/user/bin, älä yritä asentaa suoritettavia tiedostoja arvoon /usr/local/bin. Käyttäjä on luultavasti asettanut sen näin syystä.
• Älä aloita komentosarjakomentoja sanalla ”sudo”. Jos root-oikeudet vaaditaan jostain syystä, se epäonnistuu tällä virheellä, ja käyttäjä sudoaa kyseisen npm-komennon.
• Älä käytä install. Käytä .gyp-tiedostoa kääntämiseen ja prepublish kaikkeen muuhun. Sinun ei pitäisi melkein koskaan joutua asettamaan nimenomaisesti apreinstall- tai install-skriptiä. Jos teet näin, harkitse, onko muuta vaihtoehtoa. Ainoa pätevä install– tai preinstallskriptien käyttö on kääntäminen, joka on tehtävä kohdearkkitehtuurilla.

Katso myös

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