Installation

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:

postcss.config.js


const pluginList = require('@mozaic-ds/css-dev-tools/postcssPluginConfig')
const scssSyntax = require('postcss-scss')
module.exports = {
  syntax: scssSyntax,
  plugins: pluginList,
}

B) With webpack

webpack.config.js


// 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

If you are a Vue.js user, we invite you to visit our dedicated implementation of Mozaic for Vue.js.

You can find all you need on the associated Github repository: https://github.com/adeo/mozaic-vue

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

Update your angular.json file

Now you need to update the builder option in the angular.json fields to the following:

angular.json


{
  "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/components/",
            "./node_modules/@mozaic-ds/styles/generic/",
            "./node_modules/@mozaic-ds/styles/layouts/",
            "./node_modules/@mozaic-ds/styles/settings-tools/",
            "./node_modules/@mozaic-ds/styles/typography/",
            "./node_modules/@mozaic-ds/styles/utilities/",
            "./node_modules/@mozaic-ds/tokens/build/css/",
            "./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..
    }
  }
}

Implement a webpack configuration

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

webpack.config.js


module.exports = {
  module: {
    rules: [
      {
        test: /\.scss$/,
        loader: 'postcss-loader',
        options: {
          postcssOptions: {
            syntax: require('postcss-scss'),
            plugins: require('@mozaic-ds/css-dev-tools/postcssPluginConfig'),
          },
        },
      },
    ],
  },
}

F) With create-react-app

If your project is in react and you built your app with create-react-app tool, you will have to pass the path for the Mozaic sass files.

In order to do that you can edit your .env config file (or create one) at the root of your app and copy paste this inside (according to create-react-app documentation):

Using Unix filesystem:

.env


SASS_PATH=./node_modules:./node_modules/@mozaic-ds/tokens/build/scss/:./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/

Using Windows filesystem:

.env


SASS_PATH=./node_modules;./node_modules/@mozaic-ds/tokens/build/scss/;./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/

With postcss-loader < 4.0.0

postcss-loader>4

postcss-loader<4


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