Starter Project - Gulp tasks for CSS

This article is part of a series about Starter Project, and this time I will explain all about Gulp tasks for CSS.

Settings

The idea of Starter Project is to have a single config file for all Gulp tasks. If you open config.json file, you could see a section for CSS.

"css": {
  "run": true,
  "src": "src/scss/",
  "dest": "css/",
  "clean": "css/",
  "styleLintConfig": {
    "reporters": [
      {
        "formatter": "string",
        "console": true
      }
    ]，
    "sassConfig": {
      "includePaths": [
        "./node_modules/modularscale-sass/stylesheets/",
        "./node_modules/sass-mq/",
        "./node_modules/normalize.css/",
        "./src/scss/",
        "./src/scss/components"
      ]
    },
    "autoprefixedConfig": {
      "browsers": ["last 5 versions"],
      "cascade": false
    },
  },
  "renameConfig": {
    "suffix": ".min"
    "sourcemapsConfig": {
      "run": true
    }
  }
}

The first option is run. If set to true, CSS Gulp tasks will be executed. There are three other mandatory options for CSS:

• src - a path to a folder with Sass files,
• dest - a path to a folder where compiled CSS files will be saved, and
• clean - a path to a folder which will be cleaned before Gulp execution (almost always the same as dest option).

Other options are for gulp-cssimport, gulp-autoprefixer, gulp-rename, and gulp-sourcemaps.

Sass

Starter Project uses Sass as a preprocessor for CSS. As it's official website says, Sass is "CSS with superpowers." A significant number of developers are supporters and users of this robust program. It has useful features like variables, functions, and mixins.

Starter Project uses gulp-sass plugin for compiling Sass to CSS.

Imports

gulp-cssimport is a plugin that allows import of linked files by including content to CSS file. This means you cannot use native CSS @import implementation, but it is considered a bad practice in most cases anyway.

To use this plugin, add @import statement in Sass file.

// Plugins
@import 'normalize';
@import 'mq';

// Configuration
@import 'variables';
@import 'fonts';
@import 'locks';
@import 'helpers';
@import 'typography';
@import 'theme';

You could add includePaths option to the sassConfig settings to avoid writing full paths of the included libraries.

"sassConfig": {
  "includePaths": [
     "./node_modules/modularscale-sass/stylesheets/",
     "./node_modules/sass-mq/",
     "./node_modules/normalize.css/",
     "./src/scss/",
     "./src/scss/components"
  ]
},

Sass libraries

Starter Project has three libraries imported:

• Normalize.css,

• Modular Scale, and

• Media Queries.

@import 'normalize';
@import 'mq';

If your website looks inconsistent across different browsers, you probably want to use CSS technique to reset browser behavior. In Starter Project, Normalize.css is used for this task.

“Normalize.css makes browsers render all elements more consistently and in line with modern standards. It precisely targets only the styles that need normalizing.”

— Nicolas Gallagher

Modular Scale helps with font size consistency. modularscale-sass is a list of values that are used to size type and create a sense of harmony in design.

sass-mq is a Sass mixin that helps a developer in composing media queries in an elegant way.

Autoprefix

Starter Project uses gulp-autoprefixer plugin to add vendor prefixes to CSS files. This plugin is handy as developers don't have to add these prefixes manually. In config.json, you could add Autoprefixer options to autoprefixedConfig settings.

"autoprefixedConfig": {
    "browsers": ["last 5 versions"],
    "cascade": false
},

Source maps

Source maps allow developers to see the source code for compressed assets. In Starter Project, gulp-sourcemaps plugin is used to create source maps for CSS and JavaScript files. If your environment doesn't require source maps, you could disable it by setting run option to false in sourcemapsConfig.

"sourcemapsConfig": {
  "run": true
}

Minifying

gulp-clean-css is a Gulp plugin that acts as a wrapper for clean-css. In Starter Project, this plugin is used for CSS minification. To create less confusion with file names, gulp-rename plugin is used to rename minified assets by adding prefix or suffix to the file name.

"renameConfig": {
  "suffix": ".min"
}

Linting

“Linting is the process of running a program that will analyze code for potential errors.”

— Source: StackOverflow

In Starter Project, gulp-stylelint plugin is used to lint CSS files. You could configure the plugin in config.json file.

"styleLintConfig": {
  "reporters": [{
    "formatter": "string",
    "console": true
  }]
},

Default settings output error in a console as a string. See all available settings here.

Stylelint options are stored in .stylelintrc file.

{
  "plugins": [
    "stylelint-scss",
    "stylelint-order"
  ],
  "extends": "stylelint-config-sass-guidelines"
}

Stylelint also has its plugins. In Starter Project, stylelint-scss and stylelint-order plugins are used. Also, there are Stylelint Sass Guidelines that are used to extend default Stylelint settings. Learn more about Stylelint on the official website.

Bonus

For all the VS Code users, here is the tip how to use Stylelint inside the editor. First, install stylefmt and Run On Save extensions for VS Code. Then call command palette by pressing cmd + shift + p, and type open workspace settings.

When you open the workspace settings, add these settings.

{
  "emeraldwalk.runonsave": {
    "commands": [{
      "match": "\\.scss?$",
      "cmd": "cd ${workspaceRoot} && stylefmt -c .stylelintrc ${file}"
    }]
  }
}

This should run stylelint when you save .scss files. If it doesn't work, contact me for help.

Conclusion

In the previous article, I was trying to explain the idea for this project. This article should help you understand how Gulp could be used to optimize, lint and deliver best possible CSS output.

Starter Project is conceived as a boilerplate with the latest best practices for generating the best possible outcome. If you have any idea or suggestion how this project could be better and more interesting, please contact me, open an issue, or create a pull request on GitHub.