igosuki/compass-mixins
Compass Mixins packages the classic Compass Sass mixin library as a standalone dependency, providing familiar helpers for gradients, typography, layout, and vendor prefixes with modern Sass compilers—without requiring the full Compass framework.
What this actually is. A vendored copy of the Compass stylesheet library (lib/compass/**/*.scss) repackaged as plain SCSS partials so it can be consumed by node-sass/libsass (and mostly dart-sass) instead of the dead Ruby Compass gem. There is no JavaScript API, no compiler plugin, no CLI — it is a directory of .scss files you put on the Sass load path. That framing determines everything below.
Install and wire up the load path.
npm install --save-dev compass-mixins
# or: bower install compass-mixins
The load path must point at lib/, not lib/compass/, because imports are written as compass/css3:
// gulp-sass / node-sass
sass({ includePaths: ['node_modules/compass-mixins/lib'] })
// webpack sass-loader
{ loader: 'sass-loader', options: { sassOptions: { includePaths: ['node_modules/compass-mixins/lib'] } } }
// app.scss — first import
@import "compass/css3";
.btn { @include border-radius(4px); @include box-shadow(0 1px 2px rgba(0,0,0,.2)); }
Where to look first, in order:
lib/compass/_compass.scss — the root manifest; shows every submodule that @import "compass" pulls in. Read this before importing the umbrella file.lib/compass/support/_variables.scss — the $legacy-support-for-* / $experimental-support-for-* switches. This is the only configuration surface the package really has.lib/compass/css3/ — _border-radius.scss, _box-shadow.scss, _transition.scss, _transform.scss, _gradients.scss, _background-size.scss. Mixin signatures are documented in comments at the top of each file.lib/compass/utilities/ — general/ (clearfix, inline-block, float, nowrap, min-height), sprites/, tables/, lists/ (horizontal-list, inline-list).lib/compass/layout/ (sticky-footer, grid-background, stretching) and lib/compass/typography/ (links, lists, vertical-rhythm).First real use case. You are porting a legacy Rails/Bower project off Ruby Sass. The existing .scss is full of @include border-radius, @include box-shadow, @include background-image(linear-gradient(...)), @include clearfix. Swap the Compass gem for this package, point the load path at lib, and those files compile unchanged. That migration is the package's entire reason to exist — evaluate it as a compatibility shim, not a design system.
Import narrowly, never the umbrella. @import "compass" drags in reset, typography, layout and sprites whether you use them or not. It costs compile time on every build. Import the specific partials your file needs:
@import "compass/css3/border-radius";
@import "compass/css3/box-shadow";
@import "compass/utilities/general/clearfix";
Configure support flags before any compass import. This is the intended extension point and the single most valuable knob:
// _config.scss — must load first
$legacy-support-for-ie6: false;
$legacy-support-for-ie7: false;
$legacy-support-for-ie8: false;
$experimental-support-for-opera: false;
$experimental-support-for-khtml: false;
$experimental-support-for-svg: false; // kills extra gradient syntax
$experimental-support-for-webkit: true;
$experimental-support-for-mozilla: true;
@import "compass/css3";
With IE legacy support off, opacity() stops emitting filter: progid:DXImageTransform… and clearfix emits the modern :before/:after form only. On a 2020s codebase this alone can cut significant dead CSS.
Split responsibilities with autoprefixer. The mixins hand-write -webkit-, -moz-, -ms-, -o- prefixes at authoring time. Modern practice is: let this package handle what a post-processor cannot (gradient fallback colors, sprite math, sticky-footer structure, horizontal-list, link-colors, vertical rhythm), and let Autoprefixer own vendor prefixes from a browserslist. If you do both, keep $experimental-support-for-* minimal to avoid duplicated declarations.
Wrap it, don't sprinkle it. Keep the number of files that @import compass small. Centralize in one _vendor.scss that exposes semantic mixins:
// _vendor.scss
@import "compass/css3/border-radius";
@import "compass/css3/box-shadow";
@import "compass/css3/transition";
@mixin elevation($level: 1) {
@include box-shadow(0 #{$level}px #{$level * 2}px rgba(0,0,0,.15));
}
Components then use @include elevation(2) and never mention Compass. When you eventually rip the package out, you rewrite one file instead of grepping hundreds.
Replace the Ruby-only features rather than fighting them. compass/utilities/sprites (sprite-map, sprite, sprite-url, all-*-sprites) and inline-image() / image-width() / image-height() are Sass functions implemented by the Compass Ruby extension. Libsass and dart-sass cannot execute them — you'll get "Undefined function" at compile time. Use gulp.spritesmith / postcss-sprites / imgix for sprites and a PostCSS data-URI plugin for inline-image. The pure-Sass parts of utilities/sprites (the CSS emitting side) are useless without a generated sprite map.
Build/CI pattern. Because the package is frozen, pin a fixture test so a Sass upgrade doesn't silently break you:
npx sass --load-path=node_modules/compass-mixins/lib test/fixtures/all-mixins.scss /tmp/out.css
Keep one fixture that @includes every mixin you actually use, and diff the output. That's your only regression net.
includePaths at lib/compass produces Error: Can't find stylesheet to import for compass/css3. The path must be the directory containing compass/.@include time in others. Setting $legacy-support-for-ie8: false after importing compass/css3 may or may not take effect depending on the mixin. Always set them in a _config.scss imported before anything else.clearfix, opacity, transform, column, float), function names, and variables like $default-border-radius. Collisions with your own @mixin opacity or with Bootstrap/Foundation are real. Audit names before mixing libraries.compass/reset. It emits a full CSS reset into your bundle the moment it's imported (unlike mixins, which emit nothing until included). Most teams want normalize.css or nothing.@extend gains nothing here. The library is almost entirely mixins, not placeholder selectors. Repeated @includes duplicate declarations — that's expected; use your own %placeholders if you need dedup, and beware @extend blowing up selectors in a large cascade.@import (now deprecated → warnings on every build), and some arithmetic triggers slash-division deprecation warnings. It compiles, but you'll want silenceDeprecations or a pinned Sass version. @use migration is not possible without rewriting the package.NOASSERTION; the underlying Compass stylesheets carry their own BSD/MIT-style notices in the file headers. Read LICENSE / file headers in the repo and get sign-off if you're shipping commercially. Don't assume MIT from the package name.lib/compass into your repo (or a private registry) so a registry takedown or an npm outage can't break your build.npx sass --load-path=… input.scss output.css to isolate whether an error is your config, your load path, or a genuine missing sub-import. "Undefined mixin X" is almost always a missing partial import (e.g. using text-shadow after only importing compass/css3/border-radius).grep -rhoE '@include [a-z-]+' src/ | sort -u gives you the exact inventory. Most entries map to Autoprefixer; the residue is usually a dozen structural mixins (clearfix, sticky-footer, horizontal-list, inline-block, link-colors, column) worth hand-porting in an afternoon.How can I help you explore Laravel packages today?