Cartridge Sass

Sass expansion pack for Cartridge

To use this module, you will need cartridge-cli installed and have a cartridge project setup.

Maintainers

Name	Github Profile
Barney Scott	bmds

Installation

This module requires node version 4.4.x at a minimum.

npm install cartridge-sass --save-dev

npm uninstall cartridge-sass --save-dev

Dependencies

This module adds the following to a project:

• Sass compilation using gulp-sass
• Source map generation using gulp-sourcemaps (local only)
• Sass import file creation using gulp-sass-generate-contents
• CSS manipulation using gulp-postcss
• Automatic CSS vender prefixes using autoprefixer
• Media query merging using css-mqpacker
• CSS minification using cssnano (--prod flag only)
• Conversion of pixels to rems using postcss-pxtorem

Config

Once installed, the config file task.sass.js is created and stored in the _config directory in the root of your cartridge project. PostCSS plugins are loaded via task.sass.js this allows you to add further plugins that may be of use to the project. General configuration is added to postCssConfig settings placed here will apply to all uses of PostCSS. Additionally file specific settings can be added to postCssTaskConfig, these should be named as per the taskConfig.files configuration section.

The following settings are configured by default:

autoprefixer

Configuration for autoprefixer is set on this property. By default we set the browsers option to browsers with more than 5% usage.

{
    autoprefixer: {
        browsers: ['>5%']
    }
}

For more options see the autoprefixer options

mqpacker

TODO: Add basic info

pxtorem

TODO: Add basic info

itcss

TODO: Add basic info

src

TODO: Add basic info

watch

TODO: Add basic info

Usage

The FrontEnd CSS guidelines are a good place to start when beginning your project

---

Development

Please follow the instructions within the base module development guide when working on this project.

Prettier

Prettier is used on this project to automatically format the JS. It is run automatically on a precommit hook. To use it manually (which you should be) run npm run prettier.

Branches

New work should be commited to the develop branch and then merged in to master once complete. Documentation changes can be performed on the master branch.

Semantic Release

In addition to the base module guide, this project uses Semantic release to manage releases to NPM. When making changes and following the required commit message format releases are managed for you.

When the commit passes tests on Travis a new version will be published based on the content of the commits since the last release. For more information please see the Semantic release project on GitHub

Gold master

The project uses gold master files to determine if the generated CSS changes after updates to the module. If you are adding new PostCSS plugins or modifying versions then expect that this could change. Verify that the new CSS is correct and then update the gold masters.

Updating Gold masters

Once you have verified that the change to the CSS is appropriate the gold masters can be updated with the following NPM scripts:

• npm run regengold:dev Generates a new gold master for the dev environment
• npm run regengold:prod Generates a new gold master for the production environment

Plato

The project has Plato configured to generate reports on the Javascript complexity of the project. You can run the report locally with npm run report. This will run Plato and open a browser tab with the generated report. If you wish to simply generate the report use npm run report-complexity.