0
# Environment Management
1

2
Utilities for managing platform-specific binaries, environment detection, and installation processes. These functions handle the complexity of native module deployment across different operating systems and Node.js versions.
3

4
## Core Imports
5

6
```javascript
7
const sass = require("node-sass");
8
```
9

10
For advanced environment management functions:
11

12
```javascript
13
const extensions = require("node-sass/lib/extensions");
14
```
15

16
## Capabilities
17

18
### Version Information
19

20
Get detailed version information for node-sass and libsass.
21

22
```javascript { .api }
23
/**
24
 * Get version information string
25
 * @returns String containing node-sass and libsass versions
26
 */
27
const info = sass.info;
28

29
// Example output: "node-sass\t9.0.0\t(Wrapper)\t[JavaScript]\nlibsass\t\t3.5.5\t(Sass Compiler)\t[C/C++]"
30
```
31

32
**Usage Example:**
33

34
```javascript
35
const sass = require("node-sass");
36

37
console.log(sass.info);
38
// Output:
39
// node-sass    9.0.0    (Wrapper)         [JavaScript]
40
// libsass      3.5.5    (Sass Compiler)   [C/C++]
41

42
// Parse version info
43
const lines = sass.info.split('\n');
44
const nodeSassLine = lines[0].split('\t');
45
const libsassLine = lines[1].split('\t');
46

47
console.log('node-sass version:', nodeSassLine[1]);  // "9.0.0"
48
console.log('libsass version:', libsassLine[1]);     // "3.5.5"
49
```
50

51
### Platform Detection
52

53
Internal utilities for detecting and describing the runtime environment.
54

55
```javascript { .api }
56
/**
57
 * Get human-readable platform name
58
 * @param platform - OS platform string or null for current
59
 * @returns Platform name or false if unknown
60
 */
61
function getHumanPlatform(platform);
62

63
/**
64
 * Get human-readable architecture description  
65
 * @param arch - Architecture string or null for current
66
 * @returns Architecture description or false if unknown
67
 */
68
function getHumanArchitecture(arch);
69

70
/**
71
 * Get human-readable Node.js version from ABI
72
 * @param abi - ABI version number or null for current
73
 * @returns Node version string or false if unknown
74
 */
75
function getHumanNodeVersion(abi);
76

77
/**
78
 * Get comprehensive environment description
79
 * @param env - Environment string to parse
80
 * @returns Human-readable environment description
81
 */
82
function getHumanEnvironment(env);
83
```
84

85
**Platform Values:**
86

87
- `darwin` → "OS X"
88
- `linux` → "Linux"  
89
- `linux_musl` → "Linux/musl"
90
- `win32` → "Windows"
91
- `freebsd` → "FreeBSD"
92

93
**Architecture Values:**
94

95
- `ia32`, `x86` → "32-bit"
96
- `x64` → "64-bit"
97

98
**Node Version Examples:**
99

100
- ABI 93 → "Node.js 16.x"
101
- ABI 108 → "Node.js 18.x"
102
- ABI 115 → "Node.js 20.x"
103

104
### Binary Management
105

106
Handle platform-specific native binaries and installation.
107

108
```javascript { .api }
109
/**
110
 * Check if environment is supported by node-sass
111
 * @param platform - OS platform (optional, defaults to current)
112
 * @param arch - Architecture (optional, defaults to current)  
113
 * @param abi - Node ABI version (optional, defaults to current)
114
 * @returns Boolean indicating support
115
 */
116
function isSupportedEnvironment(platform?, arch?, abi?);
117

118
/**
119
 * Get expected binary filename for platform
120
 * @returns Binary filename string
121
 */
122
function getBinaryName();
123

124
/**
125
 * Get download URL for platform binary
126
 * @returns Download URL string
127
 */
128
function getBinaryUrl();
129

130
/**
131
 * Get directory containing binaries
132
 * @returns Path to vendor directory
133
 */
134
function getBinaryDir();
135

136
/**
137
 * Get full path to platform binary
138
 * @returns Full path to binary file
139
 */
140
function getBinaryPath();
141

142
/**
143
 * Check if binary exists at specified path
144
 * @param binaryPath - Path to check
145
 * @returns Boolean indicating existence
146
 */
147
function hasBinary(binaryPath);
148
```
149

150
**Usage Examples:**
151

152
```javascript
153
const sass = require("node-sass");
154
const extensions = require("node-sass/lib/extensions");
155

156
// Get platform descriptions
157
console.log("Platform:", extensions.getHumanPlatform());     // "Linux"
158
console.log("Architecture:", extensions.getHumanArchitecture()); // "64-bit"
159
console.log("Node version:", extensions.getHumanNodeVersion()); // "Node.js 18.x"
160

161
// Check current environment support
162
if (extensions.isSupportedEnvironment()) {
163
  console.log("Current environment is supported");
164
} else {
165
  console.log("Current environment is not supported");
166
}
167

168
// Get binary information
169
console.log("Binary name:", extensions.getBinaryName());
170
console.log("Binary path:", extensions.getBinaryPath());
171
console.log("Binary exists:", extensions.hasBinary(extensions.getBinaryPath()));
172

173
// Check specific environment
174
const isSupported = extensions.isSupportedEnvironment("linux", "x64", 108);
175
console.log("Linux x64 Node 18 supported:", isSupported);
176
```
177

178
### Installation and Caching
179

180
Manage binary downloads and caching during installation.
181

182
```javascript { .api }
183
/**
184
 * Get possible cache directory paths
185
 * @returns Array of potential cache paths
186
 */
187
function getCachePathCandidates();
188

189
/**
190
 * Get optimal cache directory path
191
 * @returns Best cache directory path
192
 */
193
function getBinaryCachePath();
194

195
/**
196
 * Get path to cached binary if it exists
197
 * @returns Path to cached binary or null
198
 */
199
function getCachedBinary();
200

201
/**
202
 * Get list of installed binary files
203
 * @returns Array of installed binary filenames
204
 */
205
function getInstalledBinaries();
206
```
207

208
**Cache Directory Priority:**
209

210
1. `SASS_BINARY_CACHE` environment variable
211
2. npm cache directory + `/node-sass`
212
3. User home directory + `/.npm/_cacache/node-sass`
213
4. Temporary directory + `/node-sass`
214

215
**Usage Example:**
216

217
```javascript
218
const extensions = require("node-sass/lib/extensions");
219

220
// Check cache status
221
const cachePath = extensions.getBinaryCachePath();
222
const cachedBinary = extensions.getCachedBinary();
223

224
console.log("Cache directory:", cachePath);
225
if (cachedBinary) {
226
  console.log("Cached binary found:", cachedBinary);
227
} else {
228
  console.log("No cached binary found");
229
}
230

231
// List installed binaries
232
const installed = extensions.getInstalledBinaries();
233
console.log("Installed binaries:", installed);
234
```
235

236
### Environment Variables
237

238
Configuration through environment variables.
239

240
```bash { .api }
241
# Sass import paths (colon-separated on Unix, semicolon on Windows)
242
SASS_PATH="/usr/local/sass:/home/user/sass"
243

244
# Binary cache directory
245
SASS_BINARY_CACHE="/tmp/node-sass-cache"
246

247
# Custom binary download site
248
SASS_BINARY_SITE="https://github.com/sass/node-sass/releases/download"
249

250
# Skip binary download (useful for Docker)
251
SASS_BINARY_PATH="/path/to/binding.node"
252

253
# Force rebuild from source
254
SASS_FORCE_BUILD="true"
255
```
256

257
**Usage Examples:**
258

259
```bash
260
# Set custom import paths
261
export SASS_PATH="./node_modules:./src/styles"
262
node-sass src/main.scss dist/main.css
263

264
# Use custom cache directory
265
export SASS_BINARY_CACHE="/tmp/sass-cache"
266
npm install node-sass
267

268
# Skip binary download in Docker
269
export SASS_BINARY_PATH="/usr/lib/node_modules/node-sass/vendor/linux-x64-108/binding.node"
270
npm install node-sass --ignore-scripts
271
```
272

273
### Error Handling
274

275
Environment-related error messages and diagnostics.
276

277
```javascript { .api }
278
/**
279
 * Generate error message for unsupported environment
280
 * @returns Formatted error message string
281
 */
282
function unsupportedEnvironment();
283

284
/**
285
 * Generate error message for missing binary
286
 * @returns Formatted error message string
287
 */
288
function missingBinary();
289
```
290

291
**Common Environment Issues:**
292

293
- **Unsupported platform/architecture**: Binary not available for the current system
294
- **Missing binary**: Binary not found after installation  
295
- **ABI mismatch**: Node.js version changed after installation
296
- **Permission issues**: Cannot write to cache directory or vendor folder
297
- **Network issues**: Cannot download binary during installation
298

299
**Troubleshooting Steps:**
300

301
1. Check if your platform is supported: `extensions.isSupportedEnvironment()`
302
2. Verify binary exists: `extensions.hasBinary(extensions.getBinaryPath())`  
303
3. Clear cache and reinstall: `rm -rf node_modules/node-sass && npm install node-sass`
304
4. Force rebuild: `npm rebuild node-sass`
305
5. Use custom binary path: Set `SASS_BINARY_PATH` environment variable
306

307
**Example Error Handling:**
308

309
```javascript
310
const sass = require("node-sass");
311

312
try {
313
  const result = sass.renderSync({
314
    data: ".test { color: red; }"
315
  });
316
  console.log(result.css.toString());
317
} catch (error) {
318
  if (error.message.includes("binding.node")) {
319
    console.error("Binary issue detected:");
320
    console.error("- Try: npm rebuild node-sass");
321
    console.error("- Or: rm -rf node_modules/node-sass && npm install node-sass");
322
  } else {
323
    console.error("Compilation error:", error.message);
324
  }
325
}
326
```