or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

grunt-sass

grunt-sass is a Grunt plugin that compiles Sass to CSS using any Sass implementation (typically Dart Sass). It provides seamless integration with Grunt task workflows, automatically handles Sass partials, and supports all standard Sass compilation options including source maps and custom output styles.

Package Information

Package Name: grunt-sass
Package Type: npm
Language: JavaScript
Installation: npm install --save-dev grunt-sass sass

Core Imports

const sass = require('sass');

// Plugin registration (done automatically by load-grunt-tasks or manual loading)
grunt.loadTasks('node_modules/grunt-sass/tasks');

Basic Usage

const sass = require('sass');

require('load-grunt-tasks')(grunt);

grunt.initConfig({
  sass: {
    options: {
      implementation: sass,
      sourceMap: true
    },
    dist: {
      files: {
        'css/main.css': 'scss/main.scss',
        'css/admin.css': 'scss/admin.scss'
      }
    }
  }
});

grunt.registerTask('default', ['sass']);

Capabilities

Plugin Registration

The main export is a function that registers the 'sass' multi-task with Grunt.

/**
 * Main plugin export that registers the sass task with Grunt
 * @param grunt - Grunt instance
 */
function(grunt: object): void;

Sass Task

The registered multi-task that compiles Sass files to CSS.

/**
 * Sass compilation multi-task registered with Grunt
 * Task name: 'sass'
 * Description: 'Compile Sass to CSS'
 */
grunt.registerMultiTask('sass', 'Compile Sass to CSS', function(): void);

Task Configuration

Configuration options for the sass task, combining required options with Sass API options.

interface SassTaskOptions {
  /**
   * Sass implementation to use (REQUIRED)
   * Typically require('sass') for Dart Sass
   */
  implementation: SassImplementation;
  
  /**
   * Source map generation control
   * - true: Generate source map at <dest>.map
   * - string: Generate source map at specified path
   * - falsy: No source map generation
   */
  sourceMap?: boolean | string;
  
  /**
   * All other Sass compilation options are passed through
   * See: https://sass-lang.com/documentation/js-api/interfaces/options/
   */
  [key: string]: any;
}

interface SassImplementation {
  /**
   * Async compilation method from Sass implementation
   */
  compileAsync(source: string, options: object): Promise<SassCompileResult>;
  
  /**
   * Information about the Sass implementation
   */
  info: string;
}

interface SassCompileResult {
  /**
   * Compiled CSS output
   */
  css: string;
  
  /**
   * Source map data (when source maps are enabled)
   */
  map?: string;
}

File Processing Behavior

grunt-sass follows standard Sass conventions and provides specific file handling:

Partial File Ignoring: Files with basename starting with '_' are automatically ignored (standard Sass partial behavior)
Async Processing: All files are processed asynchronously using Promise.all()
Grunt Files Integration: Uses standard Grunt files configuration for source-to-destination mapping

Error Handling

The task provides comprehensive error handling for common failure scenarios:

Missing Implementation Error: Task fails with grunt.fatal() if options.implementation is not provided
Compilation Errors: Sass compilation errors are passed to grunt.fatal() with formatted error messages
File System Errors: File write operations may fail and propagate errors through Grunt

Advanced Configuration Examples

Multiple Target Configuration

grunt.initConfig({
  sass: {
    options: {
      implementation: sass,
      outputStyle: 'compressed'
    },
    development: {
      options: {
        sourceMap: true,
        outputStyle: 'expanded'
      },
      files: {
        'css/main.css': 'scss/main.scss'
      }
    },
    production: {
      files: {
        'dist/css/main.min.css': 'scss/main.scss'
      }
    }
  }
});

Sass Options Pass-through

All Sass API options are supported by passing them through to the underlying implementation:

grunt.initConfig({
  sass: {
    options: {
      implementation: sass,
      includePaths: ['node_modules/bootstrap/scss'],
      outputStyle: 'compressed',
      precision: 8,
      sourceComments: false,
      charset: true
    },
    dist: {
      files: {
        'css/main.css': 'scss/main.scss'
      }
    }
  }
});

Plugin Loading Methods

// Method 1: Using load-grunt-tasks (recommended)
require('load-grunt-tasks')(grunt);

// Method 2: Manual loading
grunt.loadTasks('node_modules/grunt-sass/tasks');

// Method 3: Using grunt.loadNpmTasks
grunt.loadNpmTasks('grunt-sass');