Node.js:n ja npm:n käyttö Seravon ympäristössä

Node.js ja sen paketinhallintatyökalu npm (Node Package Manager) auttavat hallinnoimaan sivuston tai teeman JavaScript-paketteja ja varmistamaan, että asennukset ovat yhdenmukaisia eri ympäristöissä. Nämä työkalut ovat erityisen tärkeitä modernien WordPress-teemojen ja -projektien kehityksessä.

Seravon ympäristössä Node.js ja npm ovat valmiiksi asennettuina hakemistossa /data/wordpress.

Käytön aloittaminen

Kuten Composeria, myös npm:ää käytetään komentorivin (SSH) kautta. Varmista aina ensimmäisenä, että olet oikeassa hakemistossa. Yleisimmät sijainnit ovat:

/data/wordpress/ (koko sivuston laajuiset paketit)
/data/wordpress/htdocs/wp-content/themes/oma-teema/ (teemakohtaiset paketit)

Yleisimmät komennot

Kun projektissasi on package.json-tiedosto, voit asentaa paketit komennolla:

npm install

Tämä komento asentaa paketit ja niiden riippuvuudet node_modules-kansioon ja päivittää tarvittaessa package-lock.json-tiedoston.

Jos olet tuomassa olemassa olevaa projektia toisesta ympäristöstä ja projektissa on package-lock.json-tiedosto, on suositeltavaa käyttää komentoa (clean install):

npm ci

Tämä asentaa paketit käyttäen tiukasti vain lukitustiedoston määrittelemiä versioita varmistaen, että ympäristö vastaa kehitysympäristöäsi. Komento poistaa olemassa olevan node_modules-kansion ennen asennusta.

Yksittäisen uuden paketin asennus ja poisto onnistuvat komennoilla:

npm install <paketin-nimi>
npm uninstall <paketin-nimi>

Pakettien päivitys (lukitustiedoston sääntöjen puitteissa):

npm update

Teeman rakentaminen (Build)

Pelkkä pakettien asentaminen ei riitä, vaan projektin CSS- ja JS-tiedostot on usein generoitava julkaisuvalmiiseen muotoon. Tämä tehdään yleensä komennolla:

npm run build

Modernit teemat (esim. Roots Sage)

Monet modernit teemat nojaavat npm-paketteihin ja Composer-pohjaiseen rakenteeseen. Teeman paketointi vaatii Seravolla yleensä seuraavat askeleet:

Aja composer install hakemistossa /data/wordpress/. Tarkista myös, onko teeman kansiossa oma erillinen composer.json -tiedosto, ja aja komento tarvittaessa myös siellä.
Siirry teeman kansioon. Jos kansiosta löytyy package-lock.json, aja komento npm ci (muussa tapauksessa npm install).
Rakenna teeman tiedostot komennolla npm run build.

Huom: Jotkin teemat käyttävät oletuksena Yarn-paketinhallintaa. Jos teeman kansiossa on yarn.lock-tiedosto, käytä Yarn-komentoja (esim. yarn install ja yarn build).

Node.js-sovellusten ajaminen taustalla

WordPressin rinnalla on mahdollista ajaa myös jatkuvasti toimivia Node.js-sovelluksia, kuten kevyitä mikropalveluita (esim. API-rajapinnat tai chatbotit).

Prosessien hallinta (PM2)

Jatkuvasti pyörivät sovellukset tarvitsevat toimiakseen prosessinhallintatyökalun, jotta sovellus pysyy käynnissä taustalla, vaikka palvelin käynnistettäisiin uudelleen (esim. huoltotoimenpiteiden yhteydessä). Yleisesti käytetty työkalu tähän on PM2:

npm install -g pm2

Automaattinen uudelleenkäynnistys (Crontab)

Seravon palveluympäristöissä ei ole pääkäyttäjän (sudo) oikeuksia, joten PM2:n omat automaattiset käynnistysskriptit eivät toimi. Voit automatisoida uudelleenkäynnistyksen lisäämällä käynnistyskomennon palvelimen crontab-tiedostoon @reboot-määreellä:

Avaa crontab muokattavaksi: crontab -e

Lisää rivi:

@reboot pm2 start /data/wordpress/nodeapps/sovellus/sovellus.config.cjs

Sovelluksen julkaiseminen ulkoverkkoon

Kun Node-sovellus pyörii palvelimen taustalla (esim. osoitteessa http://localhost:3030), se ei ole suoraan näkyvissä ulkoverkkoon. Älä yritä ohjata liikennettä suoraan palvelimen IP-osoitteeseen, vaan tee sovellukselle käänteinen välityspalvelin (reverse proxy) nginxillä.

Voit luoda oman nginx-konfiguraation hakemistoon /data/wordpress/nginx/, joka ohjaa halutun polun liikenteen paikalliseen porttiin. Esimerkki sovellus.conf:

location ^~ /api/sovellus {
  proxy_pass http://127.0.0.1:3030/;
  proxy_set_header Host $http_host;
  proxy_set_header X-Forwarded-Host $http_host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
}

Mahdolliset vikatilanteet

Virhe: ERESOLVE unable to resolve dependency tree

Tämä pysäyttää asennuksen ja johtuu pakettien välisestä versioristiriidasta. Jos olet varma, että projekti toimii nykyisillä versioilla, voit ohittaa virheen: npm install --legacy-peer-deps (tai npm ci --legacy-peer-deps)

Generointi onnistui, mutta sivustolla on 404-virheitä

Tarkista functions.php-tiedostosta polut, joissa tyylit tai skriptit ladataan (wp_enqueue_style / wp_enqueue_script), ja varmista, että ne ovat oikein. Jos käytät Roots Sagea, varmista, että manifest.json-tiedosto on onnistuneesti luotu dist- tai public-kansioon.

Fatal Error generoinnin yhteydessä

Syynä on usein puuttuvat Composer-paketit. Tarkista, onko teemassasi oma composer.json-tiedosto. Jos on, muista ajaa teeman kansiossa composer install luodaksesi vaaditun vendor-kansion ennen generointia.

Aiheeseen liittyvät artikkelit