Gulp is a JavaScript-based task runner that lets you automate repetitive build steps when developing WordPress themes and plugins. With Gulp, you can compile SCSS/Sass stylesheets into CSS, bundle and minify JavaScript files, and automatically refresh your browser with Browsersync whenever you save changes to your code.
Seravo's WordPress project template includes ready-to-use package.json and gulpfile.js sample files. If preferred, you can also replace Gulp with other modern build tools such as Vite, Webpack, or @wordpress/scripts.
Step 1: Install Dependencies and Configure Theme Paths
Asset compilation and Browsersync file watching are intended to be run in your local development environment (inside the Docker container via seravo-docker ssh or directly on your workstation).
Navigate to your project root (
/data/wordpress/) and install the Node.js dependencies defined inpackage.json:cd /data/wordpress && npm install
Open
/data/wordpress/gulpfile.jsand replaceyourthemein the file paths with your active theme's directory name (for example,htdocs/wp-content/themes/your-theme/scss/*.scss).
Step 2: Start Live Development Mode (gulp watch)
Start file watching and Browsersync in your local development container:
cd /data/wordpress && npx gulp watch
Once Browsersync starts:
The local container's nginx web server automatically proxies traffic through Browsersync (port
1337).Saving
.scssfiles compiles the CSS and injects updated styles into your browser without a full page reload.Saving
.phpfiles triggers an automatic full-page reload in the browser.The Browsersync control panel is accessible at
http://browsersync.wordpress.local(port1338).
Example gulpfile.js
Below is a gulpfile.js example matching Seravo's project template, configured to compile SCSS files into CSS and watch both stylesheet and PHP files via Browsersync:
/*
* Basic boilerplate for Gulp and Browsersync in Seravo's environment.
* Update the paths below to match your theme's directory structure.
*/
const gulp = require('gulp');
const browserSync = require('browser-sync');
const sass = require('gulp-sass')(require('sass'));
const reload = browserSync.reload;
// File paths to watch and compile (replace 'your-theme' with your theme directory)
const src = {
scss: 'htdocs/wp-content/themes/your-theme/scss/*.scss',
css: 'htdocs/wp-content/themes/your-theme/css',
php: [
'htdocs/wp-content/themes/*/*.php',
'htdocs/wp-content/plugins/*/*.php',
'htdocs/wp-content/mu-plugins/*/*.php',
],
};
// Compile SCSS files into CSS
gulp.task('sass', () => {
return gulp
.src(src.scss)
.pipe(sass().on('error', sass.logError))
.pipe(gulp.dest(src.css))
.pipe(reload({ stream: true }));
});
// Start Browsersync and watch files for changes
gulp.task(
'serve',
gulp.series('sass', () => {
// Local container Nginx routes traffic to port 1337 while Browsersync is running
browserSync.init({
proxy: `https://${process.env.DEFAULT_DOMAIN}`,
open: false,
port: 1337,
ui: {
port: 1338,
},
notify: true,
});
// Enable usePolling so file changes are detected reliably across shared
// Docker volumes on macOS and Windows hosts
gulp.watch(src.scss, { usePolling: true }, gulp.series('sass'));
gulp.watch(src.php, { usePolling: true }).on('change', reload);
})
);
// Alias for the 'serve' task
gulp.task('watch', gulp.series('serve'));
// Default task: compiles assets once (used during deployments)
gulp.task('default', gulp.series('sass'));
Building Assets for Production
Running npx gulp without arguments executes the default task, compiling your assets once without leaving a watcher process running. There are two common workflows for deploying compiled assets to production:
Compile locally before deploying: Run
npx gulplocally before committing your changes and include the compiled CSS and JavaScript files in Git. This is the simplest approach for small-to-medium projects.Compile automatically during deployment: Exclude compiled assets from Git (via
.gitignore) and addnpm ci && npx gulpto your server's/data/wordpress/.git/hooks/post-receivescript so assets are built automatically after everygit push.
Note: Never commit the node_modules/ directory to Git (it is excluded by default in Seravo's .gitignore). Always commit package.json and package-lock.json so dependencies remain consistent across environments.
Common Issues and Troubleshooting
gulp: command not founderror: Gulp is installed locally insidenode_modules/.bin/rather than globally. Run commands usingnpx gulp watchornpx gulp.SCSS changes do not compile or appear on the site: Verify that you updated the theme directory path in
gulpfile.jsto match your active theme and that your theme'sfunctions.phpenqueues (wp_enqueue_style) the compiled CSS file.Saving files does not trigger compilation in the local Docker environment: Ensure
{ usePolling: true }is passed togulp.watch, as shared Docker filesystems on macOS and Windows do not always propagate native filesystem events into the container.npm installorgulp-sassfails with build errors: Check the active Node.js version withnode -vand confirm that the packages defined inpackage.jsonare compatible with your environment's Node version.
See Also
Gulp and Browsersync streamline theme development by eliminating manual compilation and browser refresh steps. If you need assistance configuring local development tools or deployment build scripts, our support team is happy to help at [email protected].
