Setup a project using Mozaic and npm scripts

In this example, in order to familiarize with Mozaic, we will set up a simple web dev environment:

• Install and configure our postcss build pipeline
• Import our first Mozaic SCSS tools and settings, and use them
• Configure stylelinnt to auto-fix our styling mistakes
• Build a live-reload dev server and use Mozaic static assets in our project

You have read the presentation tab and followed the installation steps (or you should have).

Now you should have:

• a brand new project directory
• node v18+ installed
• a package.json file with Mozaic installed (at least @mozaic-ds/css-dev-tools, @mozaic-ds/styles and @mozaic-ds/web-fonts)

I) Install and configure PostCSS

Configuring Postcss is always done by providing an array of plugins. Mozaic provides you with this array of postcss plugins, but no task runner comes with it.

That way, you are free to use your favorite one, like gulp, grunt, webpack or even npm scripts.

For this tutorial, we will use npm scripts and some npm package as a simple example.

A) Install postcss-cli:

B) Configure PostCSS:

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

C) Create some files:

Create src/ and dist/ directories.

Create a src/bundle.scss file and paste the following code:

your project should look like this now:

D) Add scripts to build and watch your CSS:

create the following npm scripts under the script keys in your package.json file.

css:build tell postcss-cli to build our SCSS and to output the compiled CSS files into the dist/ directory. We also created a css:watch command to watch our changes to the scss files.

E) Run the watcher:

Now each time you make a change, the dist/bundle.css file is updated. Postcss also creates a dist/bundle.css.map which will allow you to determine the source file and line of a declaration in the browser inspector.

Postcss is up and running!

II) It's time to write some CSS!

stylelint to lint SCSS files:

stylelint comes with its configuration in Mozaic and it is provided at compilation time. You don't necessarily need a root config file, but in some cases, you may want to have it, for example to configure prettier-stylelint on your IDE, or to use stylelint outside of the compilation pipeline.

In this case, you can create a stylelint.config.js file in the root dir of your project.

As an example, we will create an NPM script that will fix the syntax in our SCSS files.

A) Create a NPM fix command:

let's create a NPM script to fix our stylelint errors, add the following in your package.json:

If you try to run the npm run css:lint-fix command, node will throw an error because stylelint require a config file.

B) Create a stylelint config file:

Create a stylelint.config.js file at your project root.

then edit the file and add the folowing code:

Run the npm run css:lint-fix command. Nothing should happen, because the code you copied has no error.

C) Let's test that:

Edit your src/bundle.scss file, and edit line 5 to remove the line break between the mixin instantiation and the first declaration :

Run the npm run css:lint-fix again. stylelint fixed this outrageous mistake and added the line break after the mixin instantiation.

et voilà !

III) Static assets:

Mozaic provide you with static assets like fonts, icons or logos.

Depending on your environment, statics assets like icons or fonts may be served from a different URL.

let's create a live-reloading dev server as an example.

A) Copy the statics:

Let's make a script that will clean our dist/statics/ directory and copy the static assets from the Mozaic nodes_module to our project. It will allow us to be sure that we always have the last version of these static assets in our project.

Add in your package.json the following script:

B) Create a dev server:

First, let's install live-server

And create a script to launch it upon our dist/ directory. We will tell it to refresh the browser whenever there is a change in the dist directory, and also to run the statics:copy command before starting.

C) Hello Mozaic:

create an index.html file in the dist directory

paste the following inside:

now run npm run serve. A live server should open your favorite browser.

you should now see something like this:

Change 'Hello Mozaic' for 'Hello foo' in your index.html and save. Your browser should refresh automatically.

D) Use the Mozaic Fonts

When starting your server, the fonts should have been added into dist/static directory.

But as you can see, the fonts are not the Mozaic ones. Let's configure that:

open a new terminal window at your project dir and run the css wtacher

in the src/bundle.scss file add the folowing:

In the previous file, we set our path to path to font faces. It is now able to load them.

Then we set the semi-bold LeroyMerlin font-face into the body declaration.

Your browser should now look like this:

Notes

Note that you may only want to compile existing Mozaic components. In that case, you just have to create your own bundle, and import the parts you are interested in:

note that you need to follow the ITCSS/ADS import order

If you want to create your own local components:

Note that if you want to pipe your own components into the same as the Mozaic ones, the linter will ask of you to follow our guidelines.

Please read our guidelines to write CSS that follows our conventions.

If you choose not to follow our guideline, build your CSS apart from the Mozaic ones with the tool of your choice.