find-unused-sass-variables

A small tool to find unused Sass variables in a directory.

Install

npm install find-unused-sass-variables --save-dev

CLI

Usage

fusv <folders...> [options]
# or the full alias
find-unused-sass-variables <folders...> [options]

One or more folder paths can be passed at once.

Options

| Flag | Alias | Description | Default | |---|---|---|---| | --ignore <variables> | -i | Comma-separated variable names to skip (e.g. $my-var,$another) | - | | --ignoreFiles <files> | -if | Comma-separated file glob patterns to skip (e.g. **/_variables.scss) | - | | --extension [types...] | -e | File extension(s) to scan. Repeatable or comma-separated. | scss | | --help | | Print help | - |

Examples

# Scan a single folder
fusv src/

# Scan multiple folders
fusv src/ themes/

# Ignore specific variables
fusv src/ --ignore='$my-var,$another-var'

# Ignore files matching a glob
fusv src/ --ignoreFiles='**/_variables.scss'

# Scan .scss and .css files
fusv src/ -e scss -e css

# Combine options
fusv src/ --ignore='$unused' --ignoreFiles='**/vendor/**' -e scss -e sass

Shell quoting On Unix/macOS, quote the value to prevent the shell from expanding $ (e.g. --ignore='$my-var'). On Windows CMD, no quoting is needed (e.g. --ignore=$my-var).

Exit codes

| Code | Meaning | |---|---| | 0 | No unused variables found | | 1 | One or more unused variables found (or an error occurred) |

API

import { find, findAsync } from 'find-unused-sass-variables';

find(dir, options?)

Synchronous. Scans dir and returns the result immediately.

find(dir: string, options?: Options): Result

findAsync(dir, options?)

Asynchronous. Same behaviour as find, but returns a Promise.

findAsync(dir: string, options?: Options): Promise<Result>

Options

| Property | Type | Description | Default | |---|---|---|---| | ignore | string[] | Variable names to skip, e.g. ['$my-var', '$brand-color'] | [] | | ignoreFiles | string[] | File glob patterns to skip, e.g. ['**/_variables.scss'] | [] | | fileExtensions | string[] | Extensions to scan (leading dot optional), e.g. ['scss', 'css'] | ['scss'] |

Return value

Both functions return (or resolve to):

| Property | Type | Description | |---|---|---| | unused | { name: string, file: string, line: number }[] | Variables declared but never referenced | | total | number | Total variables found across all scanned files |

Each entry in unused:

| Field | Type | Description | |---|---|---| | name | string | Variable name, e.g. '$my-color' | | file | string | Path to the file containing the variable | | line | number | Line number of the variable |

Examples

Synchronous

import { find } from 'find-unused-sass-variables';

const result = find('src/');
console.log(result.total);   // total variables found
console.log(result.unused);  // [{ name: '$unused-color', file: 'src/_colors.scss', line: 12 }, ...]

Asynchronous

import { findAsync } from 'find-unused-sass-variables';

const result = await findAsync('src/');
console.log(result.total);
console.log(result.unused);

With options

import { find } from 'find-unused-sass-variables';

const result = find('src/', {
  ignore: ['$my-var', '$brand-color'],
  ignoreFiles: ['**/_variables.scss', '**/vendor/**'],
  fileExtensions: ['scss', 'css']
});

Disable and enable scanning

Wrap any region with fusv-disable / fusv-enable comments to exclude those variables from analysis. Both inline (//) and block (/* */) comment styles are supported.

$used-variable-1: #666;

// fusv-disable
$intentionally-unused: #coffee; // will NOT be reported
// fusv-enable

$used-variable-2: #ace;

/* fusv-disable */
$intentionally-unused: #coffee;
/* fusv-enable */

Notes

• The tool's logic is pretty "dumb"; if you use the same name for a variable in different files or namespaces, then it won't distinguish between them.
• The tool only looks for .scss files by default, but you can optionally specify the file extensions.

License

MIT