stenciljs/sass

Sass plugin for Stencil

Summary

@stencil/sass is a Stencil plugin that precompiles Sass files referenced by Stencil components into CSS during the build. It uses the pure JavaScript sass package, replacing the older node-sass implementation, and plugs into Stencil's plugin system. It also participates in the Stencil v5 CLI wizard for new project setup and component scaffolding.

What it is useful for

This plugin is useful when a Stencil project wants to author component styles in .scss or .sass instead of plain CSS. It handles precompilation transparently, so engineers can write Sass in component files without configuring a separate build step.

The injectGlobalPaths option makes it practical to share Sass variables, mixins, and functions across components — the README specifically calls out overriding default Sass variables of @ionic/core as a use case. The quietDeps and silenceDeprecations options are useful for cleaning up build output when working with dependencies that emit Sass warnings or deprecated syntax.

How engineers can use it

Install the plugin as a dev dependency:

npm install @stencil/sass --save-dev

Then add it to stencil.config.ts:

import { Config } from '@stencil/core';
import { sass } from '@stencil/sass';

export const config: Config = {
  plugins: [
    sass({
      // optional config options
    }),
  ],
};

For new projects, the README documents that npx stencil init followed by selecting Sass wires this up automatically, and stencil generate will offer .scss and .sass as stylesheet choices when scaffolding a component.

To share global Sass across components, list file paths in injectGlobalPaths:

sass({
  injectGlobalPaths: ['src/globals/variables.scss', 'src/globals/mixins.scss'],
})

A documented caveat: each file is added to every component, so these files should not contain CSS rules (which would be duplicated) — only variables, mixins, and functions. Relative paths in injectGlobalPaths are resolved from the Stencil config file. The component's own directory is automatically added to includePaths.

Any other Sass options can be passed through to the plugin; the README points to the sass package documentation for the full list. Engineers migrating from earlier versions that used node-sass should consult the "Behavioral Differences from Ruby Sass" doc linked in the README if they encounter unexpected behavior.

One factual note: the repository metadata reports the license as NOASSERTION, so teams should verify licensing terms directly with the maintainers before redistribution.