Registry / serialization / scss-comment-parser

scss-comment-parser

JSON →
library0.8.4jsnpmunverified

scss-comment-parser is a JavaScript library designed to parse `///` style comments within SCSS files and extract structured context information. It is primarily used to generate documentation, serving as a core component for tools like SassDoc. The current stable version is 0.8.4. While not on a rapid release cycle (last updated in 2018), it receives maintenance updates for bug fixes and dependency upgrades. Key differentiators include its specific focus on SassDoc-style comment syntax, its ability to extract detailed SCSS context (including variables, mixins, functions, placeholders, and CSS selectors), and support for custom annotation definitions, allowing for flexible documentation generation workflows. It processes SCSS code to identify comment blocks and their associated code, providing a structured JSON output.

serialization
npm install scss-comment-parser
github ↗package ↗
INSTALL
IMPORT
SIG · SCSS-COMMENT-PARSE
S
scss-comment-parser
serializationjavascriptv0.8.4
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.

ScssCommentParser
✓ const ScssCommentParser = require('scss-comment-parser');
This package primarily exposes a class/constructor via CommonJS `module.exports`. This is the intended and most reliable import method for CommonJS environments.
ScssCommentParser (ESM default)
✓ import ScssCommentParser from 'scss-comment-parser';
✗ import { ScssCommentParser } from 'scss-comment-parser';
For ES Module environments, a default import (`import ScssCommentParser from ...`) might work with bundlers or Node.js's CJS interop, as it often resolves to `module.exports`. However, `import { ScssCommentParser } from ...` is incorrect as there's no named export of this class.
ScssCommentParser (dynamic ESM)
✓ const ScssCommentParser = (await import('scss-comment-parser')).default;
✗ const ScssCommentParser = await import('scss-comment-parser');
In an asynchronous ES Module context, dynamic `import()` can be used to load this CommonJS package. Always access the `.default` property to get the actual constructor function.

Initializes the parser with custom annotations, processes a sample SCSS string containing various comment types and code contexts, and logs the extracted documentation data in a formatted JSON output.

const ScssCommentParser = require('scss-comment-parser'); const annotations = { _: { alias: { 'aliasTest': 'annotationTest' } }, annotationTest: function ( commentLine ) { return 'Working'; } }; const parser = new ScssCommentParser( annotations ); const scss = ` /// @annotationTest /// This is a test comment for a variable. $my-variable: #ff00ff; /// @param {string} $name - The name to greet. /// This mixin generates a greeting style. @mixin greet($name) { .greeting-#{$name} { color: blue; } } /// A placeholder for common base styles. %base-styles { margin: 0; padding: 0; } /// @example /// .some-class { @extend %base-styles; } .some-selector { /* some styles */ } `; const comments = parser.parse( scss ); console.log(JSON.stringify(comments, null, 2)); /* Expected output (truncated): [ { "context": { "type": "variable", "name": "my-variable", "value": "#ff00ff", "code": "$my-variable: #ff00ff;", "line": { "start": 4, "end": 4 } }, "description": "This is a test comment for a variable.", "annotations": { "annotationTest": [ "Working" ] } }, { "context": { "type": "mixin", "name": "greet", "args": "($name)", "code": "@mixin greet($name) {\n .greeting-#{$name} { color: blue; }\n}", "line": { "start": 8, "end": 10 } }, "description": "This mixin generates a greeting style.", "annotations": { "param": [ "{string} $name - The name to greet." ] } }, // ... and other parsed contexts ] */
Debug
Known issues
breakingIn version 0.2.4, the `context.code` property for parsed code blocks was modified. It now removes the first opening and last closing brace, which could break consumers relying on the exact raw code string content.
fix
Review existing code that processes `context.code` and adjust expectations for the content format. Manual re-addition of braces might be necessary if the raw string is critical.
affects: >=0.2.4
gotchaThis library is distributed as a CommonJS module. Using direct ES Module `import` statements (`import ScssCommentParser from 'scss-comment-parser'`) in pure ESM environments might result in `TypeError: ScssCommentParser is not a constructor` or other import errors if not correctly handled by the runtime or bundler.
fix
For CommonJS, use `const ScssCommentParser = require('scss-comment-parser');`. For ES Modules, consider using a dynamic import (`import('scss-comment-parser').then(module => new module.default(...))`) or explicitly handling CommonJS interop.
affects: >=0.1.0
gotchaThe package has undergone multiple internal dependency updates to `cdocparser` (e.g., 0.7.0, 0.6.0, 0.5.x, 0.4.0). While the public API of `scss-comment-parser` may appear stable, these underlying changes could subtly alter the structure or content of the parsed output (e.g., `context.line` properties, context detection).
fix
Thoroughly test parsed output when upgrading `scss-comment-parser` to ensure no regressions or unexpected changes in the extracted comment and context data occur.
affects: >=0.4.0
Errors
Common errors & fixes
TypeError: ScssCommentParser is not a constructor
Attempting to instantiate `ScssCommentParser` when the imported value is not the constructor function itself, often due to incorrect ES Module import syntax for a CommonJS module or an incorrect alias.
fix
Ensure you are using `const ScssCommentParser = require('scss-comment-parser');` for CommonJS. If in ESM, try `import * as ScssCommentParserModule from 'scss-comment-parser'; const ScssCommentParser = ScssCommentParserModule.default;` or the dynamic import pattern.
TypeError: Cannot read properties of undefined (reading 'parse')
The `parser` object is undefined or null, indicating `ScssCommentParser` was not correctly imported or instantiated, or the `new` keyword was omitted.
fix
Verify that `require('scss-comment-parser')` successfully returns the constructor and that `new ScssCommentParser(...)` is called with valid arguments before attempting to call `.parse()`.
ReferenceError: require is not defined
Attempting to use `require()` in an ES Module context where it is not globally available without specific configuration (e.g., in a `.mjs` file or when `type: "module"` is set in `package.json`).
fix
For modern Node.js ESM environments, switch to `import` syntax or use a dynamic `import()`. If strictly needing `require`, ensure your file is treated as CommonJS (e.g., `.js` extension without `type: "module"` in `package.json`, or `.cjs` extension).
Upgrade
Version history
0.8.4latest on npm
Audit
Dependencies
cdocparserrequiredCore dependency for parsing C-style comments and code context. Referenced in changelog multiple times for updates.
Agent activity
6 hits · last 30 days
node
6
Resources
githubhttps://github.com/SassDoc/scss-comment-parser ↗
packagehttps://www.npmjs.com/package/scss-comment-parser ↗
scss-comment-parser — npm install scss-comment-parser · libregistry