npm-komennot: pakettienhallinnan opas

01Mikä on npm ja mihin sitä käytetään?

npm (Node Package Manager) on JavaScript-maailman pakettienhallinta. Sen avulla voit lisätä projektiisi muiden kirjoittamia kirjastoja, seurata niiden versioita ja ajaa projektiin liittyviä komentoja yhdestä paikasta.

npm tulee Node.js:n mukana; sitä ei tarvitse asentaa erikseen. Jos et ole vielä asentanut Node.js:ää, seuraa ensin oppaamme Node.js:n asennus ja kokeile sitten tämän artikkelin komentoja omassa päätteessäsi.

npm:llä on kolme osaa: tietokoneellasi oleva komentorivityökalu, pakettien isännöinnistä vastaava rekisteri (registry) ja jokaisen projektin sydän, package.json-tiedosto. Lähes kaikki komennot lukevat tai päivittävät tätä tiedostoa.

02Mikä on package.json?

package.json on projektin henkilökortti: siihen kirjoitetaan nimi, versio, riippuvuudet ja ajettavat skriptit. Uudessa projektissa luot tämän tiedoston komennolla npm init; -y-lippu ohittaa kaikki kysymykset oletusvastauksilla.

• dependencies: Paketit, joita sovellus tarvitsee toimiessaan.
• devDependencies: Vain kehityksen ja käännöksen aikana tarvittavat työkalut (kääntäjä, testityökalu, muotoilija).
• scripts: npm run -komennolla ajettavat lyhyet komennot.
• package-lock.json: Tallentaa jokaisen asennetun paketin tarkan version; lisää tämä tiedosto aina Gitiin.

mkdir ilk-proje
cd ilk-proje
npm init -y

{
  "name": "ilk-proje",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "node --test"
  },
  "dependencies": {
    "axios": "^1.7.0"
  },
  "devDependencies": {
    "vite": "^6.0.0"
  }
}

03Pakettien asennus npm install -komennolla

npm install on eniten käytetty komento, ja se tekee kaksi eri asiaa. Yksinään kirjoitettuna se asentaa kaikki package.json-tiedoston riippuvuudet node_modules-kansioon; paketin nimen kanssa kirjoitettuna se asentaa paketin ja lisää sen package.json-tiedostoon. Lyhyt muoto on npm i.

# Asenna projektin kaikki riippuvuudet
npm install

# Yeni paket ekle (dependencies)
npm install axios

# Lisää kehitystyökalu (devDependencies)
npm install -D prettier

# Asenna tietty versio
npm install lodash@4

# Globaali asennus (komentorivityökaluille)
npm install -g serve

# Poista paketti
npm uninstall axios

Globaali vai paikallinen?

Asenna paketit mahdollisuuksien mukaan paikallisesti; näin projekti toimii samalla versiolla myös toisella tietokoneella. Varaa globaali asennus vain komentorivityökaluille, joita käytät kaikkialla, ja kertaluontoisiin työkaluihin riittää npx.

Milloin npm ci:tä käytetään?

npm ci poistaa node_modules-kansion ja asentaa package-lock.json-tiedoston versiot sellaisenaan eikä muuta lukitustiedostoa. Se sopii ihanteellisesti palvelimelle julkaisuun, jatkuvan integraation putkiin ja ”minulla se toimi” -ongelmien ratkaisuun.

04Skriptien ajaminen npm run -komennolla

package.json-tiedoston scripts-kenttä antaa pitkille komennoille lyhyet nimet. Näin jokainen tiimissä käynnistää kehityspalvelimen komennolla npm run dev ja tuotantokäännöksen komennolla npm run build tuntematta työkalun yksityiskohtia.

Jotkin nimet, kuten start ja test, ovat erityisiä; ne toimivat ilman run-sanaa. Skriptille lisäparametrien välittämiseen käytetään kahta viivaa.

npm run dev
npm run build
npm start
npm test

# Listaa kaikki määritellyt skriptit
npm run

# Parametrin välittäminen skriptille
npm run build -- --mode staging

pre- ja post-skriptit

Jos lisäät skriptin nimen eteen pre tai post, npm ajaa sen automaattisesti ennen tai jälkeen. Esimerkiksi prebuild-niminen skripti voi tyhjentää vanhan käännöskansion juuri ennen komentoa npm run build. Tämä järjestely varmistaa, ettei kukaan tiimissä unohda vaihetta.

Miksi skriptit löytävät paikalliset työkalut?

npm run lisää ajon ajaksi projektin node_modules/.bin-kansion väliaikaisesti PATH-muuttujaan. Siksi skriptiin riittää kirjoittaa vain vite tai prettier; työkalua ei tarvitse asentaa globaalisti. Jos sama työkalu ei löydy kirjoitettaessa suoraan päätteeseen, syy on tämä, ja ratkaisu on käyttää npx:ää.

Käyttöjärjestelmäerot skripteissä

Komennot kuten rm -rf eivät toimi Windowsin oletuskuoressa. Jos tiimissä on eri käyttöjärjestelmiä, suosi skripteissä alustasta riippumattomia Node.js-työkaluja tai lyhyitä Node.js-skriptejä; näin sama package.json antaa jokaisella koneella saman tuloksen.

05Pakettien päivittäminen ja tarkastus

Paketteja päivitetään säännöllisesti; tietoturva-aukkoja korjataan ja uusia ominaisuuksia tulee. Ennen päivitystä aja komento npm outdated nähdäksesi, mikä on vanhentunut.

package.json-tiedoston ^-merkki sallii pienet ja korjausversiot (1.7.0 → 1.9.2), ~-merkki vain korjausversiot (1.7.0 → 1.7.5). npm update päivittää näiden rajojen sisällä; pääversion ylittämiseksi paketti on asennettava uudelleen @latest-tunnisteella, ja se vaatii yleensä muutoksia koodiin.

# Eskiyen paketleri listele
npm outdated

# Päivitä sallitulla välillä
npm update

# Siirry uuteen pääversioon (käytä varoen)
npm install axios@latest

# Tietoturvatarkastus
npm audit
npm audit fix

# Näytä asennetut paketit
npm ls --depth=0
npm ls -g --depth=0

# Paketin uusin julkaistu versio
npm view axios version

06Mikä on npx ja milloin sitä käytetään?

npx on npm:n mukana tuleva paketinajaja. Sen avulla voit ajaa työkalun kertaluontoisesti asentamatta sitä globaalisti; työkalua etsitään ensin projektin node_modules-kansiosta, ja jos sitä ei löydy, se ladataan väliaikaisesti.

Projektipohjan luominen on npx:n yleisin käyttö. Esimerkiksi uuden React-projektin avaamiseen Vitellä käytetään npm create -komentoa; yksityiskohdat löydät artikkelista React-asennus Vitellä.

# Julkaise kansio paikallisella palvelimella
npx serve .

# Suorita projektiin asennettu muotoilija
npx prettier --write .

# Uusi projekti mallipohjasta (tekee saman kuin npm create, npx create-...)
npm create vite@latest

07npm, yarn ja pnpm: erot

npm ei ole ainoa vaihtoehto; myös yarn ja pnpm asentavat paketteja samasta rekisteristä. Koska kaikki kolme käyttävät package.json-tiedostoa, projektin rakenne ei muutu; ero näkyy asennusnopeudessa, levynkäytössä ja lukitustiedostossa.

• Käytä projektissa vain yhtä pakettienhallintaa; kahden lukitustiedoston olemassaolo johtaa versiosekaannukseen.
• Jos liityt olemassa olevaan projektiin, katso kansion lukitustiedostoa ja valitse sama työkalu.
• Jos aloitat uutena, aloittaminen npm:llä on kitkattomin tie.

08Yleiset virheet ja ratkaisut

Suurin osa npm-virheistä johtuu rikkinäisestä välimuistista, yhteensopimattomasta Node.js-versiosta tai ristiriitaisista riippuvuuksista. Lue ensin virheilmoituksen ensimmäiset rivit; ratkaisu kerrotaan yleensä siellä.

• ERESOLVE / peer dependency -virhe: Jokin paketeista odottaa toisen paketin eri versiota. Päivitä paketit yhteensopiviin versioihin; väliaikaisena ratkaisuna voi käyttää komentoa npm install --legacy-peer-deps.
• Rikkinäinen node_modules: Poista node_modules-kansio ja aja npm install tai npm ci. Lukitustiedoston poistaminen on viimeinen keino.
• Välimuisti-ongelma: npm cache verify tarkistaa välimuistin; tarvittaessa tyhjennä se komennolla npm cache clean --force.
• EACCES-käyttöoikeusvirhe: Älä käytä sudoa globaalissa asennuksessa; asenna Node.js uudelleen nvm:llä.
• Engine-varoitus: Jos paketti vaatii uudemman Node.js:n, siirry nvm:llä LTS-versioon.

09npm:n oikea käyttö projekteissa

Tarpeettoman monet paketit lisäävät sekä tietoturvariskiä että selaimelle lähetettävän JavaScriptin määrää. Kysymys ”voinko ratkaista tämän muutamalla koodirivillä?” ennen jokaista uutta riippuvuutta on sivun nopeuden halvin optimointi. Käsittelemme tätä aihetta säännöllisesti nopeus- ja suorituskykyoptimointi -palvelussamme.

Älä koskaan lisää node_modules-kansiota Gitiin; kirjoita se .gitignore-tiedostoon ja jaa vain package.json ja lukitustiedosto. Projektin lähettämisen etävarastoon kävimme läpi vaihe vaiheelta oppaassamme projektin lataaminen GitHubiin.

Jos suunnittelet yrityksellesi verkkosivujen suunnittelua tai maksu-, toimitus- ja kirjanpitojärjestelmiä yhdistävää integraatioprojektia, riippuvuuksien hallinnan rakentaminen oikein heti alussa alentaa ylläpitokustannuksia pitkällä aikavälillä. Lisää Node.js-sisältöä löydät nodejs-tunnisteen sivulta.