Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/xakpc/gulp-grass-sass
Sass plugin for Gulp to compile SASS to CSS 8x faster
https://github.com/xakpc/gulp-grass-sass
gulp sass
Last synced: 4 months ago
JSON representation
Sass plugin for Gulp to compile SASS to CSS 8x faster
- Host: GitHub
- URL: https://github.com/xakpc/gulp-grass-sass
- Owner: xakpc
- License: mit
- Created: 2024-06-16T10:11:03.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2024-08-31T13:51:47.000Z (5 months ago)
- Last Synced: 2024-09-29T04:01:47.462Z (4 months ago)
- Topics: gulp, sass
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/@xakpc/gulp-grass-sass
- Size: 172 KB
- Stars: 7
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
[![GitHub Actions Workflow Status][actions-shield]][actions-url]
[![Stargazers][stars-shield]][stars-url]
[![MIT License][license-shield]][license-url]
[![NPM Downloads][npm-shield]][npm-url]
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
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](https://nodejs.org/) · [Rust](https://www.rust-lang.org/) · [Gulp](https://gulpjs.com/) · [Grass](https://github.com/connorskees/grass) · [N-API](https://github.com/napi-rs/napi-rs)
## 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 need Visual Studio with the built-in Task Runner Explorer or `gulp-cli` to run Gulp from the terminal.
Due to the nature of Rust being compiled into native libraries, this package is built specifically for the following architectures. Please ensure your system matches one of the following to use this package:
- darwin-arm64 (macOS on ARM, e.g., M1/M2 Macs)
- darwin-x64 (macOS on Intel x86_64)
- linux-x64-gnu (Linux on Intel/AMD x86_64)
- win32-x64-msvc (Windows 64-bit on Intel/AMD with MSVC)
### Installation
1. Open the **Terminal** in Visual Studio from the menu: **View** > **Terminal**.
1. Navigate to your project directory in the Terminal.
1. Install the required npm packages as dev dependencies:
```sh
npm install --save-dev gulp @xakpc/gulp-grass-sass
```
1. Create a `gulpfile.js` in the root of your project with the following content:
```js
///
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);
};
```
1. Change paths according to your project needs.
## 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:
```js
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
1. Run `watch` task in Visual Studio
1. Open Task Runner Explorer in Visual Studio from the menu: **View** > **Other Windows** > **Task Runner Explorer**.
1. 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 ``).
1. 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.
1. Or run it manually from Terminal if `gulp-cli` installed
```sh
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:
```ts
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
}
```
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.
```js
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.
## 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:
1. Start by forking the project repository to your own GitHub account.
2. Create a Feature branch specifically for your contribution to keep your work organized. Use a meaningful name: `git checkout -b feature/YourFeatureName`.
3. Make the modifications or additions you have in mind. Stick to the coding style already used in the project.
4. 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"`.
5. Push your changes to your repository: `git push origin feature/YourFeatureName`.
6. 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.
7. 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](https://github.com/xakpc/gulp-grass-sass/issues/new?labels=bug&template=bug-report---.md). Use the tag `bug` to help maintainers quickly see what’s wrong.
- **Request a Feature** by [opening an issue](https://github.com/xakpc/gulp-grass-sass/issues/new?labels=enhancement&template=feature-request---.md) 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!
## License
Distributed under the MIT License. See `LICENSE.txt` for more information.
## Contact
Pavel - [@xakpc](https://twitter.com/xakpc)
Project Link: [https://github.com/xakpc/gulp-grass-sass/](https://github.com/xakpc/gulp-grass-sass/)
My personal blog: [xakpc.info](https://xakpc.info)
## Acknowledgments
* [grass](https://github.com/connorskees/grass) by [Connor Skees](https://github.com/connorskees)
* [Node-API (N-API) for Rust](https://github.com/napi-rs/napi-rs)
* [Best README Template](https://github.com/othneildrew/Best-README-Template)
[contributors-shield]: https://img.shields.io/github/contributors/xakpc/gulp-grass-sass.svg?style=for-the-badge
[contributors-url]: https://github.com/xakpc/gulp-grass-sass/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/xakpc/gulp-grass-sass.svg?style=for-the-badge
[forks-url]: https://github.com/xakpc/gulp-grass-sass/network/members
[stars-shield]: https://img.shields.io/github/stars/xakpc/gulp-grass-sass.svg?style=for-the-badge
[stars-url]: https://github.com/xakpc/gulp-grass-sass/stargazers
[issues-shield]: https://img.shields.io/github/issues/xakpc/gulp-grass-sass.svg?style=for-the-badge
[issues-url]: https://github.com/xakpc/gulp-grass-sass/issues
[license-shield]: https://img.shields.io/github/license/xakpc/gulp-grass-sass?style=for-the-badge
[license-url]: https://github.com/xakpc/gulp-grass-sass/blob/master/LICENSE.txt
[npm-shield]: https://img.shields.io/npm/dw/%40xakpc%2Fgulp-grass-sass?style=for-the-badge&logo=npm
[npm-url]: https://www.npmjs.com/package/@xakpc/gulp-grass-sass
[actions-shield]: https://img.shields.io/github/actions/workflow/status/xakpc/gulp-grass-sass/build-all-targets.yml?style=for-the-badge&logo=github
[actions-url]: https://github.com/xakpc/gulp-grass-sass/actions