How to use SCSS/SASS in your Django project (NPM Way)

Django SCSS Tutorial Series:

1. Introduction
2. How to use SCSS/SASS in your Django project (Python Way)
3. How to use SCSS/SASS in your Django project (NPM Way)

If you want quick start, please check python-webpack-boilerplate

Objectives

After reading this article, you will get:

1. How to write SCSS/SASS using NPM for your Django project
2. How to deploy Django project which uses NPM as front-end solution

Prerequisite

First, please make sure you have installed Node in your dev env.

I recommend you to use nvm to do this, and you can find more details on NVM Github

Step 1: Directory structure and workflow

Below is our directory structure and the basic workflow:

./static_src
        ↓
  $ ./node_modules/node-sass/bin/node-sass
        ↓
./static_compiled
        ↓
  $ ./manage.py collectstatic
        ↓
./static_root

Notes:

1. The static_src includes all front-end stuff(JS, CSS, etc) of our project.
2. We can use node-sass (gulp, grunt, webpack also ok) to compile the files in static_src and put the build files in static_compiled

Then we can let our Django dev server to find static files from static_compiled. Code below should be added to our settings.py

STATICFILES_DIRS = [
    os.path.join(PROJECT_DIR, 'static_compiled'),
    ]

The final ./manage.py collectstatic would copied and compress files from static_compiled and other django package static files into the static_root directory.

Step 2: Install NPM dependencies

Please make sure you are in static_src directory, and then keep reading

First, please run npm init to create package.json

Then, please install node-sass package using npm, node-sass is a tool which can help us combine SCSS to CSS

npm install node-sass
npm install bootstrap

And then create directory sass as child of static_src

Here we put a sample main.scss to the sass directory, it has code below.

@import 'node_modules/bootstrap/scss/bootstrap';

As you can see in the main.scss, we import bootstrap, we can also add custom variables to customize our Bootstrap theme as we like.

Now our goal is to compile main.scss to main.css, then in Django template, we can only import main.css to make the theme work as expected.

Step 3: Setup NPM command

In package.json, there is a property called scripts, we can add commands to this property, and then call it using npm run

"scripts": {
  "compile:css": "node-sass -o ../static_compiled/css sass"
}

As you can see, we add a command compile:css to compile the sass to ../static_compiled/css

Now you can run npm run compile:css to check the result

> node-sass -o ../static_compiled/css sass

Rendering Complete, saving .css file...

Congratulations, you just compiled the SCSS/SASS using node-sass package.

Step 4: SCSS/SASS Auto Compile feature

It is annoying if we need to run the command above each time after we edit our SCSS files. So we need to find a way to monitor SCSS files and auto compile after they are modified.

"scripts": {
  "compile:css": "node-sass -o ../static_compiled/css sass",
  "compile:css:watch": "node-sass -o ../static_compiled/css sass --watch"
}

You can npm run compile:css:watch in a terminal (recommend Tmux here) and edit SCSS/SASS in your editor, after you change the file, new CSS files would be generated, which is convenient

Step 5: NPM config

If you check above scripts section, you will find a problem. We need to replace many times if we want to rename static_compiled.

npm config is like variable in programming, which can help us solve this problem.

"config": {
    "src_css": "sass",
    "dest_css": "../static_compiled/css",
},
"scripts": {
  "compile:css": "node-sass -o $npm_package_config_dest_css $npm_package_config_src_css",
}

You can use npm_package_config_{name} in the scripts.

Better Solution

Now you already understand how to compile SCSS with npm stack.

If you want to jump start frontend project which supports SCSS and modern JS out of the box.

Please check python-webpack-boilerplate

Django SCSS Tutorial Series:

1. Introduction
2. How to use SCSS/SASS in your Django project (Python Way)
3. How to use SCSS/SASS in your Django project (NPM Way)

If you want quick start, please check python-webpack-boilerplate