Magento 2 theme blank SASS parent and child setup and installation

created July 3, 2017, last updated July 3, 2017.

.

With CE 1.9 Magento introduced the SASS stylesheet language to aid frontend development. With Magento 2.x for reasons best known to the developers they switched from SASS to LESS. At the end of the day both LESS and SASS are compiled into good old CSS but if your stylesheet language of preference is SASS or you are new to Magento and are looking for a good starting block to build a new theme from then it is well worth taking a look at SnowDogApps theme blank sass project.

The Less to Sass Community Project is officially supported by Magento and Theme Blank SASS is the result of this project – a (production ready) Magento 2 blank theme converted to SASS.

Together with the accompanying Fronttools pack you get the development tools and extendable SASS based blank theme you need to get you started building your own custom theme.

Why use theme blank SASS ?

  • If you are coming from Magento 1.9 then you already are familiar with SASS
  • Magento 2.x may possibly move to SASS in the future
  • LUMA is not designed to be extended as a blank theme
  • Essential development tools such as browsersync are included

How to install theme blank SASS parent theme and Fronttools

You can be up and running with theme blank SASS and fronttools in a few minutes. Here is a step by step theme blank sass and frontools installation guide tested on my Magento 2.x docker containers.

I am installing the parent theme and fronttools directly into my docker Magento 2 php-apache container with a bash script :

curl -o- http://gaiterjones.com/dropbox/magento2/theme-blank-sass/install-theme-blank-sass.sh | bash
 
script to install theme-blank-sass and fronttools

#!/bin/bash
# GAITERJONES
# blog.gaiterjones.com
# script to install theme-blank-sass and fronttools
# for docker service https://github.com/gaiterjones/docker-magento2
#
set -e
# variables
RED='\033[0;31m'
NC='\033[0m'

# CHANGE THIS
MAGENTO_DIR='/var/www/dev/magento2'
NVM_HOME='/var/www'

# start
printf "${RED}Installing theme-blank-sass into Magento Root: ${MAGENTO_DIR}...\n\n${NC}"
cd ${MAGENTO_DIR}
composer require snowdog/theme-blank-sass
composer require snowdog/frontools
${MAGENTO_DIR}/bin/magento setup:upgrade
${MAGENTO_DIR}/bin/magento cache:clean

printf "${RED}Installing nvm...\n${NC}"
cd /tmp
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.1/install.sh | bash
export NVM_DIR=${NVM_HOME}/.nvm
 [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
nvm install --lts
nvm use --lts
printf "${RED}Installing gulp...\n${NC}"
npm install -g gulp-cli

printf "${RED}Installing frontools...\n${NC}"
cd ${MAGENTO_DIR}/vendor/snowdog/frontools
npm install
gulp setup
curl -o "${MAGENTO_DIR}/dev/tools/frontools/config/themes.json" http://gaiterjones.com/dropbox/magento2/theme-blank-sass/browser-sync.json
curl -o "${MAGENTO_DIR}/dev/tools/frontools/config/themes.json" http://gaiterjones.com/dropbox/magento2/theme-blank-sass/themes-blank-sass-parent.json
curl -o "${MAGENTO_DIR}/vendor/snowdog/theme-blank-sass/web/images/logo.svg" http://gaiterjones.com/dropbox/magento2/theme-blank-sass/logo-theme-blank-sass.svg

printf "${RED}Generating theme-blank-sass styles...\n${NC}"
gulp styles

printf "${RED}Configuring Snowdog/blank theme.\n${NC}"
THEME_ID="$(n98-magerun2.phar dev:theme:list --format=csv \
  | grep 'Snowdog/blank' | cut -d, -f1)" \
  ; test -n "${THEME_ID}" \
  && n98-magerun2.phar config:set design/theme/theme_id "${THEME_ID}"
${MAGENTO_DIR}/bin/magento cache:clean

# done
printf "${RED}Installation complete.\n\n${NC}"

Here are the script commands broken down into some more detail :

Set the install environment variables

cd ${MAGENTO_DIR}
MAGENTO_DIR='/var/www/dev/magento2'
NVM_HOME='/var/www'

MAGENTO_DIR is the path to the magento root and NVM_HOME the path to the NVM installation home folder – this is the home folder for the user that installs NVM

Install the theme and tools with composer, upgrade Magento and refresh caches.

composer require snowdog/theme-blank-sassinstall theme blank sass
composer require snowdog/frontoolsinstall fronttools

${MAGENTO_DIR}/bin/magento setup:upgradeupdate Magento
${MAGENTO_DIR}/bin/magento cache:cleanrefresh caches

Install NVM and gulp-cli

cd /tmp
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.1/install.sh | bash
export NVM_DIR=${NVM_HOME}/.nvm
 [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
nvm install --lts
nvm use --lts
npm install -g gulp-cli

Install frontools.

cd ${MAGENTO_DIR}/vendor/snowdog/frontools
npm install

You run the fronttools setup with gulp setup, this will copy the project sample configuration files to ${MAGENTO_DIR}/dev/tools/frontools/config/.  You must edit themes.json, for the parent theme.

{
  "blank": {
    "src": "vendor/snowdog/theme-blank-sass",
    "dest": "pub/static/frontend/Snowdog/blank",
    "locale": ["en_GB"],
    "postcss": ["plugins.autoprefixer()"],
    "ignore": [".test"]
  }
}

The script is copying my themes and browser-sync json configuration files via curl.

gulp setup
curl -o "${MAGENTO_DIR}/dev/tools/frontools/config/themes.json" http://gaiterjones.com/dropbox/magento2/theme-blank-sass/browser-sync.json
curl -o "${MAGENTO_DIR}/dev/tools/frontools/config/themes.json" http://gaiterjones.com/dropbox/magento2/theme-blank-sass/themes-blank-sass-parent.json
gulp styles

Next I compile the SASS to CSS and install it using

gulp styles

Finally I am using n98-magerun2 to enable the new theme, and refresh the Magento caches.

THEME_ID="$(n98-magerun2.phar dev:theme:list --format=csv \
  | grep 'Snowdog/blank' | cut -d, -f1)" \
  ; test -n "${THEME_ID}" \
  && n98-magerun2.phar config:set design/theme/theme_id "${THEME_ID}"
${MAGENTO_DIR}/bin/magento cache:clean


Theme blank SASS parent theme is now installed. You can watch the install process below.

magento 2 theme blank sass install video

We used the gulp setup, and gulp styles tasks above – other useful tasks include

  • gulp clean
    • Removes /pub/static directory content.
  • gulp dev
    • Runs browserSync and inheritancebabelstyleswatch tasks.

See the fronttools project page for a full list of gulp tasks or use the gulp default task.

How to install a theme blank SASS child theme

Usual Magento best practice dictates that instead of editing the parent them we extend it with a child theme. You extend Snowdog/blank the same way as any other theme.

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Gaiterjones/blank</title>
    <parent>Snowdog/blank</parent>
    <media>
        <preview_image>media/preview.jpg</preview_image>
    </media>
</theme>

I tested this with my Docker environment and used the following script to extend theme blank SASS with my Gaiterjones/blank child theme.

curl -o- http://gaiterjones.com/dropbox/magento2/theme-blank-sass/child/install-child-theme-blank-sass.sh | bash

script to install theme-blank-sass child theme
#!/bin/bash
# GAITERJONES
# blog.gaiterjones.com
# script to install example theme-blank-sass child theme
#
set -e
# variables
RED='\033[0;31m'
NC='\033[0m'

# CHANGE THIS
MAGENTO_DIR='/var/www/dev/magento2'
NVM_HOME='/var/www'

# start
printf "${RED}Installing theme-blank-sass child theme into Magento Root: ${MAGENTO_DIR}...\n\n${NC}"
n98-magerun2.phar maintenance:enable
cd ${MAGENTO_DIR}/app/design/frontend
curl https://pe.terjon.es/dropbox/magento2/theme-blank-sass/child/gaiterjones-blank-child-theme-blank-sass.tar | tar x
${MAGENTO_DIR}/bin/magento setup:upgrade
cd ${MAGENTO_DIR}/vendor/snowdog/frontools


printf "${RED}Configuring Gaiterjones/blank theme.\n${NC}"
THEME_ID="$(n98-magerun2.phar dev:theme:list --format=csv \
  | grep 'Gaiterjones/blank' | cut -d, -f1)" \
  ; test -n "${THEME_ID}" \
  && n98-magerun2.phar config:set design/theme/theme_id "${THEME_ID}"

printf "${RED}Installing new themes.json config...\n${NC}"
curl -o "${MAGENTO_DIR}/dev/tools/frontools/config/themes.json" https://gaiterjones.com/dropbox/magento2/theme-blank-sass/child/themes-blank-sass-parent-child.json
printf "${RED}Generating theme-blank-sass styles...\n${NC}"
export NVM_DIR=${NVM_HOME}/.nvm
 [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
gulp styles
${MAGENTO_DIR}/bin/magento cache:clean
n98-magerun2.phar maintenance:disable
# done
printf "${RED}Installation complete.\n\n${NC}"

The script extracts the Gaiterjones/blank child theme source files to app/design/frontend/Gaiterjones/blank and updates Magento. We need to also update the fronttools themes.json config file to let fronttools know where our child theme lives

{
  "blank": {
    "src": "vendor/snowdog/theme-blank-sass",
    "dest": "pub/static/frontend/Snowdog/blank",
    "locale": ["en_GB"],
    "postcss": ["plugins.autoprefixer()"],
    "ignore": [".test"]
  },
  "gaiterjones-blank": {
    "src": "app/design/frontend/Gaiterjones/blank",
    "dest": "pub/static/frontend/Gaiterjones/blank",
    "locale": ["en_GB"],
    "localeOverwrites": true,
    "parent": "blank",
    "postcss": ["plugins.autoprefixer()"]
  }  
}

Next I am activating the theme with n98-magerun2 and then I simply need to refresh the caches and run gulp styles again to create the CSS for our child theme.

gulp styles
${MAGENTO_DIR}/bin/magento cache:clean

Fronttools compiles and installs the CSS for our child theme which is now installed and ready to view.

magento 2 theme blank sass child theme install video

You can see theme blank SASS in action on my development site.

Comments