postcss-scss

library4.0.9jsnpmunverified

postcss-scss is a PostCSS syntax parser specifically designed to handle SCSS files, enabling the vast ecosystem of PostCSS plugins to process SCSS source code. Currently at version 4.0.9, this module's primary function is to interpret SCSS constructs such as mixins (parsed as custom at-rules) and variables (parsed as properties). It's crucial to understand that postcss-scss *does not compile SCSS* into standard CSS; instead, it provides an AST (Abstract Syntax Tree) that allows PostCSS plugins to perform transformations directly on SCSS syntax. This bridges the gap between Sass development and PostCSS tooling. While `postcss-scss` itself has an irregular release cadence, it closely follows major PostCSS versions, which are actively maintained.

web-framework

npm install postcss-scss

github ↗package ↗

INSTALL

IMPORT

SIG · POSTCSS-SCSS

postcss-scss

web-frameworkjavascriptv4.0.9

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.

scss

✓ import scss from 'postcss-scss';

✗ import { scss } from 'postcss-scss';

This package is typically imported as a default export for use with PostCSS's `syntax` or `parser` option.

postcssConfig

✓ // postcss.config.mjs export default { syntax: await import('postcss-scss') };

✗ // postcss.config.js module.exports = { syntax: require('postcss-scss') };

For PostCSS configuration files, using `syntax: await import('postcss-scss')` is the recommended modern approach for ESM-based configs, especially since PostCSS 8 and postcss-scss v3 introduced ESM support.

scssParser

✓ const scss = require('postcss-scss');

✗ const { scss } = require('postcss-scss');

For CommonJS environments (e.g., older Node.js scripts or `postcss.config.js` without `type: 'module'` in `package.json`), it's imported as a default export.

Demonstrates how to use `postcss-scss` with PostCSS and `autoprefixer` to process SCSS input. It highlights its role as a parser, not a compiler, allowing PostCSS plugins to transform SCSS syntax into CSS.

import postcss from 'postcss'; import scss from 'postcss-scss'; import autoprefixer from 'autoprefixer'; const scssInput = ` $primary-color: #3498db; .container { display: flex; .item { color: $primary-color; // This is an SCSS inline comment padding: 10px; @include respond-to('medium') { font-size: 16px; } } } `; async function processScss() { try { const result = await postcss([autoprefixer]).process(scssInput, { syntax: scss, from: 'src/style.scss', to: 'dist/style.css' }); console.log('Processed CSS:\n', result.css); console.log('\nWarnings:\n', result.warnings().toString()); } catch (error) { console.error('PostCSS processing failed:', error); } } processScss();

Debug

Known issues

breakingVersion 4.0 removed support for Node.js 10. Users on older Node.js versions must remain on `postcss-scss` v3.x or upgrade their Node.js environment.

fix

Upgrade Node.js to version 12 or higher, or explicitly lock `postcss-scss` to a 3.x version.

affects: >=4.0

breakingWith version 4.0, `postcss` was moved from a direct dependency to a peer dependency. This means `postcss` must now be explicitly installed by the end-user alongside `postcss-scss`.

fix

Ensure `postcss` is installed in your project: `npm install postcss` or `yarn add postcss`.

affects: >=4.0

breakingVersion 3.0 introduced significant breaking changes, including dropping support for Node.js versions 6.x, 8.x, 11.x, and 13.x, and moving to PostCSS 8.0. It also added native ES modules support.

fix

For `postcss-scss` v3+, ensure Node.js is >=10 and `postcss` is >=8.0. Adjust import statements for ES module compatibility if migrating from older versions.

affects: >=3.0

gotcha`postcss-scss` acts as a parser, *not a compiler*. It enables PostCSS plugins to understand and transform SCSS syntax, but it will not compile SCSS features (like nested rules, variables, mixins) into standard CSS on its own.

fix

To compile SCSS, you still need a Sass compiler (e.g., `sass` or `node-sass`) in your build pipeline, typically *before* PostCSS, or use a PostCSS plugin like `@csstools/postcss-sass` if you want to integrate Sass compilation directly within PostCSS.

affects: >=1.0

gotchaWhen processing CSS without a `from` option, PostCSS might generate incorrect source maps and issue warnings, especially with `postcss-scss` where the original file context is important.

fix

Always provide the `from` option in your PostCSS processor configuration (e.g., `processor.process(css, { from: 'path/to/source.scss' })`) to ensure correct source map generation and context. Set it to `undefined` if source map generation is explicitly not desired.

affects: >=1.0

gotcha`postcss-scss` correctly parses SCSS inline comments (`//`). However, the default PostCSS stringifier will convert these to block comments (`/* */`) in the output.

fix

If preserving `//` comments or strictly removing them is required, consider using `postcss-strip-inline-comments` or a custom stringifier.

affects: >=1.0

Errors

Common errors & fixes

Error: Cannot find module 'postcss'

The `postcss` package is a peer dependency and was not explicitly installed alongside `postcss-scss`.

fix

Install `postcss`: `npm install postcss` or `yarn add postcss`.

CssSyntaxError: Missing semicolon

PostCSS attempted to parse SCSS syntax (e.g., nested rules, Sass variables) using the default CSS parser instead of `postcss-scss`.

fix

Ensure `postcss-scss` is correctly configured as the `syntax` or `parser` option for your PostCSS processing, for example: `postcss().process(scssCode, { syntax: require('postcss-scss') })`.

Error: PostCSS plugin <plugin-name> requires PostCSS 8.0+

You are using `postcss-scss` v3+ (which requires PostCSS 8+) with an older version of PostCSS.

fix

Upgrade your PostCSS installation to version 8 or higher: `npm install postcss@^8` or `yarn add postcss@^8`.

Error: `Node.js 10` is no longer supported.

You are trying to use `postcss-scss` v4.x with an unsupported Node.js version (Node.js 10 or older).

fix

Upgrade your Node.js environment to version 12 or newer. Alternatively, downgrade `postcss-scss` to a 3.x version if Node.js upgrade is not possible.

Upgrade

Version history

4.0.9latest on npm

Audit

Dependencies

postcssrequiredRequired as a peer dependency for PostCSS to use this as a syntax parser.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/postcss/postcss-scss ↗

packagehttps://www.npmjs.com/package/postcss-scss ↗