Registry / serialization / sass-parser

sass-parser

JSON →
library0.4.44jsnpmunverified

sass-parser (current version 0.4.44) is a JavaScript library that provides a PostCSS-compatible API for parsing Sass and CSS. It serves as a wrapper around the official Dart Sass parser, aiming to offer a fully compatible parsing solution for both Sass and indented Sass syntax, which addresses known limitations of previous PostCSS plugins like `postcss-scss`. The project is under active development and, as of its current version, is explicitly not recommended for production use due to its incomplete support for all CSS and Sass syntax features and its lack of support for parsing raw metadata (which is crucial for certain source-to-source transformations). Its release cadence is independently managed but benefits from updates to the underlying Dart Sass project (which is currently at version 1.99.0). This library is primarily for developers building PostCSS plugins or tools that require programmatic access to the Sass Abstract Syntax Tree (AST) with PostCSS compatibility.

serialization
npm install sass-parser
github ↗package ↗
INSTALL
IMPORT
SIG · SASS-PARSER
S
sass-parser
serializationjavascriptv0.4.44
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

sassParser
✓ import * as sassParser from 'sass-parser';
✗ const sassParser = require('sass-parser').default;
For ESM environments, a namespace import is common. The `require` pattern is for CommonJS.
scss
✓ import { scss } from 'sass-parser';
✗ import sassParser from 'sass-parser'; const scss = sassParser.scss;
Named export for the SCSS syntax parser. Other parsers like `sass` and `css` are also available as named exports.
Syntax objects
✓ const { scss, sass, css } = require('sass-parser');
✗ const scss = require('sass-parser').scss;
CommonJS pattern for destructuring the various syntax parsers.

This quickstart demonstrates how to import and use the `scss` parser to transform a Sass string into an Abstract Syntax Tree (AST), then modify the AST using PostCSS-compatible methods, and finally serialize it back to a string. It showcases basic node manipulation and Sass-specific property access.

import { scss } from 'sass-parser'; const rawSass = `@use 'colors';\n\nbody {\n color: colors.$midnight-blue;\n}\n.container {\n font-size: 1rem;\n padding: 10px;\n}\n`; // Parse the Sass string into a PostCSS-compatible AST const root = scss.parse(rawSass); // Access and modify the AST using PostCSS-like APIs const styleRule = root.nodes[1]; // Assuming body is the second node if (styleRule && styleRule.type === 'rule') { styleRule.selector = '.main-container'; } // Access Sass-specific nodes (e.g., @use rule, variable expressions) const useRule = root.nodes[0]; // Assuming @use is the first node if (useRule && useRule.type === 'atrule' && useRule.name === 'use') { useRule.namespace = 'c'; // Change namespace from 'colors' to 'c' } // Assuming the variable expression is within the modified style rule const colorDecl = styleRule.nodes.find(node => node.type === 'decl' && node.prop === 'color'); if (colorDecl && colorDecl.valueExpression && colorDecl.valueExpression.type === 'variable') { colorDecl.valueExpression.namespace = 'c'; } console.log(root.toString()); /* Expected Output: @use 'colors' as c; .main-container { color: c.$midnight-blue; } .container { font-size: 1rem; padding: 10px; } */
Debug
Known issues
breaking`sass-parser` is currently in active development (version 0.x.x) and is not yet considered suitable for production use. It supports only a subset of CSS and Sass syntax, which may lead to unexpected parsing errors with complex stylesheets.
fix
Use for experimental purposes or in environments where the parsed Sass subset is guaranteed to be compatible. Monitor its development and release candidates for production readiness.
affects: >=0.1.0
gotchaThe package does not currently support parsing 'raws' (metadata about original formatting). This limitation means that source-to-source transformations that rely on preserving or manipulating original whitespace, comments, or other formatting details may not function as expected.
fix
Be aware that formatting information might be lost or altered upon serialization. For transformations requiring raw preservation, this parser might be unsuitable.
affects: >=0.1.0
breakingThis package requires Node.js version 18.0.0 or higher. Running it with older Node.js versions will result in runtime errors.
fix
Ensure your Node.js environment is at least version 18.0.0. Use `nvm install 18 && nvm use 18` or update your Node.js installation.
affects: <0.4.0
gotchaThe version of `sass-parser` (e.g., 0.4.44) is independent of the underlying Dart Sass compiler version (e.g., 1.99.0). Changes and deprecations in Dart Sass releases may not immediately be reflected or fully supported in `sass-parser`'s API or parsing capabilities.
fix
Consult `sass-parser`'s own changelog and documentation for specific feature support and breaking changes related to its API, rather than relying solely on Dart Sass releases.
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'parse')
Attempting to call `parse` on the top-level `sassParser` object directly, or trying to use a syntax parser (e.g., `scss`) without proper destructuring or access.
fix
Ensure you are calling `.parse` on one of the exposed syntax objects (e.g., `sassParser.scss.parse()`) and that the `scss`, `sass`, or `css` objects are correctly imported or accessed. For CommonJS: `const { scss } = require('sass-parser');` or `const sassParser = require('sass-parser'); const root = sassParser.scss.parse(cssString);`.
Error: Unknown word (CSS parsing error)
The parser encountered Sass-specific syntax or an advanced CSS feature that is not yet supported in this experimental version of `sass-parser`.
fix
Simplify the input Sass/CSS to use only basic, widely supported syntax. Refer to `sass-parser`'s documentation to understand the current scope of supported features. Report unsupported syntax as an issue to the project maintainers.
Error: Node.js version 16.x.x is not supported. Please upgrade to Node.js >= 18.0.0.
The installed Node.js version does not meet the minimum requirement specified in the package's `engines` field.
fix
Upgrade your Node.js environment to version 18.0.0 or later. Consider using a Node Version Manager (NVM) to manage multiple Node.js versions.
Upgrade
Version history
0.4.44latest on npm
Audit
Dependencies
postcssrequiredThis package provides a PostCSS-compatible API and is designed to integrate with the PostCSS ecosystem for stylesheet transformations.
Agent activity
4 hits · last 30 days
node
4
Resources
githubhttps://github.com/sass/dart-sass ↗
packagehttps://www.npmjs.com/package/sass-parser ↗
sass-parser — npm install sass-parser · libregistry