Gerillass is a library built on top of Sass (Syntactically Awesome Style Sheets) to give you flexibility for your projects and accelerate your performance and creativity.
It 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.
Many 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, Susy, Scut, Bootstrap, etc. over time and helped me create Gerillass.
Hope you’ll enjoy using it!
Related Links:
- Dart Sass Upgrade
- Installation
- Using Gerillass with an AI coding agent
- Three ways to call the same mixin
- Vendor Prefix Support
- Experimenting
- Testing
- Contribution
- License
- Additional Info
We are saying goodbye to LibSass with version 1.3.0 😢
Because 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.
npm install gerillass --save-dev
Or with Yarn:
yarn add gerillass --dev
Then 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:
@use 'gerillass' as *;
If you call Dart Sass yourself rather than through a bundler, turn on its package importer and use a pkg: URL:
@use 'pkg:gerillass' as *;
// Dart Sass 1.71.0 or later
import * as sass from 'sass';
import { NodePackageImporter } from 'sass';
sass.compile('style.scss', { importers: [new NodePackageImporter()] });Or from the command line:
sass --pkg-importer=node style.scss style.css
Pointing straight at the file always works too:
@use '{node_modules_path}/gerillass/scss/gerillass' as *;
The 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.
Vite resolves the package by name, so there is nothing to configure. This covers anything built on Vite, including React, Vue, Svelte, SvelteKit and Astro.
@use 'gerillass' as *;
sass-loader also resolves the package by name, with no extra options.
@use 'gerillass' as *;
Next.js needs to be told where the library lives. In next.config.mjs:
export default {
sassOptions: {
loadPaths: ["node_modules/gerillass/scss"],
},
};
Then, in any .scss file:
@use 'gerillass' as *;
Add the library folder to the build target's options in angular.json. Angular calls this option includePaths, not loadPaths:
"stylePreprocessorOptions": {
"includePaths": ["node_modules/gerillass/scss"]
}
Then, in src/styles.scss:
@use 'gerillass' as *;
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.
const { src, dest } = require("gulp");
const sass = require("gulp-sass")(require("sass"));
function styles() {
return src("assets/sass/**/*.scss")
.pipe(sass({ loadPaths: ["node_modules/gerillass/scss"] }).on("error", sass.logError))
.pipe(dest("assets/css"));
}
exports.styles = styles;
Then:
@use 'gerillass' as *;
Use grunt-sass with Dart Sass as the implementation. The option here is loadPaths as well, not loadPath, and not includePaths.
module.exports = function (grunt) {
grunt.loadNpmTasks("grunt-sass");
grunt.initConfig({
sass: {
dist: {
options: {
implementation: require("sass"),
loadPaths: ["node_modules/gerillass/scss"],
},
files: { "css/main.css": "src/main.scss" },
},
},
});
};
Then:
@use 'gerillass' as *;
You can clone the repository into your local computer from Github.
git clone https://github.com/selfishprimate/gerillass.git
Or you can add the library as a submodule into your Git based project (What is a submodule?).
git submodule add https://github.com/selfishprimate/gerillass.git
Including to the project:
@use '{folder_path}/gerillass/scss/gerillass' as *;
| Tool | Version |
|---|---|
| Dart Sass | 1.103.1 |
| Vite | 8.2.2 |
| webpack / sass-loader | 5.110.3 / 17.0.1 |
| Next.js | 16.3.4 |
| Angular CLI | 20.3.36 |
| Gulp / gulp-sass | 5.0.1 / 6.0.1 |
| Grunt / grunt-sass | 1.6.3 / 4.1.0 |
A 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/.
gerillass.json describes every mixin and function: its signature, what each argument accepts, examples that compile, and inputs that are refused.
const api = require("gerillass/gerillass.json");
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, copy it into your skills folder:
mkdir -p .claude/skills/gerillass
cp node_modules/gerillass/SKILL.md .claude/skills/gerillass/
Otherwise, point your agent at the file and it will read it as plain Markdown.
Neither 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.
The 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.
So 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.
None of them is required. Pick whichever reads best in your project, and stay with it in a given file.
Bare. The shortest, and fine unless another library defines the same name.
@use 'gerillass' as *;
.avatar { @include circle(50px); }
With the gls- prefix. Every mixin also answers to a prefixed name, which avoids collisions with Bootstrap and friends.
@use 'gerillass' as *;
.avatar { @include gls-circle(50px); }
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.
@use 'gerillass' as gls;
.avatar { @include gls.circle(50px); }
All 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.
Because of the vast usage of bundlers like Gulp, Grunt, Webpack, etc.(these frameworks run some other plugins like Autoprefixer to support vendor prefixes), Gerillass doesn't provide vendor prefix support.
So, 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 tool.
Experimentation with Gerillass is easy: If you're processing Sass files on your computer already, download the Gerillass Sass library, include it in your project, and start using it. If not, use Gerillass Play! Gerillass Play is a Gulp based playground, built for you to get started with Sass and Gerillass quickly.
Important Note: Don't forget that you must have Node.js and Gulp CLI installed on your machine to work with Gerillass Play.
Gerillass comes with a unit-testing module named True, which makes Sass unit tests possible (endless thanks to the OddBird Team).
You can find two test examples under the test folder, take your time, examine the codes, and then write your unit tests. After that, run the following command to see if the tests pass.
npm test
Please read the contribution details and feel free to contribute to the library.
Gerillass is licensed under the Apache License, Version 2.0. For more see the license content.
This 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 or watch his video lectures about Web and Accessibility on LinkedIn Learning.