@xakpc/gulp-grass-sass

gulp-grass-sass

Sass plugin for Gulp utilizing the speed and performance of Grass rust library to compile SASS to CSS 8x faster than gulp-sass.
Start here »

Report Bug · Request Feature

Table of Contents

About The Project
- Built With
Getting Started
- Prerequisites
- Installation
Usage
Contributing
License
Contact
Acknowledgments

About The Project

This project aims to provide a fast and efficient way to compile SCSS to CSS using Gulp, leveraging the capabilities of the Grass rust library. With this setup, you can streamline your front-end development workflow, ensuring quick on-fly compilation times and a smooth integration with your existing Gulp tasks.

Key Features

High Performance: Drag and drop 8x compile speed (tested on 98KB CSS file) by utilizing the Grass rust library.
Seamless Integration: Easily integrates with your existing Gulp setup.
Error Handling: Provides informative error messages to help you debug issues quickly.
Flexible Configuration: Supports custom paths and configuration options to fit your project needs.

This project is designed to enhance your development experience in Visual Studio by combining the power of modern JavaScript tools with the performance benefits of Rust.

Built With

Node.js · Rust · Gulp · Grass · N-API

(back to top)

Getting Started

This project is built primarily to be used in Visual Studio with Task Runner Explorer, but it can also be used from anywhere using the CLI.

Prerequisites

You either need to have Visual Studio with the built-in Task Runner Explorer or gulp-cli to run Gulp from the terminal.

Installation

Open the Terminal in Visual Studio from the menu: View > Terminal.
Navigate to your project directory in the Terminal.
Install the required npm packages as dev dependencies:
```
npm install --save-dev gulp @xakpc/gulp-grass-sass
```

Create a gulpfile.js in the root of your project with the following content:

/// <binding ProjectOpened='watch' />
const { watch, src, dest } = require('gulp');
const compile = require('@xakpc/gulp-grass-sass');

// Task to compile SCSS to CSS without minification using rust Grass lib
function compileSassFastish() {
  return src('wwwroot/css/main.scss')
    .pipe(compile().on('error', e => { console.log(e); })) 
    .pipe(dest('wwwroot/css'));
}

exports.compileCssFastish = compileSassFastish;

// Task to watch for changes in scss files
exports.watch = function () {
  watch('wwwroot/css/*.scss', compileSassFastish);
};

Change paths according to your project needs.

(back to top)

Usage

gulp-grass-sass is built to be used in a Gulp task.

Compile your CSS

To compile your CSS with a build task, then watch your files for changes, you might write something like this:

const gulp = require('gulp');
const compile = require('@xakpc/gulp-grass-sass');

function compileStyles() {
  return gulp.src('./wwwroot/sass/**/*.scss')
    .pipe(compile().on('error', e => { console.log(e); }))
    .pipe(gulp.dest('./wwwroot/css'));
};

exports.compileStyles = compileStyles;
exports.watch = function () {
  gulp.watch('./wwwroot/sass/**/*.scss', compileStyles);
};

To run it you have a several options

Run watch task in Visual Studio
1. Open Task Runner Explorer in Visual Studio from the menu: View > Other Windows > Task Runner Explorer.
2. In Task Runner Explorer, you should see the Gulp tasks listed. Right-click on the watch task and select Bindings > Project Open to ensure the task runs when the project is opened (should be set by <binding ProjectOpened='watch' />).
3. Run the Gulp watch task manually by right-clicking on the watch task in Task Runner Explorer and selecting Run to start compiling SCSS files.
Or run it manually from Terminal if gulp-cli installed
```
gulp watch
```

Compile with options

To change the final output of your CSS, you can pass an options object to compile function.

The following options are available in the grass library, and therefore in gulp-grass-sass as well:

export const enum SassSyntax {
  Sass = 'Sass',
  Css = 'Css',
  Scss = 'Scss'
}
export const enum SassOutputStyle {
  Expanded = 'Expanded',
  Compressed = 'Compressed'
}

export interface SassOptions {
    sassSyntax?: SassSyntax
    outputStyle?: SassOutputStyle
    includePaths?: Array<string>
}

The Grass library has more options so more of them could be added in the future if needed.

All of the options are optinonal

sassSyntax would usually be determined from file extension, Scss by default
outputStyle is Expanded by default
includePaths are paths on the filesystem that Sass will look in when locating modules. For example, if you pass pages/ as a load path, you can use @import "index.cshtml.scss" to load pages/index.cshtml.scss.

Note: @import "index.cshtml" would not work, .scss extension is required here.

function compileStyles() {
  return gulp.src('./wwwroot/sass/**/*.scss')
    .pipe(compile({outputStyle: 'Compressed'}).on('error', e => { console.log(e); }))
    .pipe(gulp.dest('./wwwroot/css'));
};

exports.buildStyles = compileStyles;

Include a source map

Source maps are not supported in the grass library, and therefore not in gulp-grass-sass either.

(back to top)

Contributing

Thank you for considering a contribution to the project! Contributions make the open source community a vibrant and innovative space. I appreciate your efforts to make this project even better.

How to Contribute

If you have a suggestion or feature you’d like to add, here’s how you can contribute:

Start by forking the project repository to your own GitHub account.
Create a Feature branch specifically for your contribution to keep your work organized. Use a meaningful name: git checkout -b feature/YourFeatureName.
Make the modifications or additions you have in mind. Stick to the coding style already used in the project.
Commit your changes with a clear, concise commit message that explains the "why" behind your work. For example: git commit -m "Add filtering by tag functionality".
Push your changes to your repository: git push origin feature/YourFeatureName.
Go to the original repository, and you’ll see a prompt to open a pull request from your newly pushed branch. Fill out the pull request template with the relevant information so it’s clear what your changes are and why they should be included.
If your pull request receives feedback, be responsive and make necessary updates. This often involves additional commits and discussion with maintainers.

Before You Submit

Check Existing Issues and Pull Requests to ensure your contribution isn’t duplicative.
Run Tests to confirm your changes don’t break existing functionality.

Additional Ways to Contribute

Report a Bug by opening an issue. Use the tag bug to help maintainers quickly see what’s wrong.
Request a Feature by opening an issue with the tag enhancement. Describe what you’d like to see and why it’s a valuable addition.
Give a Star on GitHub if you like the project and want to show your support!

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Pavel - @xakpc

Project Link: https://github.com/xakpc/gulp-grass-sass/

My personal blog: xakpc.info

(back to top)

Acknowledgments

(back to top)