0
# node-sass
1

2
node-sass is a Node.js wrapper around libsass, the C/C++ port of the popular Sass CSS preprocessor. It provides both programmatic APIs and command-line tools for compiling Sass and SCSS files into CSS, with support for source maps, custom functions, and various output styles.
3

4
## Package Information
5

6
- **Package Name**: node-sass
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js native module with C++ bindings)
9
- **Installation**: `npm install node-sass`
10

11
## Core Imports
12

13
```javascript
14
const sass = require("node-sass");
15
```
16

17
For ES modules:
18

19
```javascript
20
import sass from "node-sass";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const sass = require("node-sass");
27

28
// Compile from file
29
sass.render({
30
  file: "input.scss",
31
  outFile: "output.css",
32
}, (error, result) => {
33
  if (error) {
34
    console.error(error);
35
  } else {
36
    console.log(result.css.toString());
37
  }
38
});
39

40
// Compile from string
41
sass.render({
42
  data: "$primary-color: #333; body { color: $primary-color; }",
43
}, (error, result) => {
44
  if (error) {
45
    console.error(error);
46
  } else {
47
    console.log(result.css.toString());
48
  }
49
});
50

51
// Synchronous compilation
52
try {
53
  const result = sass.renderSync({
54
    file: "input.scss"
55
  });
56
  console.log(result.css.toString());
57
} catch (error) {
58
  console.error(error);
59
}
60
```
61

62
## Architecture
63

64
node-sass is structured around several key components:
65

66
- **Core Render Engine**: Asynchronous (`render`) and synchronous (`renderSync`) compilation functions
67
- **Sass Type System**: Complete type constructors for creating and manipulating Sass values in custom functions
68
- **CLI Interface**: Command-line tool with extensive options for build processes and file watching
69
- **Binary Management**: Platform-specific binary handling with automatic downloads and caching
70
- **File Watching**: Development workflow support with automatic recompilation on file changes
71

72
## Capabilities
73

74
### Core Compilation
75

76
Primary Sass/SCSS compilation functionality for converting stylesheets to CSS with full configuration options.
77

78
```javascript { .api }
79
function render(options, callback);
80
function renderSync(options);
81
```
82

83
[Core Compilation](./compilation.md)
84

85
### Sass Type System
86

87
Complete type system for creating and manipulating Sass values in custom functions, including colors, numbers, strings, lists, and maps.
88

89
```javascript { .api }
90
const types = {
91
  Boolean: function(value),
92
  Color: function(r, g, b, a),
93
  Error: function(message),
94
  List: function(length, separator),
95
  Map: function(length),
96
  Null: function(),
97
  Number: function(value, unit),
98
  String: function(value)
99
};
100
```
101

102
[Sass Type System](./types.md)
103

104
### Command Line Interface
105

106
Comprehensive CLI tool for build processes, file watching, and batch compilation with extensive configuration options.
107

108
```bash { .api }
109
node-sass [options] <input> [output]
110
node-sass --watch <input> --output <output>
111
```
112

113
[Command Line Interface](./cli.md)
114

115
### Environment Management
116

117
Utilities for managing platform-specific binaries, environment detection, and installation processes.
118

119
```javascript { .api }
120
// Exposed through extensions module (internal)
121
function getBinaryPath();
122
function isSupportedEnvironment();
123
function getVersionInfo(binding);
124
```
125

126
[Environment Management](./environment.md)
127

128
## Constants
129

130
```javascript { .api }
131
const TRUE = sass.TRUE;     // Sass Boolean TRUE singleton
132
const FALSE = sass.FALSE;   // Sass Boolean FALSE singleton  
133
const NULL = sass.NULL;     // Sass Null singleton
134
const info = sass.info;     // Version information string
135
```
136

137
These constants provide direct access to commonly used Sass singleton values:
138

139
- `sass.TRUE` - Singleton instance representing Sass boolean true (same as `sass.types.Boolean.TRUE`)
140
- `sass.FALSE` - Singleton instance representing Sass boolean false (same as `sass.types.Boolean.FALSE`)
141
- `sass.NULL` - Singleton instance representing Sass null (same as `sass.types.Null.NULL`)
142
- `sass.info` - String containing version information for node-sass and libsass