npm package: @orqest-ai/scss-parser
Description: This utility can be used to extract structured variables from sass files.
Author: Laure Ladastra
Latest version: 1.3.0

# SCSS Parser

A lightweight JavaScript module that parses top level SCSS (Sass) variables and converts them into structured JavaScript objects. Perfect for implementation in React components.

|          |                                                                                                                                                                                                                     |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Version  | [<img src="https://img.shields.io/badge/version-1.3.0-blue.svg">](html/package.json)                                                                                                                                |
| Pipeline | [![Build Status](https://dev.azure.com/quantaleap/Orqest%20AI/_apis/build/status%2Forqest.scss-parser?branchName=main)](https://dev.azure.com/quantaleap/Orqest%20AI/_build/latest?definitionId=53&branchName=main) |
| NPM      | ![NPM Downloads](https://img.shields.io/npm/dw/%40orqest-ai%2Fscss-parser?logo=npm&labelColor=red&color=grey)                                                                                                       |
|          |

## Why?

The current alternatives [`sass-extract`](https://www.npmjs.com/package/sass-extract) and [`sass-extract-js`](https://www.npmjs.com/package/sass-extract-js) are based on the fully deprecated [`node-sass`](https://www.npmjs.com/package/node-sass), which isn
't maintained anymore and doesn't run on several system architectures (MacOS Intel x64 included). Additionally, the libraries have heavy dependencies that should not be expected for this type of functionality.

## Features

- **VanillaJS** - No dependencies, works in any JavaScript environment
- **SCSS Features** - Variables, mixins, nested rules, at-rules (@media, @import, etc.)
- **Comment Removal** - Handles both single-line (`//`) and multi-line (`/* */`) comments

## Installation

```bash
yarn add @orqest-ai/scss-parser

or

npm install @orqest-ai/scss-parser
```

## Usage

```javascript
import { parseScss } from "@orqest-ai/scss-parser"

const scssContent = `
$primary-color: #3498db;
$margin: 20px;

.header {
  background-color: $primary-color;
  margin: $margin;
  color: white;
}
`

const result = parseScss(scssContent)
console.log(result)
```

## Output

The parser returns an object with the following structure:

```javascript
{
  variables: {
    "$variable-name": "value"
  },
  mixins: {
    "mixin-name": [
      { property: "property-name", value: "value" }
    ]
  },
  rules: [
    {
      type: "rule",
      selector: ".class-name",
      declarations: [
        { property: "property-name", value: "value" }
      ]
    }
  ]
}
```

## API Reference

#### `parseScss(scssContent: string, options: object): ParsedSCSS` - Function

Parses SCSS content and returns a structured JavaScript object.

**Parameters:**

- `scssContent` (string) - the SCSS content to parse
- `options` (object)
  - trimVariableNames (boolean) - specify whether to strip the leading `$` character from SCSS variables

**Returns:**

- `ParsedSCSS` (object) - containing variables, mixins, and rules

#### `SCSSParser` - Class

For advanced usage, you can use the parser class directly:

```javascript
import { SCSSParser } from "@orqest-ai/scss-parser"

const parser = new SCSSParser()
const result = parser.parse(scssContent)
```

## Contribution

This module was quickly bootstrapped based for our specific (and limited) needs. As a result it lacks some of the more robust features:

- full validation of SCSS/CSS based on the technical spec, including support for functions in both languages (`attr()`, `darken()`, etc.)
- transpilation of nested objects

All types of contributions are encouraged to develop this module into something that could be useful for more people in the community.