A Sassy Oracle JET Yeoman Generator (2.0.x)

As a consumer of the Oracle JET Yeoman Generator, one thing I noticed is that generated projects do not include a Sass compilation step. Here is how I enable Sass in a "Basic" Oracle JET Yeoman project. This is meant to be more of a Getting Started guide than a definitive reference. Since the following reference uses compass the first step is to install compass. This old article from the Sass Way should help you get Sass and Compass installed. After installing Compass open a terminal and navigate to your project's root directory. Within that directory, invoke the following command:

npm install grunt-contrib-compass --save-dev

With dependencies in place, it is time to add Sass to the Oracle JET build files. First, let's create a compass.js configuration. Create a new file in scripts/grunt/config named compass.js. To this new file, add the following compass configuration. Compass has many valuable options, but this is enough to get started:

/* jshint -W097, node: true */
"use strict";

module.exports = {
  options: {
    sassDir: 'styles',
    cssDir: '.tmp/styles',
  },
  app: {
    options: {
      cssDir: 'styles'
    }
  },
  server: {
    options: {
      sourcemap: true,
      cssDir: 'styles'
    }
  }
};

I made up the "app" and "server" target names myself. Feel free to name them whatever makes sense to you (for example, serve or release, etc). If you choose different names, however, remember them because you will reference them later.

The delivered Oracle JET Grunt file contains two primary tasks: serve and build. Let's work on the `grunt serve` task first. As you probably know, the serve task launches a web server, listens for changes to web files, and then reloads the running browser app when file changes are detected. The watch step of the serve task is responsible for triggering other steps and then reloading the browser's content. Open scripts/grunt/config/watch.js and modify it as follows:

module.exports =
{
  compass: {
    files: ['styles/{,**/}*.{scss,sass}'],
    tasks: ['compass:server']
  },
  // to watch for changes in file and to perform livereload
  livereload:
  {
    files:
    [
      "css/!(libs)/**/*.css",
      "js/!(libs)/**/*.js",
      "js/{,*/}*.js",
      "css/{,*/}*.css",
      "**/*.html",
      "styles/*.scss"
    ],

    options:
    {
      livereload: "<%= oraclejet.ports.livereload %>"
    }
  }
};

Specifically, add the compass section and then add the styles/*.scss entry to the files array. This tells grunt to run compass when styles/*.scss files change.

Now we need to make the serve task aware of the new compass step. Open scripts/grunt/tasks/serve.js and add "compass:server", to the tasks array. The tasks section should now appear as follows:

  var tasks =
  [
    "compass:server",
    "connect:" + target + "Server" + (disableLiveReload ? ":keepalive" : ""),
  ];

Test it out by creating an scss file in the styles folder and then invoking grunt serve. You should see the *.css complement of your scss file appear in the styles folder.

Let's move onto the build task. Open the scripts/grunt/config.copy.js file and add the following exclusions to the release.src array: "!styles/**/*.map", "!styles/**/*.scss". Finally, open the scripts/grunt/tasks/build.js file and insert the "compass:app" step into the tasks array. You can pretty much place it anywere ahead of the "copy:release" step. I chose right before the "uglify:release" step. Test your build script by invoking grunt build:release. If all is working, you are now ready to begin Styling Custom Components with Oracle JET.

For further information, I recommend Customizing an Oracle JET Theme Using Sass and the Oracle JET Getting Started Guide.