pulsar-sass-autocompile

Automatically compiles SASS files on save or via shortcut, with extensive configuration possibilities.

This is a Pulsar port of sass-autocompile by Armin Pfäffle, rewritten in JavaScript and moved from the deprecated node-sass to Dart Sass.

Requirements

None. Dart Sass is a pure JavaScript implementation of Sass and ships as a direct dependency of this package, so there is nothing to install globally and no compiler process to shell out to. You do not need Node.js, node-sass, or the sass CLI on your PATH.

(The sass package does pull in @parcel/watcher, which contains a native binary. That code path belongs to the sass --watch CLI and is never loaded by the compilation API this package uses, so a missing or unbuildable watcher binary does not affect anything here.)

Usage

Basic SASS compilation

After installing this package the Compile on save option is enabled, so saving a .scss or .sass file compiles it automatically.

Alternatively you can use the shortcuts:

1. ctrl-shift-c: compile the SASS file to a CSS file
2. alt-shift-c / cmd-shift-c: direct compilation; replaces the SASS text with the compiled CSS

The third method is the Tree View context menu, which offers a Compile SASS item when you right-click a file with a .scss or .sass extension.

After compiling you will see a notification or a panel at the bottom of the editor, depending on your settings. In the panel you can click the message to open the resulting CSS file; if compilation failed, clicking jumps to the position in the SASS file where the error occurred.

When a compilation produces @debug or @warn output, a Show detailed output link appears in the panel header and opens that output in a new tab. Set Show compiler output after compilation to have it opened automatically.

Compile to file

The default behaviour, used when you save a file or pick the Tree View item. It compiles a SASS file to one CSS file per enabled output style.

Direct compilation

To compile SASS text instantly, paste it into a tab and press alt-shift-c / cmd-shift-c. The package compiles the input and replaces it with the resulting CSS. If more than one output style is enabled you are asked which single one to use.

Options and parameters

Package options configure the general behaviour. To override them per file, set parameters in a comment on the first line of the SASS file.

Differences from the original package

Dart Sass is not a drop-in replacement for libsass, so a few things had to change.

• Output styles. Dart Sass supports only expanded and compressed; nested and compact were removed upstream. The settings and menu items for them are gone. Existing settings are migrated on first activation — nested becomes expanded, compact becomes compressed — and the inline parameters compileNested, compileCompact, nestedFilenamePattern, compactFilenamePattern and outputStyle: nested|compact still work, mapping onto the closest supported style with a warning.
• precision is gone. Dart Sass always computes with a precision of 10.
• sourceComments is gone. Dart Sass does not emit them; use a source map instead.
• indentType, indentWidth and linefeed are applied by this package after compilation rather than by the compiler, and only affect the expanded output style (compressed output has no indentation or line breaks to adjust).
• Custom importers and functions use the Dart Sass API, which differs from the node-sass one. See Filename to custom importer.
• The node-sass path and timeout settings are gone, along with the machinery that hunted for a node-sass executable. Compilation now happens in-process.
• "Show node-sass output" is now "Show compiler output" and contains the @debug and @warn messages of the compilation.
• New: quietDeps and silenceDeprecations, which are useful for keeping Dart Sass' deprecation warnings manageable in projects that depend on older third-party SASS.

Settings from an earlier node-sass based installation are migrated automatically the first time this package activates.

Options

• Compile on Save

  En- or disables auto compiling on save. If enabled, saving a file with a .scss or .sass extension compiles it based on the general options and on inline parameters, if defined.

  Default: true

• Compile files ...

  Whether to compile every SASS file or only those that have a first-line-comment.

  Default: Every SASS file

• Compile Partials

  Whether saving a partial (a file whose name starts with an underscore) that has no first-line-comment compiles it.

  Default: false

• Ask before overwriting files that already exist

  If enabled and the output file already exists, you are asked whether to overwrite it. Otherwise files are overwritten silently.

  Default: false

• Directly jump to error

  If enabled and you compile an erroneous SASS file, that file is opened at the problematic position.

  Default: false

• Show 'Compile SASS' item in tree view context menu

  Adds a Compile SASS item to the Tree View context menu, shown only on files with a .scss or .sass extension.

  Default: true

• Compile with 'compressed' output style

  Compile with 'expanded' output style

  Enable one or both output styles. One output file is written per enabled style, so set the corresponding filename patterns before enabling both.

  Default: compressed: true, expanded: false

• Filename pattern for 'compressed' compiled files

  Filename pattern for 'expanded' compiled files

  The output filename for each style, optionally including a relative or absolute path.

  Use $1 as a placeholder for the original basename and $2 for the original file extension. For example, compiling Foo.sass with the pattern ../css/$1.minified.$2.css writes Foo.minified.sass.css into the sibling directory ../css/. Missing directories are created.

  Default (compressed): $1.min.css Default (expanded): $1.css

• Indent type

  Indent output with spaces or tabs. Only affects the expanded output style.

  Default: Space

• Indent width

  Number of spaces or tabs per indentation level. Only affects the expanded output style.

  Default: 2

• Linefeed

  Whether to use a cr, crlf, lf or lfcr sequence for line breaks.

  Default: lf

• Build source map

  If enabled a source map is generated. The filename is the output CSS filename with .map appended, e.g. output.css.map, and a sourceMappingURL comment is added to the CSS.

  Default: false

• Embed source map

  If enabled the source map is embedded in the CSS as a data URI instead of being written to a separate file.

  Default: false

• Include contents in source map information

  If enabled the source contents are included in the source map.

  Default: false

• Include paths

  Paths to search for files referenced by @use and @import declarations, comma separated. Paths containing spaces, commas or semicolons must be quoted. Relative paths are resolved against the directory of the file being compiled.

  /path/to/your/project/lib, "/path to your/project/mod"
  

  Default: ''

• Filename to custom importer

  Path to a .js file exporting a Dart Sass importer, or an array of them. Note that this API differs from the node-sass one: an importer is an object with canonicalize and load methods, or a file importer with findFileUrl.

  // importer.js
  module.exports = {
    canonicalize: (url) => (url.startsWith('magic:') ? new URL(url) : null),
    load: () => ({ contents: '.magic { color: purple; }', syntax: 'scss' })
  };
  

  Default: ''

• Filename to custom functions

  Path to a .js file exporting an object of Dart Sass custom functions, keyed by signature.

  // functions.js
  const { SassString } = require('sass');
  
  module.exports = {
    'greet($name)': (args) =>
      new SassString(`hi ${args[0].assertString().text}`, { quotes: false })
  };
  

  Default: ''

• Silence warnings from dependencies

  If enabled, warnings and deprecation notices raised by files loaded through an include path are not reported. Warnings from your own files still are.

  Default: false

• Silenced deprecations

  Comma separated list of Dart Sass deprecation ids to silence, e.g. import, global-builtin.

  Default: ''

• Notification type

  Which feedback you want when files are compiled: a panel, notifications, or both.

  Panel: shown at the bottom of the editor. While compiling it is a small header with a throbber; afterwards it shows a success or error message you can click to open the relevant file.

  Notification: the standard Pulsar notifications are used.

  Default: Panel

• Automatically hide panel on ...

  On which event the panel should disappear by itself. To hide it manually, use ctrl-alt-shift-h / ctrl-cmd-shift-h.

  Default: Success

• Panel-auto-hide delay

  Delay in milliseconds before the panel is hidden automatically.

  Default: 3000

• Automatically hide notifications on ...

  Which notifications disappear by themselves rather than waiting to be dismissed.

  Default: Info, Success

• Show 'Start Compiling' Notification

  Show an info message when compilation starts.

  Default: false

• Show additional compilation info

  Show extra detail such as output style, duration and file size.

  Default: true

• Show compiler output after compilation

  Automatically open the @debug and @warn output of a compilation in a new tab. Useful when working with @debug, @warn or @error.

  Default: false

• Show warning when using old parameters

  Warn whenever a compiled file uses an inline parameter that is deprecated or unsupported by Dart Sass.

  Default: true

Parameters

Add the following parameters, comma separated, to a comment on the first line of your SASS file. Both // ... and /* ... */ work. A parameter given here overrides the corresponding package option for that file only. A parameter written with a leading ! is set to false.

• compileOnSave [ : true | false ]

  Controls compile-on-save for this file.

  // compileOnSave
  // compileOnSave: true
  // !compileOnSave
  // compileOnSave: false
  

• compileCompressed

  compileExpanded

  Which output files to generate. If either is given, every output style not named here is disabled — so if you enabled both styles in the options and write compileCompressed, only the compressed file is generated.

  There is a short form that combines the style with its filename pattern:

  // compileCompressed: /path/to/your/project/css/test.css
  

• compressedFilenamePattern

  expandedFilenamePattern

  The output filename for the given style, optionally including a relative or absolute path. $1 is the original basename, $2 the original file extension.

• main

  Path to the main SASS file that should be compiled instead of this one. Put it in your partials so that saving any of them rebuilds the real entry point. See the main file convention.

  Example: // main: ../main.scss

  Chains are followed, and a cycle is reported as an error rather than followed forever.

• indentType: space | tab

  Indentation type for the expanded output style.

• indentWidth: 0-10

  Indentation width for the expanded output style.

• linefeed: cr | crlf | lf | lfcr

  Line break sequence of the output files.

• sourceMap

  Generates a source map. Given a filename it is used as the map's name; given true the CSS filename plus .map is used.

  Value: true | false | <filename.css.map>

• sourceMapEmbed

  Embed the source map as a data URI.

• sourceMapContents

  Include the source contents in the source map.

• includePath | includePaths

  Paths to search for files referenced by @use and @import. Relative paths are resolved against the file being compiled. Quote a path that contains spaces, commas or semicolons; surround multiple paths with [].

  // includePath: ../my-framework/scss/
  // includePath: [/path/to/your/project/lib, "/path to your/project/mod"]
  

• importer

  Path to a .js file containing a custom importer.

• functions

  Path to a .js file containing custom functions.

• quietDeps

  Silence warnings raised by files loaded through an include path.

• silenceDeprecations

  Deprecation ids to silence, e.g. silenceDeprecations: [import, global-builtin].

Deprecated parameters

These still work but will be removed. Use the parameters above instead.

• out

  The output filename pattern. Setting it generates a single output file, and is meant to be combined with outputStyle. Without outputStyle the style defaults to compressed.

• outputStyle

  A single output style. nested is compiled as expanded and compact as compressed, since Dart Sass no longer has them.

  Values: compressed | expanded | nested | compact

• compress

  Enables or disables compression. If true the output style is compressed, otherwise expanded. Ignored when outputStyle is also given.

• compileNested / compileCompact

  nestedFilenamePattern / compactFilenamePattern

  Treated as their expanded and compressed counterparts.

• precision / sourceComments

  Ignored, with a warning. Dart Sass has no equivalent.

Examples

Compressed output written to a sibling CSS directory:

// compileCompressed, compressedFilenamePattern: ../css/$1.css

… or in short form:

// compileCompressed: ../css/$1.css

Overriding just the filename patterns:

// compressedFilenamePattern: ../css/min/$1.css, expandedFilenamePattern: ../css/$1.css

Given this structure:

main.scss       // imports colors and layout
colors.scss     // color definitions
layout.scss     // layout definitions

adding this line to colors.scss and layout.scss compiles main.scss whenever you save either of them:

// main: main.scss

Predefined shortcuts

• ctrl-shift-c

  Compiles the current file to a CSS file. Only works on files with a .scss or .sass extension.

• alt-shift-c / cmd-shift-c

  Direct compilation of the current text. Works in any file, but reports an error if the content is not valid SASS.

• ctrl-alt-shift-s / ctrl-cmd-shift-s

  Toggles compile-on-save. A notification confirms the new value.

• ctrl-alt-shift-h / ctrl-cmd-shift-h

  Hides the panel.

Changelog

See CHANGELOG.md.

License

MIT, as with the original package. See LICENSE.md.