@unsonet/css-builder

A fast, lightweight, and isomorphic library for compiling SCSS/SASS into CSS.

Key Features:

• 🌳 Isomorphic: Works seamlessly in both Node.js and browser environments.
• 🗺️ Source Maps: Built-in support for generating .map files.
• ⚡ Dual Output: Returns both expanded and minified (compressed) CSS in a single call.
• 🛡️ Cross-Platform: Handles Windows backslash (\) paths in @import / @use automatically.
• 📦 Banners: Easily inject custom comments or auto-generated package version headers.

---

Installation

pnpm add @unsonet/css-builder sass

(Note: sass is a peer dependency and must be installed in your project).

---

Usage

In Node.js (Programmatic API)

By passing the filePath option, the library uses Sass's File Compiler under the hood. This provides the fastest compilation, perfect Source Map resolution, and native handling of OS-specific path separators.

import { buildCssBundle } from '@unsonet/css-builder';
import { resolve } from 'node:path';

async function build() {
  const result = await buildCssBundle('', { // Pass empty string, file is read by filePath
    filePath: resolve(__dirname, 'src/styles.scss'),
    sourceMap: true,
    sourceMapIncludeSources: true,
  });

  console.log(result.css);             // Expanded CSS
  console.log(result.minifiedCss);     // Compressed CSS
  console.log(result.sourceMap);       // Source Map JSON string
  console.log(result.minifiedSourceMap);// Minified Source Map JSON string
}

In the Browser

Pass the raw SCSS string and a url so Sass can correctly resolve relative @use and @import statements.

import { buildCssBundle } from '@unsonet/css-builder';

const scssCode = `
  $primary: blue;
  body { color: $primary; }
  @use 'variables';
`;

const result = await buildCssBundle(scssCode, {
  url: new URL('http://localhost/styles.scss'),
  sourceMap: true,
});

CLI

The package includes a powerful CLI tool for build scripts. It reads from a file or stdin and outputs to files or stdout.

Global Installation (optional)

pnpm add -g @unsonet/css-builder

Commands

Build from a file:

css-builder --input src/styles.scss --out dist/styles.css --out-min dist/styles.min.css --source-map true

Read from stdin (pipe):

cat src/styles.scss | css-builder --out dist/styles.css

CLI Options

Option	Description
--input	Path to the input SCSS/SASS file. If omitted, reads from stdin.
--out	Path to write the expanded CSS. If omitted, outputs to stdout.
--out-min	Path to write the minified CSS.
--package	Path to a package.json file to automatically extract name and version for the banner.
--name	Override the package name in the banner.
--version	Override the package version in the banner.
--banner	Provide a completely custom banner string.
--syntax	Force syntax: auto (default), scss, css, or indented.
--source-map	Enable source map generation (true / false). If enabled, writes .map files next to the CSS files.

---

API Reference

buildCssBundle(input, options?)

Compiles SCSS/SASS string or file into CSS objects.

Parameters:

• input (string): The raw SCSS/SASS source code. (Can be an empty string if filePath is provided in Node.js).
• options (CssBuilderOptions): Configuration object.

Returns: Promise<CssBuilderOutput>

CssBuilderOptions

Property	Type	Default	Description
filePath	string	undefined	(Node.js only) Absolute path to the file. Skips string parsing, resolves @import natively.
url	URL	undefined	(Browser/Stdin) Base URL for resolving imports in string compilation.
filename	string	undefined	Filename used strictly for auto-detecting syntax if syntax: 'auto'.
syntax	'auto' | 'scss' | 'css' | 'indented'	'auto'	Forces a specific Sass syntax.
sourceMap	boolean	false	Enables Source Map generation.
sourceMapIncludeSources	boolean	true	Includes the original SCSS contents inside the Source Map.
packageName	string	'@unsonet/css-builder'	Name used in the auto-generated banner.
version	string	undefined	Version used in the auto-generated banner.
banner	string	undefined	Custom banner. Overrides auto-generation.
...	...	...	Also supports standard Sass options: importers, functions, logger, quietDeps, charset.

CssBuilderOutput

Property	Type	Description
css	string	Compiled CSS with an auto-generated (or custom) banner.
minifiedCss	string	Minified CSS with a banner.
sourceMap	string	JSON string of the Source Map (if enabled).
minifiedSourceMap	string	JSON string of the minified Source Map (if enabled).

---

License

MIT