![](\"https://gerillass.com/images/github/gerillass_logo_sassy.svg\"){kind=logo}
\n \n\n \n \n \n
![](\"https://gerillass.com/images/github/heart_red.svg\")
Meet the Coolest Sass Toolset! _\n\n[Gerillass](https://gerillass.com) is a library built on top of [Sass (Syntactically Awesome Style Sheets)](https://sass-lang.com/) to give you flexibility for your projects and accelerate your performance and creativity.\n\nIt is also built to be read by coding agents. Every mixin and function ships with a machine-readable manifest, and the test suite compiles every documented example and asserts every documented refusal. So what the manifest says the library does is what the library does. The docs cannot drift away from the code, because a stale manifest fails the build.\n\nMany of the utilities that come with Gerillass are the solutions I have come up with for the challenges I have faced as a frontend developer over the years. These solutions have been shaped by the inspiration of other popular libraries and frameworks like [Bourbon](https://www.bourbon.io/), [Susy](https://www.oddbird.net/), [Scut](https://github.com/davidtheclark/scut), [Bootstrap](https://getbootstrap.com/), etc. over time and helped me create Gerillass.\n\nHope you’ll enjoy using it!\n\n**Related Links:**\n\n- [Gerillass Website](https://gerillass.com)\n- [Gerillass Documentation](https://docs.gerillass.com)\n- [Gerillass Blog](https://medium.com/gerillass)\n- [Twitter](https://twitter.com/gerillass)\n\n## Table of Contents\n\n- [Dart Sass Upgrade](#dart-sass-upgrade)\n- [Installation](#installation)\n - [Using with Vite](#using-with-vite)\n - [Using with webpack](#using-with-webpack)\n - [Using with Parcel](#using-with-parcel)\n - [Using with Next.js](#using-with-nextjs)\n - [Using with Angular](#using-with-angular)\n - [Using with Gulp](#using-with-gulp)\n - [Using with Grunt](#using-with-grunt)\n - [Using with Ruby: Rails, Jekyll, or plain Sass](#using-with-ruby-rails-jekyll-or-plain-sass)\n - [Cloning the Repository from Github](#cloning-the-repository-from-github)\n - [Versions these examples were tested with](#versions-these-examples-were-tested-with)\n- [Using Gerillass with an AI coding agent](#using-gerillass-with-an-ai-coding-agent)\n- [Three ways to call the same mixin](#three-ways-to-call-the-same-mixin)\n- [Vendor Prefix Support](#vendor-prefix-support)\n- [Experimenting](#experimenting)\n- [Testing](#testing)\n- [Contribution](#contribution)\n- [License](#license)\n- [Additional Info](#additional-info)\n\n## Dart Sass Upgrade\n_We are saying goodbye to LibSass with version 1.3.0_ :cry:\n\nBecause LibSass and the packages built on it, including Node Sass, are deprecated, **Gerillass will no longer support LibSass since version 1.3.0** If you're having a problem running Gerillass v1.3.0 please consider using Dart Sass instead of LibSass. If you are running Dart Sass already, you can install and use Gerillass 1.3.0 and later versions safely. If not, however, please use the earlier versions.\n\n## Installation\n\n npm install gerillass --save-dev\n\nOr with Yarn:\n\n yarn add gerillass --dev\n\nThen load it. If your setup resolves packages from **node_modules**, which Vite, webpack, Next.js and most modern bundlers do, this is all you need:\n\n @use 'gerillass' as *;\n\nIf you call Dart Sass yourself rather than through a bundler, turn on its package importer and use a `pkg:` URL:\n\n @use 'pkg:gerillass' as *;\n\n```js\n// Dart Sass 1.71.0 or later\nimport * as sass from 'sass';\nimport { NodePackageImporter } from 'sass';\n\nsass.compile('style.scss', { importers: [new NodePackageImporter()] });\n```\n\nOr from the command line:\n\n sass --pkg-importer=node style.scss style.css\n\nPointing straight at the file always works too:\n\n @use '{node_modules_path}/gerillass/scss/gerillass' as *;\n\nThe per-tool recipes below were each verified against a real build of Gerillass v1.5.0. The versions used are listed at the end of this section.\n\n\n### Using with Vite\n\nVite resolves the package by name, so there is nothing to configure. This covers anything built on Vite, including React, Vue, Svelte, SvelteKit and Astro.\n\n @use 'gerillass' as *;\n\n### Using with webpack\n\n`sass-loader` also resolves the package by name, with no extra options.\n\n @use 'gerillass' as *;\n\n### Using with Parcel\n\nParcel resolves the package by name too, so the usual line needs no configuration:\n\n @use 'gerillass' as *;\n\n**Remove `main` from your project's own `package.json`.** `npm init -y` writes `\"main\": \"index.js\"`, and Parcel reads that field as a library build target. With it present an app build fails, and the error names the stylesheet rather than the field: `Can't find stylesheet to import`. No Sass option gets around it. If you need to keep the field, turn that target off instead:\n\n \"targets\": { \"main\": false }\n\nTo use a `pkg:` URL, create the importer in a `.sassrc.js`. Setting `pkgImporter` in `.sassrc.json` does not work: Parcel switches Sass to its legacy API for that option, and the import is not found.\n\n // .sassrc.js\n const { NodePackageImporter } = require(\"sass\");\n module.exports = { importers: [new NodePackageImporter()] };\n\nTwo more things worth knowing:\n\n- **Pass the font formats you actually have to `font-face`.** It lists five by default, and Parcel resolves every `url()` in the output, so a folder holding only `.woff2` fails with `Failed to resolve './fonts/inter.eot'`. `$file-formats: woff2` fixes it.\n- **`quietDeps` hides the library's own deprecation warnings.** Dart Sass reports its `if()` deprecation from inside the package on every build. A `.sassrc.json` of `{ \"quietDeps\": true }` silences those and still reports the ones in your own files.\n\n### Using with Next.js\n\nNext.js needs to be told where the library lives. In `next.config.mjs`:\n\n export default {\n sassOptions: {\n loadPaths: [\"node_modules/gerillass/scss\"],\n },\n };\n\nThen, in any `.scss` file:\n\n @use 'gerillass' as *;\n\n### Using with Angular\n\nAdd the library folder to the build target's options in `angular.json`. Angular calls this option `includePaths`, not `loadPaths`:\n\n \"stylePreprocessorOptions\": {\n \"includePaths\": [\"node_modules/gerillass/scss\"]\n }\n\nThen, in `src/styles.scss`:\n\n @use 'gerillass' as *;\n\n### Using with Gulp\n\n`gulp-sass` hands its options straight to Dart Sass, so the option is **`loadPaths`**. The old `includePaths` name came from Node Sass and no longer resolves.\n\n const { src, dest } = require(\"gulp\");\n const sass = require(\"gulp-sass\")(require(\"sass\"));\n\n function styles() {\n return src(\"assets/sass/**/*.scss\")\n .pipe(sass({ loadPaths: [\"node_modules/gerillass/scss\"] }).on(\"error\", sass.logError))\n .pipe(dest(\"assets/css\"));\n }\n\n exports.styles = styles;\n\nThen:\n\n @use 'gerillass' as *;\n\n### Using with Grunt\n\nUse `grunt-sass` with Dart Sass as the implementation. The option here is **`loadPaths`** as well, not `loadPath`, and not `includePaths`.\n\n module.exports = function (grunt) {\n grunt.loadNpmTasks(\"grunt-sass\");\n grunt.initConfig({\n sass: {\n dist: {\n options: {\n implementation: require(\"sass\"),\n loadPaths: [\"node_modules/gerillass/scss\"],\n },\n files: { \"css/main.css\": \"src/main.scss\" },\n },\n },\n });\n };\n\nThen:\n\n @use 'gerillass' as *;\n\n### Using with Ruby: Rails, Jekyll, or plain Sass\n\nGerillass is also a gem. It installs the same Sass files and nothing else: no runtime dependencies, because each kind of project already brings its own Dart Sass. It needs Dart Sass; the LibSass-based `sass-rails` and `sassc-rails` cannot compile it.\n\n bundle add gerillass\n\n**Rails.** With `dartsass-rails` on Propshaft, the Rails 8 default, or `dartsass-sprockets` on Sprockets, there is nothing to configure: the gem hands the library's folder to Sass, and none of its files end up in `public/assets`. Then, in `app/assets/stylesheets/application.scss`:\n\n @use 'gerillass' as *;\n\n**Jekyll.** Put the gem in the plugins group of your `Gemfile`:\n\n group :jekyll_plugins do\n gem \"gerillass\"\n end\n\nThen, in a stylesheet with front matter such as `assets/css/main.scss`:\n\n ---\n ---\n @use 'gerillass' as *;\n\n**Plain Ruby.** Pass the library's folder to `sass-embedded` yourself:\n\n require \"sass-embedded\"\n require \"gerillass\"\n\n Sass.compile(\"style.scss\", load_paths: [Gerillass.load_path])\n\n### Cloning the repository from Github\n\nYou can clone the repository into your local computer from Github.\n\n git clone https://github.com/selfishprimate/gerillass.git\n\nOr you can add the library as a submodule into your Git based project ([What is a submodule?](https://git-scm.com/book/en/v2/Git-Tools-Submodules)).\n\n git submodule add https://github.com/selfishprimate/gerillass.git\n\nIncluding to the project:\n\n @use '{folder_path}/gerillass/scss/gerillass' as *;\n\n### Versions these examples were tested with\n\n| Tool | Version |\n|---|---|\n| Dart Sass | 1.103.1 |\n| Vite | 8.2.2 |\n| webpack / sass-loader | 5.110.3 / 17.0.1 |\n| Next.js | 16.3.4 |\n| Angular CLI | 20.3.36 |\n| Gulp / gulp-sass | 5.0.1 / 6.0.1 |\n| Grunt / grunt-sass | 1.6.3 / 4.1.0 |\n| Parcel / @parcel/transformer-sass | 2.16.4 / 2.16.4, with Dart Sass 1.104.1 and Gerillass 2.1.0 |\n| Ruby / Rails | 4.0.1 / 8.1.3.1 |\n| Propshaft / dartsass-rails | 1.3.2 / 0.5.1 |\n| sprockets-rails / dartsass-sprockets | 3.5.2 / 3.2.1 |\n| Jekyll / jekyll-sass-converter | 4.4.1 / 3.1.0 |\n| sass-embedded (Ruby) | 1.104.1 |\n\n## Using Gerillass with an AI coding agent\n\nA library this size has no training data behind it, so an agent asked to use Gerillass will guess at the argument forms and get them wrong. Two files ship with the package to stop that. Both live inside the installed package, so an agent working in your project can read them straight out of `node_modules/gerillass/`, or, in a Ruby project, out of the gem's folder, which `bundle info gerillass --path` prints.\n\n**`gerillass.json`** describes every mixin and function: its signature, what each argument accepts, examples that compile, and inputs that are refused.\n\n const api = require(\"gerillass/gerillass.json\");\n\n**`SKILL.md`** is a written guide generated from that manifest. It covers how to load the library, the full catalogue, and the argument forms that are easy to get wrong. If your agent supports [Agent Skills](https://code.claude.com/docs/en/skills), copy it into your skills folder:\n\n mkdir -p .claude/skills/gerillass\n cp node_modules/gerillass/SKILL.md .claude/skills/gerillass/\n\nIn a Ruby project, copy it from the gem instead:\n\n cp \"$(bundle info gerillass --path)/SKILL.md\" .claude/skills/gerillass/\n\nOtherwise, point your agent at the file and it will read it as plain Markdown.\n\n### Why you can trust what they say\n\nNeither file is written by hand. Signatures are parsed from the Sass sources, and the semantics come from a separate set of notes, so nobody can describe a mixin that does not exist.\n\nThe part that matters is what happens next. The test suite takes every example in the manifest and compiles it. It takes every input the manifest claims is refused and checks that the library really does refuse it, with its own error message rather than an internal Sass one. It runs every example a second time under the `gls-` prefixed name and requires byte-identical CSS. And it fails the build if either generated file is out of date.\n\nSo the manifest cannot claim behaviour the library does not have. That is the whole point of it. Documentation drifts away from code in most projects, quietly, and an agent reading stale docs writes code that does not work. Here it cannot happen without turning the test suite red first.\n\n\n## Three ways to call the same mixin\n\nNone of them is required. Pick whichever reads best in your project, and stay with it in a given file.\n\n**Bare.** The shortest, and fine unless another library defines the same name.\n\n @use 'gerillass' as *;\n .avatar { @include circle(50px); }\n\n**With the `gls-` prefix.** Every mixin also answers to a prefixed name, which avoids collisions with Bootstrap and friends.\n\n @use 'gerillass' as *;\n .avatar { @include gls-circle(50px); }\n\n**Through a namespace.** Sass's own mechanism, and the tidiest of the three: nothing enters your global scope at all, so a collision is impossible. The name after `as` is yours to choose.\n\n @use 'gerillass' as gls;\n .avatar { @include gls.circle(50px); }\n\nAll three produce identical CSS. The prefix predates the Sass module system; if you are starting fresh, the namespace does the same job without the extra name.\n\n## Vendor Prefix Support\n\nBecause of the vast usage of bundlers like [Gulp](https://gulpjs.com/), [Grunt](https://gruntjs.com/), [Webpack](https://webpack.js.org/), etc.(these frameworks run some other plugins like Autoprefixer to support vendor prefixes), Gerillass doesn't provide vendor prefix support.\n\nSo, feel free to use any tool to support that. My suggestion is Autoprefixer. If you are not using one of the bundlers mentioned above, you can also manually add vendor prefixes using the [Autoprefixer CSS Online](https://autoprefixer.github.io/) tool.\n\n## Experimenting\n\nThe quickest way to try Gerillass is the [playground](https://gerillass.com/playground). It runs in your browser, so there is nothing to install: write Sass on one side and read the CSS it compiles to on the other. Pick a mixin to start from an example, and pick any published Gerillass version to compile against, which makes it easy to see how a call behaves before and after an upgrade.\n\nWhen you are ready to use it in a project, follow the [installation](#installation) steps for your build tool.\n\n## Testing\n\nThe test suite runs with [Jest](https://jestjs.io/) and [True](https://github.com/oddbird/true), which makes Sass unit tests possible (endless thanks to the [OddBird Team](https://github.com/oddbird)).\n\n npm test\n\nIt checks more than hand-written assertions: every mixin is called at least once, every documented example is compiled and compared with a snapshot, and every input a mixin should refuse must stop the build with the library's own error message. [CONTRIBUTING.md](CONTRIBUTING.md#testing) explains which of these a change needs.\n\n## Contribution\n\nPlease read the [contribution details](CONTRIBUTING.md) and feel free to contribute to the library. If you are working on a mixin, the site's dev server has a lab that renders your working copy of the library as you edit it; [CONTRIBUTING.md](CONTRIBUTING.md#seeing-what-it-renders) shows how to use it.\n\n## License\n\nGerillass is licensed under the Apache License, Version 2.0. For more [see the license content](https://github.com/selfishprimate/gerillass/blob/main/LICENSE.md).\n\n## Additional Info\n\nThis project is created with the loving music of **Anna German** and dedicated to **James Williamson**: The best web educator ever. For more information about James, please check his legacy blog page at [simpleprimate.netlify.app](https://simpleprimate.netlify.app) or watch his video lectures about **Web** and **Accessibility** on [LinkedIn Learning](https://www.linkedin.com/learning/instructors/james-williamson).\n","readmeFilename":"README.md"}