Using Gulp Sass in MODX Cloud

Gulp is a toolkit for automating tedious or time-consuming tasks in your development workflow, so you can stop messing around and build something – the Gulp website

One of the common use cases in web development is to use Gulp for working with Sass and automating the tedious aspects, like creating vendor prefixes for certain CSS styles. The beginner intro to Sass helps explain what Sass is, and the basics of how to use it.

There are two essential tools commonly used to get started with Gulp Sass:

  • gulp-sass for basic Sass compilation via LibSass, including built-in support for sourcemaps
  • gulp-autoprefixer to automate the tedious process of writing vendor prefixes for the CSS rules in a post-processing step

You can do much more with Gulp than just compile Sass. For a more complete guide to a Gulp Sass workflow, including production vs development CSS and Sass documentation, see Finally, to learn more about Gulp and its numerous plugins in general, visit

Set up Gulp in MODX Cloud

To use gulp and gulp plugins you need to install and configure gulp-cli inside the home directory of a MODX Cloud instance. Log into your instance via SSH and execute the following command:

$ npm install --global gulpjs/gulp-cli

After gulp-cli has been installed, create and switch to the project directory. In this example, we'll install the sass files into a sass/ directory located inside the public webroot:

$ mkdir -p www/assets/styles/sass; cd www/assets/styles/sass

You can build your gulp package wherever you would like, for the following example, we will set it up in the site's root directory.

$ cd ~/www/

Initialize npm inside the project directory to create a package.json file by running the  following command and answering the instructions in the utility outputs.

$ npm init

Install Gulp using the following command in your shell:

$ npm install gulpjs/gulp --save-dev

Set up Gulp-based Sass tools in MODX Cloud

To install gulp-sass and gulp-autoprefixer, execute the following commands from your shell:

$ npm install gulp-sass gulp-autoprefixer --save-dev

Inside the project directory, create a gulpfile.js file to include all the plugins you would need for your project:

$ nano gulpfile.js

In the example below, it assumes your sass files end in ".sass" and are located in the <webroot>/assets/styles/sass/ directory, and your desired output is to the <webroot>/assets/styles/css/ directory.  To set up your gulp, project add the following lines to your gulpfile.js:

const gulp = require("gulp");
const sass = require("gulp-sass");
const autoprefixer = require("gulp-autoprefixer");
const paths = {
styles: {
src: "./assets/styles/sass/**/*.scss",
dest: "./assets/styles/css"

gulp.task("css", function() {
return gulp
.src(paths.styles.src, { sourcemaps: true })
errLogToConsole: true,
outputStyle: 'compressed'
.on("error", sass.logError)
.pipe(gulp.dest(paths.styles.dest, { sourcemaps: '.' }));

gulp.task("watch", function() {, gulp.series("css"));

gulp.task("default", gulp.series("css"));

Using Gulp Sass

You must be SSH'd into your instance in order to work with Gulp Sass. The configuration above provides you two important commands that you'll want to use whenever you add a new *.sass file or save an existing one:

  • gulp or gulp css when executed from the webroot will recompile the Sass, outputting any errors, created sourcemaps, and write compiled CSS files to your assets/styles/css/ directory.
  • gulp watch from the web root will tell node.js to recompile the Sass every time you change or upload new Sass files as long as you stay logged into a live SSH session.




Have more questions? Submit a request


Please sign in to leave a comment.