{"id":13984,"library":"scss-comment-parser","title":"SCSS Comment Parser","description":"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.","status":"maintenance","version":"0.8.4","language":"javascript","source_language":"en","source_url":"https://github.com/SassDoc/scss-comment-parser","tags":["javascript"],"install":[{"cmd":"npm install scss-comment-parser","lang":"bash","label":"npm"},{"cmd":"yarn add scss-comment-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add scss-comment-parser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for parsing C-style comments and code context. Referenced in changelog multiple times for updates.","package":"cdocparser","optional":false}],"imports":[{"note":"This package primarily exposes a class/constructor via CommonJS `module.exports`. This is the intended and most reliable import method for CommonJS environments.","symbol":"ScssCommentParser","correct":"const ScssCommentParser = require('scss-comment-parser');"},{"note":"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.","wrong":"import { ScssCommentParser } from 'scss-comment-parser';","symbol":"ScssCommentParser (ESM default)","correct":"import ScssCommentParser from 'scss-comment-parser';"},{"note":"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.","wrong":"const ScssCommentParser = await import('scss-comment-parser');","symbol":"ScssCommentParser (dynamic ESM)","correct":"const ScssCommentParser = (await import('scss-comment-parser')).default;"}],"quickstart":{"code":"const ScssCommentParser = require('scss-comment-parser');\n\nconst annotations = {\n  _: {\n    alias: {\n      'aliasTest': 'annotationTest'\n    }\n  },\n  annotationTest: function ( commentLine ) {\n    return 'Working';\n  }\n};\n\nconst parser = new ScssCommentParser( annotations );\n\nconst scss = `\n/// @annotationTest\n/// This is a test comment for a variable.\n$my-variable: #ff00ff;\n\n/// @param {string} $name - The name to greet.\n/// This mixin generates a greeting style.\n@mixin greet($name) {\n  .greeting-#{$name} { color: blue; }\n}\n\n/// A placeholder for common base styles.\n%base-styles {\n  margin: 0;\n  padding: 0;\n}\n\n/// @example\n///   .some-class { @extend %base-styles; }\n.some-selector { /* some styles */ }\n`;\n\nconst comments = parser.parse( scss );\n\nconsole.log(JSON.stringify(comments, null, 2));\n/* Expected output (truncated):\n[\n  {\n    \"context\": {\n      \"type\": \"variable\",\n      \"name\": \"my-variable\",\n      \"value\": \"#ff00ff\",\n      \"code\": \"$my-variable: #ff00ff;\",\n      \"line\": {\n        \"start\": 4,\n        \"end\": 4\n      }\n    },\n    \"description\": \"This is a test comment for a variable.\",\n    \"annotations\": {\n      \"annotationTest\": [\n        \"Working\"\n      ]\n    }\n  },\n  {\n    \"context\": {\n      \"type\": \"mixin\",\n      \"name\": \"greet\",\n      \"args\": \"($name)\",\n      \"code\": \"@mixin greet($name) {\\n  .greeting-#{$name} { color: blue; }\\n}\",\n      \"line\": {\n        \"start\": 8,\n        \"end\": 10\n      }\n    },\n    \"description\": \"This mixin generates a greeting style.\",\n    \"annotations\": {\n      \"param\": [\n        \"{string} $name - The name to greet.\"\n      ]\n    }\n  },\n  // ... and other parsed contexts\n]\n*/","lang":"javascript","description":"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."},"warnings":[{"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.","message":"In 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.","severity":"breaking","affected_versions":">=0.2.4"},{"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.","message":"This 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The 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).","severity":"gotcha","affected_versions":">=0.4.0"}],"env_vars":null,"search_vec":"'0.8.4':46 '2018':57 'abil':81 'allow':101 'annot':99 'associ':117 'block':114 'bug':63 'code':110,118 'comment':2,6,16,78,113 'compon':36 'context':23,86 'core':35 'css':93 'current':42 'custom':98 'cycl':53 'definit':100 'depend':66 'design':12 'detail':84 'differenti':69 'document':31,104 'extract':21,83 'file':19 'fix':64 'flexibl':103 'focus':73 'function':90 'generat':30,105 'identifi':112 'includ':70,87 'inform':24 'javascript':10,124 'json':122 'key':68 'last':54 'librari':11 'like':39 'mainten':60 'mixin':89 'output':123 'pars':14 'parser':3,7 'placehold':91 'primarili':27 'process':108 'provid':119 'rapid':51 'receiv':59 'releas':52 'sassdoc':40,76 'sassdoc-styl':75 'scss':1,5,18,85,109 'scss-comment-pars':4 'selector':94 'serv':32 'specif':72 'stabl':43 'structur':22,121 'style':15,77 'support':96 'syntax':79 'tool':38 'updat':55,61 'upgrad':67 'use':28 'variabl':88 'version':44 'within':17 'workflow':106","created_at":"2026-04-20T01:57:19.465017+00:00","updated_at":"2026-04-20T01:57:19.465017+00:00","problems":[{"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.","cause":"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.","error":"TypeError: ScssCommentParser is not a constructor"},{"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()`.","cause":"The `parser` object is undefined or null, indicating `ScssCommentParser` was not correctly imported or instantiated, or the `new` keyword was omitted.","error":"TypeError: Cannot read properties of undefined (reading 'parse')"},{"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).","cause":"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`).","error":"ReferenceError: require is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/SassDoc/scss-comment-parser","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/scss-comment-parser","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}