Siirry pääsisältöön

Kokoa resursseja ja automatisoi Gulp-työkalulla

Opi automatisoimaan WordPress-teeman SCSS- ja JavaScript-tiedostojen kääntäminen sekä selaimen automaattinen päivitys (Browsersync) Gulp-työkalulla Seravon kehitysympäristössä.

Gulp on JavaScript-pohjainen tehtäväautomaatiotyökalu (task runner), jonka avulla voit automatisoida WordPress-teeman ja lisäosien kehitysvaiheita. Gulpin avulla voit esimerkiksi kääntää SCSS/Sass-tyylitiedostot CSS-muotoon, yhdistää ja minimoida JavaScript-tiedostoja sekä päivittää selaimen automaattisesti Browsersync-työkalun avulla aina, kun tallennat muutoksia koodiin.

Seravon WordPress-projektipohja sisältää valmiit package.json- ja gulpfile.js-mallitiedostot. Halutessasi voit kuitenkin korvata Gulpin myös muilla moderneilla työkaluilla, kuten Vite, Webpack tai @wordpress/scripts.

Vaihe 1: Asenna riippuvuudet ja määritä teeman polut

Resurssien kääntäminen ja Browsersync-tarkkailu on tarkoitettu käytettäväksi paikallisessa kehitysympäristössä (Docker-kontin sisällä seravo-docker ssh tai omalla työasemallasi).

  1. Siirry projektin juurihakemistoon (/data/wordpress/) ja asenna package.json-tiedostossa määritellyt Node.js-riippuvuudet:

    cd /data/wordpress && npm install
  2. Avaa tiedosto /data/wordpress/gulpfile.js ja korvaa polkujen yourtheme-kohta oman aktiivisen teemasi hakemistonimellä (esimerkiksi htdocs/wp-content/themes/oma-teema/scss/*.scss).

Vaihe 2: Käynnistä reaaliaikainen kehitystila (gulp watch)

Käynnistä tiedostojen tarkkailu ja Browsersync paikallisessa kehityskontissa:

cd /data/wordpress && npx gulp watch

Kun Browsersync käynnistyy:

  • Paikallisen kehitysympäristön nginx-palvelin ohjaa liikenteen automaattisesti Browsersyncin (portti 1337) kautta.

  • .scss-tiedostojen tallennus kääntää CSS-tiedostot ja päivittää tyylit selaimeen ilman sivun uudelleenlatausta.

  • .php-tiedostojen tallennus lataa sivun uudelleen selaimessa automaattisesti.

  • Browsersyncin hallintapaneeli on käytettävissä osoitteessa http://browsersync.wordpress.local (portti 1338).

Esimerkki gulpfile.js-tiedostosta

Alla on Seravon mallipohjaa vastaava gulpfile.js-esimerkki, joka kääntää SCSS-tiedostot CSS-muotoon ja tarkkailee sekä tyyli- että PHP-tiedostoja Browsersyncin avulla:

/*
* Perusrunko Gulp- ja Browsersync-määrityksille Seravon ympäristössä.
* Muokkaa polut vastaamaan oman teemasi hakemistorakennetta.
*/

const gulp = require('gulp');
const browserSync = require('browser-sync');
const sass = require('gulp-sass')(require('sass'));
const reload = browserSync.reload;

// Tarkkailtavat ja käännettävät tiedostopolut (vaihda 'oma-teema' teemasi nimeen)
const src = {
scss: 'htdocs/wp-content/themes/oma-teema/scss/*.scss',
css: 'htdocs/wp-content/themes/oma-teema/css',
php: [
'htdocs/wp-content/themes/*/*.php',
'htdocs/wp-content/plugins/*/*.php',
'htdocs/wp-content/mu-plugins/*/*.php',
],
};

// Käännä SCSS-tiedostot CSS-muotoon
gulp.task('sass', () => {
return gulp
.src(src.scss)
.pipe(sass().on('error', sass.logError))
.pipe(gulp.dest(src.css))
.pipe(reload({ stream: true }));
});

// Käynnistä Browsersync ja tiedostojen tarkkailu
gulp.task(
'serve',
gulp.series('sass', () => {
// Paikallisen kontin Nginx ohjaa liikenteen porttiin 1337, kun palvelu on käynnissä
browserSync.init({
proxy: `https://${process.env.DEFAULT_DOMAIN}`,
open: false,
port: 1337,
ui: {
port: 1338,
},
notify: true,
});

// Käytetään usePolling-asetusta, jotta tiedostomuutokset tunnistuvat luotettavasti
// Dockerin ja työaseman jaettujen kansioiden välillä
gulp.watch(src.scss, { usePolling: true }, gulp.series('sass'));
gulp.watch(src.php, { usePolling: true }).on('change', reload);
})
);

// Alias 'watch'-komennolle
gulp.task('watch', gulp.series('serve'));

// Oletustehtävä: kääntää resurssit kertaalleen (käytetään julkaisun yhteydessä)
gulp.task('default', gulp.series('sass'));

Resurssien kääntäminen tuotantoa varten

Kun ajat npx gulp ilman parametreja, Gulp suorittaa default-tehtävän ja kääntää resurssit kertaalleen ilman taustalle jäävää tarkkailua. Käännettyjen tiedostojen viemiseen tuotantoon on kaksi yleistä tapaa:

  • Käännös paikallisesti ennen julkaisua: Aja npx gulp paikallisesti ennen muutosten tallentamista ja lisää käännetyt CSS- ja JavaScript-tiedostot suoraan Git-versionhallintaan. Tämä on yksinkertaisin tapa pienissä ja keskisuurissa projekteissa.

  • Automaattinen käännös julkaisun yhteydessä: Pidä käännetyt tiedostot poissa Gitistä (.gitignore) ja lisää npm ci && npx gulp palvelimen /data/wordpress/.git/hooks/post-receive-skriptiin, jolloin paketit asentuvat nopeasti ja tarkasti package-lock.json-tiedoston mukaisesti ja resurssit kääntyvät automaattisesti jokaisen git push -julkaisun jälkeen.

Huom: Älä koskaan tallenna node_modules/-hakemistoa Git-versionhallintaan (se on estetty oletuksena Seravon .gitignore-tiedostossa). Pidä kuitenkin package.json ja package-lock.json mukana versionhallinnassa, jotta riippuvuudet pysyvät yhtenäisinä kaikissa ympäristöissä.

Yleisimmät virhetilanteet

  • gulp: command not found -virheilmoitus: Gulp asennetaan projektikohtaisesti kansioon node_modules/.bin/, ei välttämättä järjestelmän laajuiseksi komennoksi. Aja komento muodossa npx gulp watch tai npx gulp.

  • SCSS-muutokset eivät käänny tai näy sivustolla: Varmista, että olet vaihtanut gulpfile.js-tiedostossa olevan teemapolun vastaamaan oman teemasi kansiota ja että teemasi functions.php lataa (wp_enqueue_style) käännetyn CSS-tiedoston.

  • Tiedostojen tallennus ei käynnistä käännöstä paikallisessa Docker-ympäristössä: Varmista, että gulp.watch-kutsuissa on mukana asetus { usePolling: true }, sillä Dockerin ja macOS/Windows-työasemien väliset jaetut tiedostojärjestelmät eivät aina välitä natiiveja tiedostotapahtumia kontin sisälle.

  • npm install tai gulp-sass epäonnistuu virheeseen: Tarkista käytössä oleva Node.js-versio komennolla node -v ja varmista, että package.json-tiedoston paketit ovat yhteensopivia ympäristön Node-version kanssa.

Katso myös

Gulp ja Browsersync nopeuttavat teemakehitystä poistamalla manuaaliset käännös- ja päivitysvaiheet. Mikäli tarvitset apua paikallisen kehitysympäristön työkaluissa tai julkaisuskriptien määrittämisessä, asiakaspalvelumme auttaa osoitteessa [email protected].

Vastasiko tämä kysymykseesi?