Seravon esimerkkiprojekti kehittäjien tueksi

Seravo on jo pitkään tarjonnut WordPress-kehittäjille valmiin projektipohjan, joka toimii perustana uusien sivustojen luomiselle ja kehitykselle. Projektipohja löytyy palvelimelta valmiiksi asennettuna, kun tilaat WordPress-palvelupaketin Seravolta.

Projektin työkaluihin kuuluvat mm. Git, Composer, Nginx ja Docker. Projektipohjasta on kuitenkin puuttunut esimerkki siitä, miten projektin juuresta voidaan hallita koko projektin build-prosessia.

Tähän vastauksena olemme julkaisseet WordPress-kehittäjille esimerkkiprojektin, jonka tavoitteena on esitellä aiempaa käytännöllisempi projektipohja. Uudessa projektipohjassa käytetään WordPress-yhteisön työkaluja mahdollisimman paljon:

• @wordpress/scripts build-prosessiin.
• NPM workspaces projektin eri osien, kuten kustomoitujen lisäosien ja teemojen määrittelyyn.

Esimerkkiprojektin keskeisimmät ominaisuudet

Esimerkkiprojektin runko on täsmälleen sama kuin Seravon projektipohja, mutta siihen on lisätty muutama asia:

• Esimerkkilohko-lisäosa käyttäen @wordpress/create-block-työkalua.
• Esimerkkiteema, johon on lisätty JS- ja CSS-tiedostoja sekä webpack.config.js-tiedosto niiden hallintaan.
  • Teema on pelkistetty versio 2025-oletusteemasta (Twenty Twenty-Five).
• NPM workspaces määrittelee ylläolevat omiksi ”työtiloiksi” projektin juuressa olevan package.json avulla.

Esimerkkiprojektin juuresta löytyy oma readme-tiedosto, josta löytyy tarkempaa tietoa.

Miten NPM workspaces toimii?

Projektin juuressa package.json-tiedostossa määritellään projektin kaikki työtilat, esimerkiksi:

"workspaces": [
    "htdocs/wp-content/plugins/example-blocks",
    "htdocs/wp-content/themes/example-theme"
]

Ja vastaavasti sekä esimerkkilohkosta että esimerkkiteemasta löytyvät niiden omat package.json-tiedostot, joissa määritellään niiden tarvitsemat NPM-paketit ja skriptit.

Ideana on, että kaikki projektin osat (lisäosa ja teema) voisivat toimia itsenäisinä yksikköinä. Silti niitä kaikkia voidaan hallita projektin juuresta samaan aikaan.

Oleellista on määrittää name-kentän arvo lisäosan ja teeman package.json-tiedostoissa ja käyttää tätä projektin juuressa olevassa package.json-tiedostossa.

NPM-komentojen käyttö projektin juuresta

Suorittamalla komennon käyttäen -w-valitsinta on mahdollista ajaa annettu komento kyseisen työtilan kontekstissa. Esimerkiksi kun projektin juuressa ajetaan seuraava komento:

npm run build -w=example-blocks

• Tämä suorittaa build-skriptin, joka on määritelty tiedostossa ./htdocs/wp-content/plugins/example-blocks/package.json.
• Huomaa, että ”example-blocks” on oltava sama kuin name-kentän arvo yllä olevassa package.json-tiedostossa.

Vastaavasti käyttäen --workspaces-valitsinta on mahdollista ajaa annettu komento kaikissa työtiloissa. Esimerkiksi seuraava komento ajaa lint:css kaikissa työtiloissa:

npm run lint:css --workspaces

@wordpress/scripts ja sen käyttö

Esimerkkiprojektissa kaikkien työtilojen build-prosessiin on käytetty @wordpress/scripts NPM-pakettia.

Kun esimerkkilohko-lisäosa on luotu @wordpress/create-block-paketilla, niin kaikki lisäosan build-prosessiin liittyvät toimenpiteet tapahtuvat automaattisesti.

Vastaavasti teema tarvitsee oman webpack.config.js-tiedoston, jossa määritellään tarkemmin mitä JS ja CSS -tiedostoja teema pitää sisällään.

Ylikirjoitamme osan @wordpress/scripts-paketin asetuksista omilla määrityksillämme:

• Määritetään mistä löytyvät teema CSS- ja JavaScript-tiedostot (entry points).
• Lisätty webpack-remove-empty-scripts-lisäosa, jotta CSS-tiedostoihin liittyviä ylimääräisiä .js-tiedostoja ei jää jäljelle.

Tarkemmin tästä kokonaisuudesta voi lukea WordPressin kehittäjädokumentaation build process -artikkelista.

Yhteenveto

Projektipohjan tarkempi dokumentaatio löytyy readme-tiedostosta.

Tämä esimerkkiprojekti on toki vain yksi esimerkki siitä, miten WordPress-projektinsa voi organisoida, mutta toivomme, että siitä on asiakkaillemme hyötyä. Mikäli tästä herää kysymyksiä, vastaamme niihin mielellämme!