3 #### Supported Node.js versions 0.10, 0.12, 1, 2, 3, 4, 5, 6 and 7.
8 <img width="77px" alt="Sass logo" src="https://rawgit.com/sass/node-sass/master/media/logo.svg" />
10 <td valign="bottom" align="right">
11 <a href="https://www.npmjs.com/package/node-sass">
12 <img width="100%" src="https://nodei.co/npm/node-sass.png?downloads=true&downloadRank=true&stars=true">
18 [![Build Status](https://travis-ci.org/sass/node-sass.svg?branch=master&style=flat)](https://travis-ci.org/sass/node-sass)
19 [![Build status](https://ci.appveyor.com/api/projects/status/22mjbk59kvd55m9y/branch/master)](https://ci.appveyor.com/project/sass/node-sass/branch/master)
20 [![npm version](https://badge.fury.io/js/node-sass.svg)](http://badge.fury.io/js/node-sass)
21 [![Dependency Status](https://david-dm.org/sass/node-sass.svg?theme=shields.io)](https://david-dm.org/sass/node-sass)
22 [![devDependency Status](https://david-dm.org/sass/node-sass/dev-status.svg?theme=shields.io)](https://david-dm.org/sass/node-sass#info=devDependencies)
23 [![Coverage Status](https://coveralls.io/repos/sass/node-sass/badge.svg?branch=master)](https://coveralls.io/r/sass/node-sass?branch=master)
24 [![Inline docs](http://inch-ci.org/github/sass/node-sass.svg?branch=master)](http://inch-ci.org/github/sass/node-sass)
25 [![Join us in Slakc](https://libsass-slack.herokuapp.com/badge.svg)](https://libsass-slack.herokuapp.com/)
27 Node-sass is a library that provides binding for Node.js to [LibSass], the C version of the popular stylesheet preprocessor, Sass.
29 It allows you to natively compile .scss files to css at incredible speed and automatically via a connect middleware.
31 Find it on npm: <https://www.npmjs.com/package/node-sass>
33 Follow @nodesass on twitter for release updates: https://twitter.com/nodesass
41 Some users have reported issues installing on Ubuntu due to `node` being registered to another package. [Follow the official NodeJS docs](https://github.com/nodejs/node-v0.x-archive/wiki/Installing-Node.js-via-package-manager) to install NodeJS so that `#!/usr/bin/env node` correctly resolved.
43 Compiling versions 0.9.4 and above on Windows machines requires [Visual Studio 2013 WD](https://www.visualstudio.com/downloads/download-visual-studio-vs#d-express-windows-desktop). If you have multiple VS versions, use ```npm install``` with the ```--msvs_version=2013``` flag also use this flag when rebuilding the module with node-gyp or nw-gyp.
45 **Having installation troubles? Check out our [Troubleshooting guide](/TROUBLESHOOTING.md).**
50 var sass = require('node-sass');
54 }, function(err, result) { /*...*/ });
56 var result = sass.renderSync({
66 **Special**: `file` or `data` must be specified
68 Path to a file for [LibSass] to render.
73 **Special**: `file` or `data` must be specified
75 A string to pass to [LibSass] to render. It is recommended that you use `includePaths` in conjunction with this so that [LibSass] can find files when using the `@import` directive.
77 ### importer (>= v2.0.0) - _experimental_
79 **This is an experimental LibSass feature. Use with caution.**
81 Type: `Function | Function[]` signature `function(url, prev, done)`
84 Function Parameters and Information:
85 * `url (String)` - the path in import **as-is**, which [LibSass] encountered
86 * `prev (String)` - the previously resolved path
87 * `done (Function)` - a callback function to invoke on async completion, takes an object literal containing
88 * `file (String)` - an alternate path for [LibSass] to use **OR**
89 * `contents (String)` - the imported contents (for example, read from memory or the file system)
91 Handles when [LibSass] encounters the `@import` directive. A custom importer allows extension of the [LibSass] engine in both a synchronous and asynchronous manner. In both cases, the goal is to either `return` or call `done()` with an object literal. Depending on the value of the object literal, one of two things will happen.
93 When returning or calling `done()` with `{ file: "String" }`, the new file path will be assumed for the `@import`. It's recommended to be mindful of the value of `prev` in instances where relative path resolution may be required.
95 When returning or calling `done()` with `{ contents: "String" }`, the string value will be used as if the file was read in through an external source.
99 * `this` refers to a contextual scope for the immediate run of `sass.render` or `sass.renderSync`
101 * importers can return error and LibSass will emit that error in response. For instance:
104 done(new Error('doesn\'t exist!'));
105 // or return synchornously
106 return new Error('nothing to do here');
109 * importer can be an array of functions, which will be called by LibSass in the order of their occurrence in array. This helps user specify special importer for particular kind of path (filesystem, http). If an importer does not want to handle a particular path, it should return `null`. See [functions section](#functions--v300) for more details on Sass types.
111 ### functions (>= v3.0.0) - _experimental_
113 **This is an experimental LibSass feature. Use with caution.**
115 `functions` is an `Object` that holds a collection of custom functions that may be invoked by the sass files being compiled. They may take zero or more input parameters and must return a value either synchronously (`return ...;`) or asynchronously (`done();`). Those parameters will be instances of one of the constructors contained in the `require('node-sass').types` hash. The return value must be of one of these types as well. See the list of available types below:
117 #### types.Number(value [, unit = ""])
118 * `getValue()`/ `setValue(value)` : gets / sets the numerical portion of the number
119 * `getUnit()` / `setUnit(unit)` : gets / sets the unit portion of the number
121 #### types.String(value)
122 * `getValue()` / `setValue(value)` : gets / sets the enclosed string
124 #### types.Color(r, g, b [, a = 1.0]) or types.Color(argb)
125 * `getR()` / `setR(value)` : red component (integer from `0` to `255`)
126 * `getG()` / `setG(value)` : green component (integer from `0` to `255`)
127 * `getB()` / `setB(value)` : blue component (integer from `0` to `255`)
128 * `getA()` / `setA(value)` : alpha component (number from `0` to `1.0`)
133 var Color = require('node-sass').types.Color,
134 c1 = new Color(255, 0, 0),
135 c2 = new Color(0xff0088cc);
138 #### types.Boolean(value)
139 * `getValue()` : gets the enclosed boolean
140 * `types.Boolean.TRUE` : Singleton instance of `types.Boolean` that holds "true"
141 * `types.Boolean.FALSE` : Singleton instance of `types.Boolean` that holds "false"
143 #### types.List(length [, commaSeparator = true])
144 * `getValue(index)` / `setValue(index, value)` : `value` must itself be an instance of one of the constructors in `sass.types`.
145 * `getSeparator()` / `setSeparator(isComma)` : whether to use commas as a separator
148 #### types.Map(length)
149 * `getKey(index)` / `setKey(index, value)`
150 * `getValue(index)` / `setValue(index, value)`
154 * `types.Null.NULL` : Singleton instance of `types.Null`.
160 data: '#{headings(2,5)} { color: #08c; }',
162 'headings($from: 0, $to: 6)': function(from, to) {
163 var i, f = from.getValue(), t = to.getValue(),
164 list = new sass.types.List(t - f + 1);
166 for (i = f; i <= t; i++) {
167 list.setValue(i - f, new sass.types.String('h' + i));
177 Type: `Array<String>`
180 An array of paths that [LibSass] can look in to attempt to resolve your `@import` declarations. When using `data`, it is recommended that you use this.
186 `true` values enable [Sass Indented Syntax](http://sass-lang.com/documentation/file.INDENTED_SYNTAX.html) for parsing the data string or file.
188 __Note:__ node-sass/libsass will compile a mixed library of scss and indented syntax (.sass) files with the Default setting (false) as long as .sass and .scss extensions are used in filenames.
190 ### indentType (>= v3.0.0)
194 Used to determine whether to use space or tab character for indentation.
196 ### indentWidth (>= v3.0.0)
201 Used to determine the number of spaces or tabs to be used for indentation.
203 ### linefeed (>= v3.0.0)
207 Used to determine whether to use `cr`, `crlf`, `lf` or `lfcr` sequence for line break.
212 **Special:** When using this, you should also specify `outFile` to avoid unexpected behavior.
214 `true` values disable the inclusion of source map information in the output file.
217 Type: `String | null`
219 **Special:** Required when `sourceMap` is a truthy value
221 Specify the intended location of the output file. Strongly recommended when outputting source maps so that they can properly refer back to their intended files.
223 **Attention** enabling this option will **not** write the file on disk for you, it's for internal reference purpose only (to generate the map for example).
225 Example on how to write it on the disk
229 outFile: yourPathTotheFile,
230 }, function(error, result) { // node-style callback from v3.0.0 onwards
232 // No errors during the compilation, write this result on the disk
233 fs.writeFile(yourPathTotheFile, result.css, function(err){
235 //file written on disk
246 Values: `nested`, `expanded`, `compact`, `compressed`
248 Determines the output format of the final CSS style.
254 Used to determine how many digits after the decimal will be allowed. For instance, if you had a decimal number of `1.23456789` and a precision of `5`, the result will be `1.23457` in the final CSS.
260 `true` Enables the line number and file where a selector is defined to be emitted into the compiled CSS as a comment. Useful for debugging, especially when using imports and mixins.
263 Type: `Boolean | String | undefined`
265 **Special:** Setting the `sourceMap` option requires also setting the `outFile` option
267 Enables the outputting of a source map during `render` and `renderSync`. When `sourceMap === true`, the value of `outFile` is used as the target output location for the source map. When `typeof sourceMap === "string"`, the value of `sourceMap` will be used as the writing location for the file.
269 ### sourceMapContents
273 `true` includes the `contents` in the source map information
279 `true` embeds the source map as a data URI
285 the value will be emitted as `sourceRoot` in the source map information
287 ## `render` Callback (>= v3.0.0)
288 node-sass supports standard node style asynchronous callbacks with the signature of `function(err, result)`. In error conditions, the `error` argument is populated with the error object. In success conditions, the `result` object is populated with an object describing the result of the render call.
291 * `message` (String) - The error message.
292 * `line` (Number) - The line number of error.
293 * `column` (Number) - The column number of error.
294 * `status` (Number) - The status code.
295 * `file` (String) - The filename of error. In case `file` option was not set (in favour of `data`), this will reflect the value `stdin`.
298 * `css` (Buffer) - The compiled CSS. Write this to a file, or serve it out as needed.
299 * `map` (Buffer) - The source map
300 * `stats` (Object) - An object containing information about the compile. It contains the following keys:
301 * `entry` (String) - The path to the scss file, or `data` if the source was not a file
302 * `start` (Number) - Date.now() before the compilation
303 * `end` (Number) - Date.now() after the compilation
304 * `duration` (Number) - *end* - *start*
305 * `includedFiles` (Array) - Absolute paths to all related scss files in no particular order.
310 var sass = require('node-sass');
312 file: '/path/to/myFile.scss',
313 data: 'body{background:blue; a{color:black;}}',
314 importer: function(url, prev, done) {
315 // url is the path in import as is, which LibSass encountered.
316 // prev is the previously resolved path.
317 // done is an optional callback, either consume it or return value synchronously.
318 // this.options contains this options hash, this.callback contains the node-style callback
319 someAsyncFunction(url, prev, function(result){
321 file: result.path, // only one of them is required, see section Special Behaviours.
322 contents: result.data
326 var result = someSyncFunction(url, prev);
327 return {file: result.path, contents: result.data};
329 includePaths: [ 'lib/', 'mod/' ],
330 outputStyle: 'compressed'
331 }, function(error, result) { // node-style callback from v3.0.0 onwards
333 console.log(error.status); // used to be "code" in v2x and below
334 console.log(error.column);
335 console.log(error.message);
336 console.log(error.line);
339 console.log(result.css.toString());
341 console.log(result.stats);
343 console.log(result.map.toString());
345 console.log(JSON.stringify(result.map)); // note, JSON.stringify accepts Buffer too
349 var result = sass.renderSync({
350 file: '/path/to/file.scss',
351 data: 'body{background:blue; a{color:black;}}',
352 outputStyle: 'compressed',
353 outFile: '/to/my/output.css',
354 sourceMap: true, // or an absolute or relative (to outFile) path
355 importer: function(url, prev, done) {
356 // url is the path in import as is, which LibSass encountered.
357 // prev is the previously resolved path.
358 // done is an optional callback, either consume it or return value synchronously.
359 // this.options contains this options hash
360 someAsyncFunction(url, prev, function(result){
362 file: result.path, // only one of them is required, see section Sepcial Behaviours.
363 contents: result.data
367 var result = someSyncFunction(url, prev);
368 return {file: result.path, contents: result.data};
372 console.log(result.css);
373 console.log(result.map);
374 console.log(result.stats);
377 ### Special behaviours
379 * In the case that both `file` and `data` options are set, node-sass will give precedence to `data` and use `file` to calculate paths in sourcemaps.
381 ### Version information (>= v2.0.0)
383 Both `node-sass` and `libsass` version info is now exposed via the `info` method:
386 var sass = require('node-sass');
388 console.log(sass.info);
391 it will output something like:
393 node-sass 2.0.1 (Wrapper) [JavaScript]
394 libsass 3.1.0 (Sass Compiler) [C/C++]
398 Since node-sass >=v3.0.0 LibSass version is determined at run time.
402 Listing of community uses of node-sass in build tools and frameworks.
404 ### Brackets extension
406 [@jasonsanjose](https://github.com/jasonsanjose) has created a [Brackets](http://brackets.io) extension based on node-sass: <https://github.com/jasonsanjose/brackets-sass>. When editing Sass files, the extension compiles changes on save. The extension also integrates with Live Preview to show Sass changes in the browser without saving or compiling.
410 [Brunch](http://brunch.io)'s official sass plugin uses node-sass by default, and automatically falls back to ruby if use of Compass is detected: <https://github.com/brunch/sass-brunch>
412 ### Connect/Express middleware
414 Recompile `.scss` files automatically for connect and express based http servers.
416 This functionality has been moved to [`node-sass-middleware`](https://github.com/sass/node-sass-middleware) in node-sass v1.0.0
420 [@jking90](https://github.com/jking90) wrote a [DocPad](http://docpad.org/) plugin that compiles `.scss` files using node-sass: <https://github.com/jking90/docpad-plugin-nodesass>
424 [@stephenway](https://github.com/stephenway) has created an extension that transpiles Sass to CSS using node-sass with [duo.js](http://duojs.org/)
425 <https://github.com/duojs/sass>
429 [@sindresorhus](https://github.com/sindresorhus/) has created a set of grunt tasks based on node-sass: <https://github.com/sindresorhus/grunt-sass>
433 [@dlmanning](https://github.com/dlmanning/) has created a gulp sass plugin based on node-sass: <https://github.com/dlmanning/gulp-sass>
437 [@sintaxi](https://github.com/sintaxi)’s Harp web server implicitly compiles `.scss` files using node-sass: <https://github.com/sintaxi/harp>
439 ### Metalsmith plugin
441 [@stevenschobert](https://github.com/stevenschobert/) has created a metalsmith plugin based on node-sass: <https://github.com/stevenschobert/metalsmith-sass>
445 [@fourseven](https://github.com/fourseven) has created a meteor plugin based on node-sass: <https://github.com/fourseven/meteor-scss>
449 [@dbashford](https://github.com/dbashford) has created a Mimosa module for sass which includes node-sass: <https://github.com/dbashford/mimosa-sass>
453 There is also an example connect app here: <https://github.com/andrew/node-sass-example>
455 ## Rebuilding binaries
457 Node-sass includes pre-compiled binaries for popular platforms, to add a binary for your platform follow these steps:
459 Check out the project:
462 git clone --recursive https://github.com/sass/node-sass.git
465 node scripts/build -f # use -d switch for debug release
466 # if succeeded, it will generate and move
467 # the binary in vendor directory.
470 ## Command Line Interface
472 The interface for command-line usage is fairly simplistic at this stage, as seen in the following usage section.
474 Output will be sent to stdout if the `--output` flag is omitted.
477 `node-sass [options] <input> [output]`
479 `cat <input> | node-sass > output`
483 `node-sass src/style.scss dest/style.css`
488 -w, --watch Watch a directory or file
489 -r, --recursive Recursively watch directories or files
490 -o, --output Output directory
491 -x, --omit-source-map-url Omit source map URL comment from output
492 -i, --indented-syntax Treat data from stdin as sass code (versus scss)
493 -q, --quiet Suppress log output except on error
494 -v, --version Prints version info
495 --output-style CSS output style (nested | expanded | compact | compressed)
496 --indent-type Indent type for output CSS (space | tab)
497 --indent-width Indent width; number of spaces or tabs (maximum value: 10)
498 --linefeed Linefeed style (cr | crlf | lf | lfcr)
499 --source-comments Include debug info in output
500 --source-map Emit source map
501 --source-map-contents Embed include contents in map
502 --source-map-embed Embed sourceMappingUrl as data URI
503 --source-map-root Base path, will be emitted in source-map as is
504 --include-path Path to look for imported files
505 --follow Follow symlinked directories
506 --precision The amount of precision allowed in decimal numbers
507 --error-bell Output a bell character on errors
508 --importer Path to .js file containing custom importer
509 --functions Path to .js file containing custom functions
510 --help Print usage info
513 The `input` can be either a single `.scss` or `.sass`, or a directory. If the input is a directory the `--output` flag must also be supplied.
515 Also, note `--importer` takes the (absolute or relative to pwd) path to a js file, which needs to have a default `module.exports` set to the importer function. See our test [fixtures](https://github.com/sass/node-sass/tree/974f93e76ddd08ea850e3e663cfe64bb6a059dd3/test/fixtures/extras) for example.
517 The `--source-map` option accepts a boolean value, in which case it replaces destination extension with `.css.map`. It also accepts path to `.map` file and even path to the desired directory.
518 When compiling a directory `--source-map` can either be a boolean value or a directory.
520 ## Binary configuration parameters
522 node-sass supports different configuration parameters to change settings related to the sass binary such as binary name, binary path or alternative download path. Following parameters are supported by node-sass:
524 Variable name | .npmrc parameter | Process argument | Value
525 -----------------|------------------|--------------------|------
526 SASS_BINARY_NAME | sass_binary_name | --sass-binary-name | path
527 SASS_BINARY_SITE | sass_binary_site | --sass-binary-site | URL
528 SASS_BINARY_PATH | sass_binary_path | --sass-binary-path | path
530 These parameters can be used as environment variable:
532 * E.g. `export SASS_BINARY_SITE=http://example.com/`
534 As local or global [.npmrc](https://docs.npmjs.com/misc/config) configuration file:
536 * E.g. `sass_binary_site=http://example.com/`
538 As a process argument:
540 * E.g. `npm install node-sass --sass-binary-site=http://example.com/`
542 ## Post-install Build
544 Install runs only two 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.
548 This module is brought to you and maintained by the following people:
550 * Michael Mifsud - Project Lead ([Github](https://github.com/xzyfer) / [Twitter](https://twitter.com/xzyfer))
551 * Andrew Nesbitt ([Github](https://github.com/andrew) / [Twitter](https://twitter.com/teabass))
552 * Dean Mao ([Github](https://github.com/deanmao) / [Twitter](https://twitter.com/deanmao))
553 * Brett Wilkins ([Github](https://github.com/bwilkins) / [Twitter](https://twitter.com/bjmaz))
554 * Keith Cirkel ([Github](https://github.com/keithamus) / [Twitter](https://twitter.com/Keithamus))
555 * Laurent Goderre ([Github](https://github.com/laurentgoderre) / [Twitter](https://twitter.com/laurentgoderre))
556 * Nick Schonning ([Github](https://github.com/nschonni) / [Twitter](https://twitter.com/nschonni))
557 * Adam Yeats ([Github](https://github.com/adamyeats) / [Twitter](https://twitter.com/adamyeats))
558 * Adeel Mujahid ([Github](https://github.com/am11) / [Twitter](https://twitter.com/adeelbm))
562 We <3 our contributors! A special thanks to all those who have clocked in some dev time on this project, we really appreciate your hard work. You can find [a full list of those people here.](https://github.com/sass/node-sass/graphs/contributors)
564 ### Note on Patches/Pull Requests
567 * Make your feature addition or bug fix.
568 * Add documentation if necessary.
569 * Add tests for it. This is important so I don't break it in a future version unintentionally.
570 * Send a pull request. Bonus points for topic branches.
574 Copyright (c) 2015 Andrew Nesbitt. See [LICENSE](https://github.com/sass/node-sass/blob/master/LICENSE) for details.
576 [LibSass]: https://github.com/sass/libsass