CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-node-sass

Node.js wrapper around libsass for compiling Sass and SCSS files to CSS

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

environment.mddocs/

Environment Management

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.

Core Imports

const sass = require("node-sass");

For advanced environment management functions:

const extensions = require("node-sass/lib/extensions");

Capabilities

Version Information

Get detailed version information for node-sass and libsass.

/**
 * Get version information string
 * @returns String containing node-sass and libsass versions
 */
const info = sass.info;

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

Usage Example:

const sass = require("node-sass");

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

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

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

Platform Detection

Internal utilities for detecting and describing the runtime environment.

/**
 * Get human-readable platform name
 * @param platform - OS platform string or null for current
 * @returns Platform name or false if unknown
 */
function getHumanPlatform(platform);

/**
 * Get human-readable architecture description  
 * @param arch - Architecture string or null for current
 * @returns Architecture description or false if unknown
 */
function getHumanArchitecture(arch);

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

/**
 * Get comprehensive environment description
 * @param env - Environment string to parse
 * @returns Human-readable environment description
 */
function getHumanEnvironment(env);

Platform Values:

  • darwin → "OS X"
  • linux → "Linux"
  • linux_musl → "Linux/musl"
  • win32 → "Windows"
  • freebsd → "FreeBSD"

Architecture Values:

  • ia32, x86 → "32-bit"
  • x64 → "64-bit"

Node Version Examples:

  • ABI 93 → "Node.js 16.x"
  • ABI 108 → "Node.js 18.x"
  • ABI 115 → "Node.js 20.x"

Binary Management

Handle platform-specific native binaries and installation.

/**
 * Check if environment is supported by node-sass
 * @param platform - OS platform (optional, defaults to current)
 * @param arch - Architecture (optional, defaults to current)  
 * @param abi - Node ABI version (optional, defaults to current)
 * @returns Boolean indicating support
 */
function isSupportedEnvironment(platform?, arch?, abi?);

/**
 * Get expected binary filename for platform
 * @returns Binary filename string
 */
function getBinaryName();

/**
 * Get download URL for platform binary
 * @returns Download URL string
 */
function getBinaryUrl();

/**
 * Get directory containing binaries
 * @returns Path to vendor directory
 */
function getBinaryDir();

/**
 * Get full path to platform binary
 * @returns Full path to binary file
 */
function getBinaryPath();

/**
 * Check if binary exists at specified path
 * @param binaryPath - Path to check
 * @returns Boolean indicating existence
 */
function hasBinary(binaryPath);

Usage Examples:

const sass = require("node-sass");
const extensions = require("node-sass/lib/extensions");

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

// Check current environment support
if (extensions.isSupportedEnvironment()) {
  console.log("Current environment is supported");
} else {
  console.log("Current environment is not supported");
}

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

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

Installation and Caching

Manage binary downloads and caching during installation.

/**
 * Get possible cache directory paths
 * @returns Array of potential cache paths
 */
function getCachePathCandidates();

/**
 * Get optimal cache directory path
 * @returns Best cache directory path
 */
function getBinaryCachePath();

/**
 * Get path to cached binary if it exists
 * @returns Path to cached binary or null
 */
function getCachedBinary();

/**
 * Get list of installed binary files
 * @returns Array of installed binary filenames
 */
function getInstalledBinaries();

Cache Directory Priority:

  1. SASS_BINARY_CACHE environment variable
  2. npm cache directory + /node-sass
  3. User home directory + /.npm/_cacache/node-sass
  4. Temporary directory + /node-sass

Usage Example:

const extensions = require("node-sass/lib/extensions");

// Check cache status
const cachePath = extensions.getBinaryCachePath();
const cachedBinary = extensions.getCachedBinary();

console.log("Cache directory:", cachePath);
if (cachedBinary) {
  console.log("Cached binary found:", cachedBinary);
} else {
  console.log("No cached binary found");
}

// List installed binaries
const installed = extensions.getInstalledBinaries();
console.log("Installed binaries:", installed);

Environment Variables

Configuration through environment variables.

# Sass import paths (colon-separated on Unix, semicolon on Windows)
SASS_PATH="/usr/local/sass:/home/user/sass"

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

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

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

# Force rebuild from source
SASS_FORCE_BUILD="true"

Usage Examples:

# Set custom import paths
export SASS_PATH="./node_modules:./src/styles"
node-sass src/main.scss dist/main.css

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

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

Error Handling

Environment-related error messages and diagnostics.

/**
 * Generate error message for unsupported environment
 * @returns Formatted error message string
 */
function unsupportedEnvironment();

/**
 * Generate error message for missing binary
 * @returns Formatted error message string
 */
function missingBinary();

Common Environment Issues:

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

Troubleshooting Steps:

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

Example Error Handling:

const sass = require("node-sass");

try {
  const result = sass.renderSync({
    data: ".test { color: red; }"
  });
  console.log(result.css.toString());
} catch (error) {
  if (error.message.includes("binding.node")) {
    console.error("Binary issue detected:");
    console.error("- Try: npm rebuild node-sass");
    console.error("- Or: rm -rf node_modules/node-sass && npm install node-sass");
  } else {
    console.error("Compilation error:", error.message);
  }
}

docs

cli.md

compilation.md

environment.md

index.md

types.md

tile.json