##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({
file: scss_filename,
success: callback
[, options..]
});
var css = sass.renderSync({
data: scss_content
[, options..]
});
Options
The API for using node-sass has changed, so that now there is only one variable - an options hash. Some of these options are optional, and in some circumstances some are mandatory.
file
file
is a String
of the path to an scss
file for libsass to render. One of this or data
options are required, for both render and renderSync.
data
data
is a String
containing the scss to be rendered by libsass. One of this or file
options are required, for both render and renderSync. It is recommended that you use the includePaths
option in conjunction with this, as otherwise libsass may have trouble finding files imported via the @import
directive.
success
success
is a Function
to be called upon successful rendering of the scss to css. This option is required but only for the render function. If provided to renderSync it will be ignored.
error
error
is a Function
to be called upon occurance of an error when rendering the scss to css. This option is optional, and only applies to the render function. If provided to renderSync it will be ignored.
includePaths
includePaths
is an Array
of path String
s to look for any @import
ed files. It is recommended that you use this option if you are using the data
option and have any @import
directives, as otherwise libsass may not find your depended-on files.
imagePath
imagePath
is a String
that represents the public image path. When using the image-url()
function in a stylesheet, this path will be prepended to the path you supply. eg. Given an imagePath
of /path/to/images
, background-image: image-url('image.png')
will compile to background-image: url("/path/to/images/image.png")
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!]
sourceComments
is a String
to determine what debug information is included in the output file. Its value should be one of 'none', 'normal', 'map'
. The default is 'none'
.
The map
option will create the source map file in your CSS destination.
[Important: souceComments
is only supported when using the file
option, and does nothing when using data
flag.]
sourceMap
If your sourceComments
option is set to map
, sourceMap
allows setting a new path context for the referenced Sass files.
The source map describes a path from your CSS file location, into the the folder where the Sass files are located. In most occasions this will work out-of-the-box but, in some cases, you may need to set a different output.
Examples
var sass = require('node-sass');
sass.render({
data: 'body{background:blue; a{color:black;}}',
success: function(css){
console.log(css)
},
error: function(error) {
console.log(error);
},
includePaths: [ 'lib/', 'mod/' ],
outputStyle: 'compressed'
});
console.log(sass.renderSync({
data: 'body{background:blue; a{color:black;}}',
outputStyle: 'compressed'
}));
Edge-case behaviours
- In the case that both
file
and data
options are set, node-sass will only attempt to honour the file
directive.
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'
, prefix: '/prefix'
}),
connect.static('/prefix', __dirname + '/public')
);
Heavily inspired by https://github.com/LearnBoost/stylus
DocPad Plugin
@jking90 wrote a DocPad plugin that compiles .scss
files using node-sass: https://github.com/jking90/docpad-plugin-nodesass
Grunt extension
@sindresorhus has created a set of grunt tasks based on node-sass: https://github.com/sindresorhus/grunt-sass
Gulp extension
@dlmanning has created a gulp sass plugin based on node-sass: https://github.com/dlmanning/gulp-sass
Harp
@sintaxi’s Harp web server implicitly compiles .scss
files using node-sass: https://github.com/sintaxi/harp
Meteor plugin
@fourseven has created a meteor plugin based on node-sass: https://github.com/fourseven/meteor-scss
Mimosa module
@dbashford has created a Mimosa module for sass which includes node-sass: https://github.com/dbashford/mimosa-sass
Example App
There is also an example connect app here: https://github.com/andrew/node-sass-example
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
git submodule init
git submodule update
npm install
npm install -g node-gyp
node-gyp rebuild
Replace the prebuild binary with your newly generated one
cp build/Release/binding.node precompiled/*your-platform*/binding.node
Command Line Interface
The interface for command-line usage is fairly simplistic at this stage, as seen in the following usage section.
Output will be saved with the same name as input SASS file into the current working directory if it's omitted.
Usage
node-sass [options] <input.scss> [<output.css>]
Options:
--output-style CSS output style (nested|expanded|compact|compressed) [default: "nested"]
--source-comments Include debug info in output (none|normal|map) [default: "none"]
--include-path Path to look for @import-ed files [default: cwd]
--help, -h Print usage info
Post-install Build
Install runs a series of Mocha tests to see if your machine can use the pre-built libsass
which will save some time during install. If any tests fail it will build from source.
If you know the pre-built version will work and do not want to wait for the tests to run you can skip the tests by setting the environment variable SKIP_NODE_SASS_TESTS
to true.
SKIP_NODE_SASS_TESTS=true npm install
Contributors
Special thanks to the following people for submitting patches:
Dean Mao
Brett Wilkins
litek
gonghao
Dylan Greene
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.