sass-graph

What is sass-graph?

The sass-graph npm package is a utility that helps in analyzing the dependencies of Sass files in a project. It parses Sass files to find all the `@import` statements and constructs a graph of the relationships between files. This is particularly useful for understanding and managing complex stylesheets structures in large projects.

What are sass-graph's main functionalities?

Parsing a directory of Sass files

This feature allows you to parse an entire directory of Sass files to create a graph representing the dependencies between them.

const sassGraph = require('sass-graph');
const graph = sassGraph.parseDir('path/to/sass/files');

Finding dependencies of a single Sass file

This feature is used to find all the files that depend on a single Sass file, which can be useful for understanding the impact of changes to that file.

const sassGraph = require('sass-graph');
const graph = sassGraph.parseFile('path/to/sass/file.scss', options);
const dependencies = graph.index['path/to/sass/file.scss'].importedBy;

Watching a directory of Sass files for changes

This feature sets up a watcher on a directory of Sass files and triggers a callback with the changed files when a change is detected.

const sassGraph = require('sass-graph');
const graph = sassGraph.parseDir('path/to/sass/files');
sassGraph.watch('path/to/sass/files', options, (changedFiles) => {
  console.log('Files changed:', changedFiles);
});

Other packages similar to sass-graph

postcss

PostCSS is a tool for transforming CSS with JavaScript plugins. While it is not limited to Sass, it can be used to analyze and manipulate CSS dependencies, similar to how sass-graph analyzes Sass dependencies.

node-sass-magic-importer

node-sass-magic-importer is a custom importer for node-sass that adds additional features to the standard Sass `@import` rule. It provides functionalities that can help manage dependencies, but it is more focused on extending the import capabilities rather than analyzing the dependency graph.

stylelint

Stylelint is a linter for stylesheets that can be used to enforce consistent conventions and avoid errors in stylesheets. It does not construct a dependency graph like sass-graph, but it can be used to analyze and lint the structure of Sass files.

README

Sass Graph

Parses Sass files in a directory and exposes a graph of dependencies

Install

Install with npm

npm install --save-dev sass-graph

Usage

Usage as a Node library:

var sassGraph = require('./sass-graph');

Usage as a command line tool:

The command line tool will parse a graph and then either display ancestors, descendents or both.

$ ./bin/sassgraph --help
Usage: bin/sassgraph <command> [options] <dir> [file]

Commands:
  ancestors    Output the ancestors
  descendents  Output the descendents

Options:
  -I, --load-path   Add directories to the sass load path
  -e, --extensions  File extensions to include in the graph
  -j, --json        Output the index in json
  -h, --help        Show help
  -v, --version     Show version number

Examples:
  ./bin/sassgraph descendents test/fixtures test/fixtures/a.scss
  /path/to/test/fixtures/b.scss
  /path/to/test/fixtures/_c.scss

API

parseDir

Parses a directory and builds a dependency graph of all requested file extensions.

parseFile

Parses a file and builds its dependency graph.

Options

loadPaths

Type: Array Default: [process.cwd]

Directories to use when resolved @import directives.

extensions

Type: Array Default: ['scss', 'sass']

File types to be parsed.

follow

Type: Boolean Default: false

Follow symbolic links.

exclude

Type: RegExp Default: undefined

Exclude files matching regular expression.

Example

var sassGraph = require('./sass-graph');
console.log(sassGraph.parseDir('test/fixtures'));

//{ index: {,
//    '/path/to/test/fixtures/a.scss': {
//        imports: ['b.scss'],
//        importedBy: [],
//    },
//    '/path/to/test/fixtures/b.scss': {
//        imports: ['_c.scss'],
//        importedBy: ['a.scss'],
//    },
//    '/path/to/test/fixtures/_c.scss': {
//        imports: [],
//        importedBy: ['b/scss'],
//    },
//}}

Running Mocha tests

You can run the tests by executing the following commands:

npm install
npm test

Authors

Sass graph was originally written by Lachlan Donald. It is now maintained by Michael Mifsud.

License

MIT

Changelog

[4.0.0]

BREAKING CHANGES

• Bump yargs@^17.2.1 (@kiskoza, #117)