Mozaic

Important note

Using postCSS with the following configuration is mandatory for us to ensure Mozaic to work as advertised. Not following these instructions may cause Mozaic CSS to break silently either now or at some point in the future as new features and bug fixes are published.

Introduction

The Mozaic CSS source files are written in SCSS. But we compile them trough Postcss. This allows us to combine an SCSS syntax with the power of Postcss Plugins.

Mozaic provides you with an array of PostCSS plugins that you are required to use to build Mozaic files, but no task runner or compiler comes with it. That way, you are free to use your favorite one, like gulp, grunt, webpack or even npm scripts.

The Mozaic postCSS plugin list contains:

stylelint: a powerfull linter for preprocessor languages
nodeSass: compile SCSS into css
autoprefixer: automatically add browser prefixes
mqpacker on demand: a custom built media queries regrouper based on comments
postcss-base64: url encode svg in css
cssnano: optimize and minify the CSS code

A) Using a configuration file:

You can create a postcss.config.js file in your project root directory and paste the following code inside:

const pluginList = require('@mozaic-ds/css-dev-tools/postcssPluginConfig')
const scssSyntax = require('postcss-scss')

module.exports = {
  syntax: scssSyntax,
  plugins: pluginList,
}

B) with webpack

/*... your imports */
const pluginList = require('@mozaic-ds/css-dev-tools/postcssPluginConfig')
const scssSyntax = require('postcss-scss')

/*... your webpack config */
...
{
  test: /\.scss$/,
  use: [
    'style-loader',
    'css-loader',
    {
      loader: 'postcss-loader',
      options: {
        syntax: scssSyntax,
        plugins: pluginList
      }
    }
  ]
}
...

C) with gulp

var postcss = require('gulp-postcss')
var gulp = require('gulp')
const pluginList = require('@mozaic-ds/css-dev-tools/postcssPluginConfig')

gulp.task('css', () =>
  gulp
    .src('./src/*.scss')
    .pipe(postcss(pluginList))
    .pipe(gulp.dest('./dest'))
)

D) With Vue.js using Vue-CLI

You will need to use PostCSS via postcss-loader.

npm install -D postcss-loader

After installing postcss-loader, configure the file vue.config.js this way:

const pluginList = require('@mozaic-ds/css-dev-tools/postcssPluginConfig')
const scssSyntax = require('postcss-scss')

module.exports = {
  chainWebpack: config => {
    // remove the old loader
    config.module.rules.delete('css')

    // define the new one with mozaic config
    config.module
      .rule('css')
      .test(/\.scss$/)
      .use('vue-style-loader')
      .loader('postcss-loader')
      .tap(() => ({
          syntax: scssSyntax,
          plugins: pluginList,
        })
      })
  },
}

E) With Angular CLI

Using Angular CLI, you need to override the webpack configuration.
Install @angular-builders/custom-webpack:

npm i -D @angular-builders/custom-webpack

Now we need to change the builder option in the angular.json fields to the following:

{
  "architect": {
    "build": {
      "builder": "@angular-builders/custom-webpack:browser",
      "options": {
        "customWebpackConfig": {
          "path": "./webpack.config.js"
        },
        "stylePreprocessorOptions": {
          "includePaths": [
            "./node_modules/@mozaic-ds/styles/",
            "./node_modules/@mozaic-ds/styles/settings-tools/",
            "./node_modules/@mozaic-ds/styles/typography/",
            "./node_modules/@mozaic-ds/styles/layout/",
            "./node_modules/@mozaic-ds/styles/utilities/",
            "./node_modules/@mozaic-ds/styles/components/",
            "./node_modules/@mozaic-ds/tokens/build/scss/",
            "./node_modules/"
          ]
        },
        // here the rest of your configuraton...,
      }
    },
    "serve": {
      "builder": "@angular-builders/custom-webpack:dev-server",
      // here the rest of your configuraton..
    }
  }
}

You must create a new webpack.config.js file in the root directory:

With postcss-loader < 4.0.0

const pluginList = require('@mozaic-ds/css-dev-tools/postcssPluginConfig')
const scssSyntax = require('postcss-scss')

module.exports = {
  module: {
    rules: [
      {
        test: /\.scss$/,
        loader: 'postcss-loader',
        options: {
          ident: 'postcss',
          syntax: scssSyntax,
          plugins: pluginList,
        },
      },
    ],
  },
}

With postcss-loader >= 4.0.0

const pluginList = require('@mozaic-ds/css-dev-tools/postcssPluginConfig')
const scssSyntax = require('postcss-scss')

module.exports = {
  module: {
    rules: [
      {
        test: /\.scss$/,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            ident: "postcss",
            syntax: scssSyntax,
            plugins: pluginList,
          },
        },
      },
    ],
  },
};

Working with style preprocessor options

When the style preprocessor options is used to include custom paths it is not working seamlessly for now. You have to configure Mozaic to acknowledge these paths in the same way you did for Angular. Refer to the Mozaic configuration SASS options section to know-how.

Compiling for production

You need to set an environment variable to compile for production. Mozaic will deliver to you a postCSS plugin list with production features like minification and will disable development features like stylelint.

MOZAIC_ENV=production

Sass and PostCSS configuration options

Read our configuration and customization guide.

Installation