string-extract-sass-vars^4.2.0

Installation

Quick Take

Examples

• Ignore variables inside both Sass comment styles
• Convert number-only Sass values to JavaScript numbers
• Convert 3-digit color hex codes to 6-digit
• Keep semicolons that occur inside a quoted value
• Raises alarm if variables file has been wiped

API — extractVars()

The main function extractVars() is imported like this:

It’s a function which takes two input arguments:

For example, a typical input string for this program:

$red: #ff6565;
$blue: #08f0fd;

The Optional Options Object has the following shape:

Here are all defaults in one place for copying:

Function returns a plain object of zero or more SASS file’s key-value pairs.

For example, a typical output of this program:

{
  red: "#ff6565",
  blue: "#08f0fd"
}

API — defaults

You can import defaults:

It's a plain object:

The main function calculates the options to be used by merging the options you passed with these defaults.

API — version

You can import version:

API — types

This package is written in TypeScript and exports the following types:

import type { Opts, UnknownValueObj } from "string-extract-sass-vars";

opts.throwIfEmpty

In production, you have many things to worry about. Imagine something went wrong with your SCSS variables file — or it was mangled — or something else went wrong — this program would find no variables and would yield an empty plain object. But you would not notice.

If you know that there will always be at least one key in the extracted source — set opts.throwIfEmpty — it will throw an error instead of silently yielding an empty plain object.

By default, this option is disabled.

opts.cb

Think of it as a middleware — if you pass a function, then before placing the extracted value into a result object, this program will feed that value into your function and use function’s result instead.

This gives opportunities to process the values, for example, turning 3-digit hex colour numbers into email-friendly 6-digit:

What this program doesn’t do

This program is a quick parser for variables files or simple key-value pair SASS style content. It’s not a fully-fledged SASS code parser.

Ensure the input file is a simple SCSS variables file:

• No nesting
• No partials
• No modules
• No mixins
• No extend/inheritance
• No operators

Why do you need this

Sometimes you want to use CSS variables in the inline HTML styles. For example, <span style="color: {{ textGrey }};"></span>.

It depends on what templating engine you use, but in case of Nunjucks, you need to load the variable textGrey into Nunjucks global Environment.

In Gulp (or Eleventy or other script which runs everything) you use Node fs.readFileSync to read the PostCSS/SASS variables file, containing line $textGrey: #ccc;. Then you feed that outout into this program which parses and extracts a plain object: { textGrey: "#ccc" }. Then you load it into Nunjucks global Environment.

After that, <span style="color: {{ textGrey }};"></span> is rendered into <span style="color: #ccc;"></span>.

Conceptually, global variables in HTML and CSS let you DRY the code — there’s single source of truth for constants. In React component-based web development Storybook-documented colour constants is a similar thing.

And global variables are not just for HTML inline CSS use:

1. You can put Nunjucks globals into SASS variables file — your CSS won’t use them but all global constants will be in one place: both CSS and Nunjucks.
2. Template’s logic can use SASS variables file values in calculations (imagine, column count).

Changelog