Sass Genius - Smart Compiler

The intelligent SCSS/SASS compiler that thinks ahead. Built with AI-powered development in Cursor, Sass Genius automatically tracks dependencies, handles complex partial structures, and compiles your stylesheets faster than ever.

Why Sass Genius?

Stop wrestling with manual compilation workflows. Sass Genius uses an intelligent dependency graph to automatically detect which files need recompilation when you edit a partial. No configuration needed—just save and watch it work.

Key Advantages

Feature	Sass Genius	Traditional Compilers
Dependency Tracking	Automatic graph-based	Manual or none
Partial Detection	Intelligent `_` file handling	Basic pattern matching
SASS Syntax	Full support (with/without quotes)	Limited
Built-in Modules	Auto-ignores `sass:math`, `sass:color`	Often causes errors
File Operations	Atomic saves (zero downtime)	Can break during compilation
PostCSS Pipeline	Built-in with cssnano	Requires separate setup

Features

Intelligent Dependency Graph

When you edit _variables.sass, Sass Genius automatically knows which entry files import it and recompiles only those files. No more manual "compile all" commands.

styles/
├── main.sass          ← Entry file
├── _variables.sass    ← Edit this...
└── _mixins.sass

✓ Sass Genius detects: main.sass depends on _variables.sass
✓ Automatically recompiles: main.sass → main.min.css

Advanced Partial Detection

Sass Genius understands multiple import styles and automatically resolves partials:

SCSS Style (with quotes):

@import "components/button";
@import "utils/variables", "utils/mixins";

SASS Style (without quotes):

@import components/button
@import utils/variables, utils/mixins

Modern Syntax:

@use "sass:math";
@use "components/button" as btn;
@forward "utils/variables";

All of these automatically resolve to the correct _button.scss or _button.sass file!

Atomic File Operations

Your CSS files are never in a broken state. Sass Genius writes to temporary files first, then atomically replaces the output—ensuring zero downtime even during compilation.

Professional Minification

Built-in PostCSS pipeline with cssnano provides:

Advanced CSS optimization
Safe class name preservation
Removal of comments and whitespace
Color optimization
Duplicate rule elimination

Installation

From VS Code Marketplace

Open VS Code
Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
Search for "Sass Genius"
Click Install

From VSIX Package

code --install-extension sass-genius-1.0.0.vsix

Requirements

VS Code 1.95.0 or higher
Node.js 16+ (for Dart Sass)

Quick Start

Create your SASS/SCSS files:

project/
├── styles/
│   ├── main.scss          ← Entry file
│   ├── _variables.scss    ← Partial
│   └── _mixins.scss       ← Partial
└── public/
    └── css/               ← Output directory

Configure output location (optional - works with defaults):

Create .vscode/settings.json:

{
  "sassGenius.formats": [
    {
      "format": "compressed",
      "extensionName": ".min.css",
      "savePath": "public/css"
    }
  ]
}

Save any SASS file and watch the magic happen! ✨

Configuration

All Available Options

Setting	Type	Default	Description
`sassGenius.includeItems`	array	`["*/.scss", "*/.sass"]`	Glob patterns for entry files
`sassGenius.excludeItems`	array	`["/node_modules/", ...]`	Patterns to exclude
`sassGenius.partialsList`	string	`"/*/_.s[ac]ss"`	Pattern for partial files
`sassGenius.formats`	array	See below	Output formats configuration
`sassGenius.generateMap`	boolean	`false`	Generate source maps
`sassGenius.watchOnLaunch`	boolean	`true`	Auto-start watcher
`sassGenius.compileOnWatch`	boolean	`true`	Auto-compile on changes
`sassGenius.debounceTime`	number	`250`	Debounce time (ms)

Format Configuration

{
  "sassGenius.formats": [
    {
      "format": "compressed",      // or "expanded"
      "extensionName": ".min.css", // output file suffix
      "savePath": "public/css"     // relative to workspace
    },
    {
      "format": "expanded",
      "extensionName": ".css",
      "savePath": "public/css"
    }
  ]
}

Usage Scenarios

Scenario 1: Simple Flat Structure

Perfect for small projects or learning:

styles/
├── main.scss
├── about.scss
└── contact.scss

Configuration:

{
  "sassGenius.includeItems": ["styles/**/*.scss"]
}

Scenario 2: Organized with Partials

Standard project structure:

styles/
├── main.scss              ← Entry
├── _variables.scss        ← Partial
├── _mixins.scss          ← Partial
├── components/
│   ├── _button.scss      ← Partial
│   └── _card.scss        ← Partial
└── layouts/
    ├── _header.scss      ← Partial
    └── _footer.scss      ← Partial

main.scss:

@import "variables";
@import "mixins";
@import "components/button";
@import "components/card";
@import "layouts/header";
@import "layouts/footer";

Result: Edit any partial → main.scss automatically recompiles!

Scenario 3: Multiple Entry Points

For multi-page applications:

styles/
├── home.scss             ← Entry
├── dashboard.scss        ← Entry
├── admin.scss           ← Entry
├── shared/
│   ├── _variables.scss  ← Used by all
│   └── _mixins.scss     ← Used by all
└── components/
    ├── _button.scss     ← Used by home & dashboard
    └── _table.scss      ← Used by dashboard & admin

Result: Edit _button.scss → Only home.scss and dashboard.scss recompile (not admin.scss)!

Scenario 4: Framework Integration

React/Next.js

src/
├── styles/
│   ├── globals.scss
│   ├── _variables.scss
│   └── components/
│       ├── _navbar.scss
│       └── _footer.scss
└── components/
    └── Navbar.tsx

Configuration:

{
  "sassGenius.includeItems": ["src/styles/**/*.scss"],
  "sassGenius.formats": [{
    "format": "compressed",
    "extensionName": ".min.css",
    "savePath": "public/css"
  }]
}

Vue.js

src/
├── assets/
│   └── styles/
│       ├── main.scss
│       ├── _variables.scss
│       └── components/
│           └── _button.scss
└── components/
    └── Button.vue

Scenario 5: Monorepo Setup

packages/
├── app-web/
│   └── styles/
│       └── main.scss
├── app-admin/
│   └── styles/
│       └── admin.scss
└── shared-ui/
    └── styles/
        ├── _variables.scss
        └── _components.scss

Configuration per package:

{
  "sassGenius.includeItems": ["packages/*/styles/**/*.scss"]
}

Partial Detection Deep Dive

How It Works

Sass Genius uses a sophisticated resolver that checks multiple file variations:

For import: @import "components/button"

Checks in order:

components/_button.scss
components/button.scss
components/button/index.scss
components/_button/index.scss
components/_button.sass
components/button.sass
components/button/index.sass
components/_button/index.sass

Supported Import Styles

Classic SCSS (with quotes and semicolons)

@import "variables";
@import "mixins", "functions";
@import "components/button";

Modern SASS (no quotes, no semicolons)

@import variables
@import mixins, functions
@import components/button

Module System

@use "sass:math";
@use "sass:color";
@use "variables" as vars;
@forward "mixins";

Built-in Module Handling

Sass Genius automatically ignores Dart Sass built-in modules:

sass:math
sass:color
sass:string
sass:list
sass:map
sass:selector
sass:meta

No more "file not found" errors for built-in modules!

Complex Nesting Example

styles/
├── main.scss
├── vendor/
│   └── bootstrap/
│       ├── _variables.scss
│       └── mixins/
│           ├── _grid.scss
│           └── _utilities.scss
└── custom/
    ├── _overrides.scss
    └── components/
        └── _custom-button.scss

main.scss:

@import "vendor/bootstrap/variables";
@import "vendor/bootstrap/mixins/grid";
@import "custom/overrides";
@import "custom/components/custom-button";

Result: Edit any nested partial → dependency graph tracks it → main.scss recompiles automatically!

AI-Powered Development

Built with Cursor AI

This extension was developed entirely using Cursor AI with Claude 4.5 Sonnet, showcasing the power of AI-assisted development.

Development Workflow:

Plan Mode - Analyzed requirements, designed architecture
Agent Mode - Implemented features, fixed bugs, optimized code
Iterative Refinement - Real-time debugging and enhancement

Key Features Developed with AI:

Intelligent dependency graph algorithm
SASS syntax parser (with/without quotes)
Atomic file operations
Built-in module detection
Complex import resolution

Cursor AI Version Info

Cursor Version: 2.4.32
VS Code Version: 1.105.1
AI Model: Claude 4.5 Sonnet
Build Type: Stable (Early Access)
Development Date: February 2026

Learn more about Cursor AI: cursor.com

Performance

Compilation Speed

Sass Genius is optimized for speed:

Small projects (< 10 files): ~50-100ms
Medium projects (10-50 files): ~200-500ms
Large projects (50+ files): ~500-2000ms

Smart Recompilation

Only affected files are recompiled:

Edit _variables.scss (used by 3 entry files)
→ Recompiles: 3 files
→ Time: ~150ms

Edit _button.scss (used by 1 entry file)
→ Recompiles: 1 file
→ Time: ~50ms

Edit main.scss (entry file)
→ Recompiles: 1 file + rebuilds dependency graph
→ Time: ~80ms

Debouncing

Rapid saves are automatically debounced (default: 250ms) to prevent multiple compilations.

Commands

Access commands via Command Palette (Cmd+Shift+P / Ctrl+Shift+P):

Sass Genius: Show Output - View compilation logs
Sass Genius: Compile All - Force recompile all entry files
Sass Genius: Compile Current - Compile currently open file

Visual Feedback

Status Bar

Look at the bottom-right corner of VS Code:

🟢 Sass Genius - Ready / Compilation successful
🟡 Sass Genius - Compiling...
🔴 Sass Genius - Compilation error (click to view logs)

Output Panel

Click status bar or use "Show Output" command to see detailed logs:

Sass Genius: Compiling → main.scss
Sass Genius: ✔ main.min.css (127 ms) 45kb

Clickable File Paths

Error messages include clickable file paths:

Error in /path/to/_variables.scss:15
  ↑ Click to jump to error

Troubleshooting

Partial not recompiling entry file

Problem: You edit _variables.scss but main.scss doesn't recompile.

Solutions:

Check that main.scss actually imports _variables.scss
Save main.scss once to rebuild the dependency graph
Check Output panel for "dependency graph" messages
Verify import path is correct (relative to entry file)

"File not found" errors

Problem: Compilation fails with import errors.

Solutions:

Check import path matches actual file location
Remember: @import "button" looks for _button.scss or button.scss
Use relative paths: @import "../shared/variables"
Check file extensions match (.scss vs .sass)

Compilation is slow

Problem: Takes several seconds to compile.

Solutions:

Check excludeItems includes node_modules
Reduce includeItems scope to specific directories
Increase debounceTime if you save frequently
Check for circular imports (rare but possible)

Source maps not generating

Problem: .css.map files not created.

Solution:

{
  "sassGenius.generateMap": true
}

Multiple outputs not working

Problem: Want both .css and .min.css but only getting one.

Solution:

{
  "sassGenius.formats": [
    {
      "format": "expanded",
      "extensionName": ".css",
      "savePath": "public/css"
    },
    {
      "format": "compressed",
      "extensionName": ".min.css",
      "savePath": "public/css"
    }
  ]
}

Known Limitations

Circular imports - Will be detected but may cause performance issues
Dynamic imports - Cannot detect imports constructed at runtime
External files - Files outside workspace are not watched
Very large projects (1000+ files) - May experience slower initial graph building

Contributing

Found a bug or have a feature request?

Issues: github.com/darekwlodarski/sass-genius/issues
Pull Requests: Welcome! Please read CONTRIBUTING.md first
Discussions: Share your use cases and feedback

License

MIT License - see LICENSE file for details.

Changelog

1.0.0 (2026-02-10)

Initial Release

Intelligent dependency graph for automatic partial tracking
Support for SCSS and SASS syntax (with/without quotes)
Built-in Sass module detection (sass:math, sass:color, etc.)
Atomic file operations for zero-downtime compilation
PostCSS pipeline with cssnano minification
Visual status bar feedback
Clickable error logs
Multiple output format support
Source map generation
Debounced compilation
Auto-start watcher on launch

Built with ❤️ using Cursor AI & Claude 4.5 Sonnet
Created by Dariusz Włodarski | 2026

⭐ Rate on Marketplace • 🐙 GitHub • 🐛 Report Bug