node-sass

What is node-sass?

The node-sass npm package is a library that allows you to natively compile .scss files to CSS at incredible speed and automatically via a connect middleware. It provides a binding for Node.js to the Sass engine, which is written in C++ and allows for the translation of SCSS or SASS syntax into standard CSS that browsers can understand.

What are node-sass's main functionalities?

Compiling SCSS to CSS

This feature allows you to compile .scss files into .css files. The 'render' method takes an options object and a callback function. The options object specifies the input and output paths for the SCSS and CSS files, respectively. The callback is invoked after the compilation process, and you can handle the result or error accordingly.

const sass = require('node-sass');
sass.render({
  file: 'path/to/input.scss',
  outFile: 'path/to/output.css'
}, function(error, result) { // Node-style callback from v3.0.0 onwards
  if(!error){
    // No errors during the compilation, write this result on the disk
    fs.writeFile('path/to/output.css', result.css, function(err){
      if(!err){
        //file written on disk
      }
    });
  }
});

Watching files or directories

This feature allows you to watch .scss files or directories for changes and automatically recompile them to CSS when a change is detected. The example uses 'chokidar', an external library for watching files, to listen for changes on the specified SCSS file and then uses node-sass to compile the file to CSS.

const sass = require('node-sass');
const chokidar = require('chokidar');

chokidar.watch('path/to/input.scss').on('change', () => {
  sass.render({
    file: 'path/to/input.scss',
    outFile: 'path/to/output.css'
  }, function(error, result) {
    if (!error) {
      fs.writeFile('path/to/output.css', result.css, function(err){
        if(!err){
          console.log('SCSS file updated.');
        }
      });
    }
  });
});

Command Line Interface (CLI) usage

node-sass provides a CLI for compiling SCSS files to CSS directly from the command line. In this example, the '--output-style' option is used to specify the CSS output format (compressed in this case), '-o' is used to define the output directory for the compiled CSS, and the last argument is the input directory containing the SCSS files.

node-sass --output-style compressed -o dist/css src/scss

Other packages similar to node-sass

sass

The 'sass' package is the primary implementation of Sass, which is written in Dart. It provides the same core functionality as node-sass but does not rely on a native C++ binding, making it more portable and easier to install across different environments. It is also the package recommended by the Sass team as node-sass has been deprecated.

postcss

PostCSS is a tool for transforming CSS with JavaScript plugins. While it is not a direct replacement for node-sass, it can be used with plugins like 'precss' to provide similar SCSS-like syntax and features. PostCSS is highly extensible and can be integrated with a large number of plugins to extend its capabilities beyond what node-sass offers.

less

Less is a backward-compatible language extension for CSS. It is similar to SCSS in terms of features like variables, mixins, and nesting, but it has its own syntax and compiles to CSS using the Less compiler. While it serves a similar purpose to node-sass, it is a different preprocessor language with its own community and ecosystem.

stylus

Stylus is a preprocessor that serves as an alternative to SCSS. It offers a flexible syntax with optional colons, semicolons, and braces, and provides powerful features like variable interpolation and functions. Stylus can be seen as a more expressive, but less widely adopted, alternative to node-sass.

README

##node-sass

Node-sass is a library that provides binding for Node.js to libsass, the C version of the popular stylesheet preprocessor, Sass.

It allows you to natively compile .scss files to css at incredible speed and automatically via a connect middleware.

Find it on npm: https://npmjs.org/package/node-sass

Install

npm install node-sass

Usage

var sass = require('node-sass');
sass.render(scss_content, callback [, options]);
// OR
var css = sass.renderSync(scss_content [, options]);

Options

The options argument is optional, though it's use is recommended. It support two attributes: includePaths and outputStyle.

includePaths

includePaths is an Array of path Strings to look for any @imported files. It is recommended that you use this option if you have any @import directives, as otherwise libsass may not find your depended-on files.

outputStyle

outputStyle is a String to determine how the final CSS should be rendered. Its value should be one of 'nested', 'expanded', 'compact', 'compressed'. [Important: currently the argument outputStyle has some problem which may cause the output css becomes nothing because of the libsass, so you should not use it now!]

Examples

var sass = require('node-sass');
sass.render('body{background:blue; a{color:black;}}', function(err, css){
  console.log(css)
}/*, { includePaths: [ 'lib/', 'mod/' ], outputStyle: 'compressed' }*/);
// OR
console.log(sass.renderSync('body{background:blue; a{color:black;}}')/*, { includePaths: [ 'lib/', 'mod/' ], outputStyle: 'compressed' }*/);

Connect/Express middleware

Recompile .scss files automatically for connect and express based http servers

var server = connect.createServer(
  sass.middleware({
      src: __dirname
    , dest: __dirname + '/public'
    , debug: true
    , outputStyle: 'compressed'
  }),
  connect.static(__dirname + '/public')
);

Heavily inspired by https://github.com/LearnBoost/stylus

Rebuilding binaries

Node-sass includes pre-compiled binaries for popular platforms, to add a binary for your platform follow these steps:

Check out the project:

git clone https://github.com/andrew/node-sass.git
cd node-sass
npm install
npm install -g node-gyp
git submodule init
git submodule update
node-gyp rebuild

Replace the prebuild binary with your newly generated one

cp build/Release/binding.node precompiled/*your-platform*/binding.node

Contributors

Special thanks to the following people for submitting patches:

Dean Mao Brett Wilkins litek gonghao

Note on Patches/Pull Requests

• Fork the project.
• Make your feature addition or bug fix.
• Add documentation if necessary.
• Add tests for it. This is important so I don't break it in a future version unintentionally.
• Send a pull request. Bonus points for topic branches.

Copyright

Copyright (c) 2013 Andrew Nesbitt. See LICENSE for details.