Sass Setup and Installation — Complete Guide

In this tutorial, you will learn about Sass Setup and Installation. We cover key concepts, practical examples, and best practices to help you master this topic.

Set up Sass with npm, configure compilation scripts, choose between SCSS and indented syntax, and integrate with build tools like Webpack or Vite for automated compilation.

What You'll Learn

• Installing Sass via npm
• SCSS vs indented (.sass) syntax
• Compilation commands and flags
• Source maps for debugging
• Integration with build tools
• Directory structure for Sass projects

Why It Matters

• Correct setup prevents compilation issues
• Build tool integration automates compilation
• Source maps enable debugging compiled CSS
• Proper directory structure scales with projects

Real-World Use

• A team uses npm scripts to compile Sass in CI/CD
• A developer integrates Sass into a Vite project
• A legacy project uses gulp-sass for compilation
• A design system compiles Sass with source maps

flowchart LR
  A[npm install sass] --> B[Create .scss files]
  B --> C[Configure build script]
  C --> D[Compile to CSS]
  D --> E[Source maps]
  D --> F[Minified output]
  E --> G[Debug in DevTools]

Installation and Setup

Code Example: Installing Sass

# 1. Initialize npm project
npm init -y

# 2. Install Sass as dev dependency
npm install --save-dev sass

# 3. Verify installation
npx sass --version
# Output: 1.77.0 (or similar)

# 4. Create directory structure
mkdir -p src/scss dist/css

# 5. Create main SCSS file
echo '
$primary: #0066CC;
body { font-family: system-ui; color: $primary; }
' > src/scss/main.scss

# 6. Compile
npx sass src/scss/main.scss dist/css/main.css

# 7. Compile with source map
npx sass src/scss/main.scss dist/css/main.css --source-map

# 8. Watch mode
npx sass --watch src/scss:dist/css

Expected output: Sass compiles main.scss to main.css. Source maps allow browser DevTools to show the original SCSS line numbers. Watch mode recompiles on every save.

Code Example: Package.json Scripts

{
    "name": "sass-project",
    "scripts": {
        "sass:dev": "sass src/scss:dist/css --source-map --watch",
        "sass:build": "sass src/scss:dist/css --style compressed --no-source-map",
        "build": "npm run sass:build",
        "dev": "npm run sass:dev"
    },
    "devDependencies": {
        "sass": "^1.77.0"
    }
}

# Run in development mode
npm run sass:dev

# Build for production
npm run sass:build

Expected output: npm run sass:dev starts watch mode with source maps for development. npm run sass:build compiles compressed CSS without source maps for production.

Code Example: Sass Directory Structure

project/
    src/
        scss/
            main.scss           # Entry point - imports all partials
            _variables.scss     # Variables (underscore = partial)
            _mixins.scss        # Mixins
            _functions.scss     # Custom functions
            _reset.scss         # CSS reset/normalize
            _typography.scss    # Typography styles
            _layout.scss        # Layout and grid
            _components.scss    # Component styles
            _utilities.scss     # Utility classes
            _themes.scss        # Theme variants
    dist/
        css/
            main.css            # Compiled output
            main.css.map        # Source map
    node_modules/
    package.json

// main.scss - entry point
// Imports order matters for cascade

// 1. Variables and config (no output)
@import 'variables';
@import 'functions';
@import 'mixins';

// 2. Base styles
@import 'reset';
@import 'typography';

// 3. Layout
@import 'layout';

// 4. Components
@import 'components';

// 5. Utilities and overrides
@import 'utilities';
@import 'themes';

Code Example: Build Tool Integration

// Vite configuration (vite.config.js)
import { defineConfig } from 'vite';

export default defineConfig({
    css: {
        preprocessorOptions: {
            scss: {
                additionalData: `
                    @import "./src/scss/_variables.scss";
                    @import "./src/scss/_mixins.scss";
                `
            }
        }
    }
});

// Webpack configuration (webpack.config.js)
const path = require('path');

module.exports = {
    module: {
        rules: [
            {
                test: /\.scss$/,
                use: [
                    'style-loader',   // Inject CSS into DOM
                    'css-loader',     // Resolve CSS imports
                    {
                        loader: 'sass-loader',
                        options: {
                            sourceMap: true,
                            sassOptions: {
                                outputStyle: 'compressed'
                            }
                        }
                    }
                ]
            }
        ]
    }
};

Expected output: Vite automatically compiles SCSS when it detects .scss files. Webpack requires the sass-loader. Both support source maps and auto-reload during development.

Common Mistakes

1. Installing globally instead of locally — Global Sass can cause version conflicts. Use local install with npx or npm scripts.
2. Forgetting the underscore in partials — Partial files (_filename.scss) tell Sass not to compile them individually. Without the underscore, each partial generates a separate CSS file.
3. Not using source maps in development — Without source maps, DevTools shows compiled CSS lines instead of SCSS lines, making debugging harder.
4. Committing node_modules or compiled CSS — Add node_modules and dist/css to .gitignore. Compile in CI or postinstall.
5. Using deprecated @import instead of @use — Modern Dart Sass uses @use and @forward. @import is deprecated.
6. Not matching output style to environment — Expanded for development, compressed for production.
7. Ignoring the modern module system — @use loads each file once and scopes variables. Prefer @use over @import.

Practice Questions

1. How do you install Sass in a project? npm install --save-dev sass
2. What is the difference between SCSS and Sass syntax? SCSS uses curly braces and semicolons (like CSS). Sass uses indentation without braces.
3. Why use partial files with leading underscore? The underscore prevents Sass from compiling the partial separately. Partials are only compiled when imported into a main file.
4. What is the purpose of a source map? A source map links compiled CSS back to the original SCSS source, enabling DevTools debugging of the preprocessor code.

FAQ

Mini Project

Set up a complete Sass project from scratch. Install Sass via npm. Create a directory structure with src/scss/ (main.scss + _variables.scss, _mixins.scss, _reset.scss) and dist/css/. Configure package.json scripts for dev (watch + source maps) and build (compressed). Write styles using variables and a mixin. Compile and verify output. Set up a Vite or Webpack project that imports the SCSS. Verify source maps work in DevTools. Add .gitignore for node_modules and dist.

What's Next

Continue with Lesson 3: Sass Variables to learn how to use variables effectively in Sass.