Skip to main content

Compile Assets and Automate Tasks with Gulp

Learn how to automate WordPress theme SCSS and JavaScript compilation along with automatic browser reloads (Browsersync) using Gulp in Seravo's development environment.

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).

  1. Navigate to your project root (/data/wordpress/) and install the Node.js dependencies defined in package.json:

    cd /data/wordpress && npm install
  2. Open /data/wordpress/gulpfile.js and replace yourtheme in 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 .scss files compiles the CSS and injects updated styles into your browser without a full page reload.

  • Saving .php files triggers an automatic full-page reload in the browser.

  • The Browsersync control panel is accessible at http://browsersync.wordpress.local (port 1338).

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 gulp locally 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 add npm ci && npx gulp to your server's /data/wordpress/.git/hooks/post-receive script so assets are built automatically after every git 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 found error: Gulp is installed locally inside node_modules/.bin/ rather than globally. Run commands using npx gulp watch or npx gulp.

  • SCSS changes do not compile or appear on the site: Verify that you updated the theme directory path in gulpfile.js to match your active theme and that your theme's functions.php enqueues (wp_enqueue_style) the compiled CSS file.

  • Saving files does not trigger compilation in the local Docker environment: Ensure { usePolling: true } is passed to gulp.watch, as shared Docker filesystems on macOS and Windows do not always propagate native filesystem events into the container.

  • npm install or gulp-sass fails with build errors: Check the active Node.js version with node -v and confirm that the packages defined in package.json are 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].

Did this answer your question?