Sass Formatter

0.8.0 · active · verified Sun Apr 19

Sass Formatter is a TypeScript-based utility for automatically formatting Sass, SCSS, CSS, and Less syntax files. It provides consistent code styling by correcting indentation, spacing, and other common formatting issues. The current stable version is 0.8.0, indicating it is still in active development with potential for minor breaking changes before a 1.0 release. It features both a programmatic API for integration into tools and a powerful command-line interface (CLI) for direct file processing and CI/CD pipelines. A key differentiator is its ability to convert CSS or SCSS to Sass syntax, alongside customizable formatting rules through a `.sassformatterrc.json` configuration file. It is notably used in the VS Code Sass extension. While a specific release cadence isn't published, the project is actively maintained with frequent updates.

Common errors

```
Error: Cannot find module 'sass-formatter'
```
cause The 'sass-formatter' package is not installed or the import path is incorrect. It's an ESM-only package.

fix Ensure the package is installed via `npm install sass-formatter` or `yarn add sass-formatter`, and that your project supports ESM imports (e.g., set `"type": "module"` in package.json or use `.mjs` files).
```
sass-formatter: command not found
```
cause The `sass-formatter` CLI tool is not globally installed or its executable path is not in your system's PATH.

fix Install the CLI tool globally using `npm install -g sass-formatter` or ensure `node_modules/.bin` is included in your system's PATH environment variable for local installations.
```
Invalid config file: [path-to-config-file].json
```
cause The custom configuration file specified (e.g., `.sassformatterrc.json`) contains syntax errors, is not valid JSON, or contains unrecognized keys/values.

fix Review the specified configuration file for JSON syntax errors. Refer to the `SassFormatterConfig` interface in the documentation for valid keys and their expected value types.

Warnings

deprecated The `deleteWhitespace` configuration option is deprecated in `SassFormatterConfig`.
Fix: Remove the `deleteWhitespace` key from your `.sassformatterrc.json` or custom configuration file. It may be removed in future versions.
gotcha As a pre-1.0 package, `sass-formatter` may introduce breaking changes in minor versions. Always review release notes carefully when upgrading.
Fix: Consult the project's changelog or GitHub releases for detailed breaking change information before upgrading to a new version.
gotcha When using a custom configuration file, providing unknown keys or invalid values will trigger warnings or an exit code 1, respectively, during CLI execution.
Fix: Ensure all keys in your `.sassformatterrc.json` or custom config file adhere to the `SassFormatterConfig` interface, and that values match the expected types.

Install

npm install sass-formatter npm
yarn add sass-formatter yarn
pnpm add sass-formatter pnpm

Imports

SassFormatter
wrong:
```
const SassFormatter = require('sass-formatter');
```
correct:
```
import { SassFormatter } from 'sass-formatter';
```
Primary class for programmatic formatting. The package is ESM-first, commonJS requires are not supported.

SassFormatterConfig

wrong:

import type { SassFormatterConfig } from 'sass-formatter'; // While valid, explicit 'type' import might be used for clarity in some TS configs.

correct:

import { SassFormatterConfig } from 'sass-formatter';

TypeScript interface for configuring the formatter's behavior. Can be imported for type checking custom configurations.

defaultSassFormatterConfig
wrong:
```
const defaultSassFormatterConfig = require('sass-formatter').defaultSassFormatterConfig;
```
correct:
```
import { defaultSassFormatterConfig } from 'sass-formatter';
```
Provides the default configuration object, useful for merging with custom settings. The package is ESM-first.

Quickstart

Demonstrates how to import and use the `SassFormatter` class to format a Sass string programmatically and print the result.

import { SassFormatter } from 'sass-formatter';

const unformattedSass = `
// This is an unformatted Sass snippet
span
  color: none
  @for $i from 0 through 2
    &:nth-child(#{$i})
        color: none
    @each $author in $list
      .photo-#{$author}
                background: image-url("avatars/#{$author}.png") no-repeat

@while $types > 0
      .while-#{$types}
 width: $type-width + $types
`;

console.log('--- Original Sass ---');
console.log(unformattedSass);

const formattedSass = SassFormatter.Format(unformattedSass);

console.log('\n--- Formatted Sass ---');
console.log(formattedSass);

view raw JSON →