Sass Extension for Nova

Automatically compile local .scss and indented-syntax .sass files to CSS after saving.

Features

• Expanded or compressed CSS output.
• Optional external or embedded source maps (disabled by default).
• Project-specific compilation scope and output paths.
• Optional paths relative to the saved Sass file.
• Sass executable detection and version checks.
• Compile Now for the active Sass file, independent of automatic compilation.
• Clickable Sass errors and located warnings in Nova's Issues sidebar.
• Error notifications, with compilation status, warnings, and full errors in Nova's Extension Console.
• UTF-8 BOM removal from CSS reported as generated by a successful compilation.

Requirements and installation

Install Dart Sass on the Mac running Nova. With Homebrew, run:

brew install sass/sass/sass
sass --version

In Nova, choose Extensions → Extension Library, search for Sass, and click Install.

Use a local Nova project. Remote documents are skipped, with one notification per extension activation. Local documents are still eligible for compilation; opening a remote document does not disable the entire workspace. For remote websites, compile locally and use Nova Publishing to upload CSS and any source maps you need.

Automatic compilation

By default, the extension automatically runs Sass after you save a local .scss or .sass file. Compilation starts after the save finishes, so it uses the latest contents on disk. You do not need to run a separate command.

The project settings determine which entry points are compiled, where the CSS is written, and the output style. Saving a partial can update an entry point that loads it, provided that entry point is within the compilation scope. Sass performs an incremental update, skipping outputs it considers up to date. See Compilation scope example for the default layout and custom path examples.

Compilation errors appear in a notification and, when a source location is available, in Nova's Issues sidebar. Full diagnostics are available in the Extension Console.

To disable automatic compilation, set Compilation & Output → Compile on Save → Off in the Sass project settings. You can still use Sass: Compile Now as described below. Compilation runs on save, not while you type, and remote documents are not supported.

Manual compilation

Open a saved local .scss or .sass file, then use Extensions → Sass → Compile Now or Editor → Sass → Compile Now, or search for Sass: Compile Now in the Command Palette. Compile Now is enabled for the active saved local .scss or .sass file. Both menus also offer Check Sass Installation, which does not require a Sass file. Nova may disable the Editor menu itself when no text editor is open; use the Extensions menu in that case. A key binding can be assigned in Nova's settings.

Compile Now performs an incremental update using the same scope and output settings as saving the active Sass file. Unchanged outputs may be skipped.

Use it when Compile on Save is Off. It targets the active file's compilation scope, not every open file or website. To target exactly one entry point, set Update Path to that file.

Save modified local Sass/CSS files first. The command asks you to save rather than compiling older content from disk. Remote files are unsupported.

The command is available through the menu and palette, not the Files sidebar's right-click menu, which Nova's documented extension API does not expose.

Issues and warnings

Located Sass errors and warnings appear in the Issues sidebar. Click an issue to open its source location, including imported partials. Results are replaced on the next completed compilation of the same scope; unrelated scopes retain their results. Full output and diagnostics without a recognised location remain in the Extension Console.

Compilation errors still produce a popup, even with the Issues sidebar open. Sass reports where parsing fails, which can be later than the original mistake (for example, a missing closing brace). It may stop at the first fatal error in an entry point; fixing it and compiling again can reveal further errors.

Project settings

Open Project → Project Settings → Languages & Extensions → Sass. Settings are grouped into three collapsible sections below.

Compilation & Output

Compile on Save

On (default) or Off. Controls automatic compilation after saving. Sass: Compile Now remains available when Off. Existing checkbox preferences are migrated without changing their selection.

CSS Style

Expanded (default) or Compressed.

Generate Source Map

External, Embedded, or None (default). External maps are separate .css.map files; embedded maps are included in the CSS. Both let developer tools relate CSS to its Sass source.

Version 1.6 keeps explicitly saved preferences. Projects without a saved preference now default to None. Turning maps off does not delete old .css.map files.

Remove UTF-8 BOM

On (default) or Off. On removes the UTF-8 byte order mark from CSS reported as generated by a successful compilation. Off leaves Sass output unchanged. Applies to automatic saves and Sass: Compile Now. Changing the setting does not rewrite existing CSS; the file must be compiled again. This does not remove @charset declarations.

Error CSS

Yes (default) or No. Controls whether Sass writes an error stylesheet when compilation fails. This is separate from the extension's error notification.

Deprecation Warnings

On (default) or Off. Turn off to hide deprecation warnings from the Issues sidebar and editor highlights. Existing results update immediately, without recompilation. Errors and other warnings remain visible, and full diagnostics are still logged to the Extension Console. Turning this back on restores cached deprecations from the latest compilation results. Existing checkbox preferences are preserved.

Paths

Leave both paths blank for the default css/scss workflow: compilation uses the saved file's folder, or its parent if that folder is named scss. CSS is generated beside each Sass entry point. The placeholders describe this automatic behaviour; they are hints, not configured paths. Custom paths start from the project root unless relative paths are enabled.

Update Path

Optional compilation input, relative to the workspace root by default; for example, source/styles. Use a directory to update its Sass entry points, or a file such as source/styles/main.scss to target one entry point when saving partials elsewhere.

When blank, the extension uses the saved file's directory. If that directory is named scss (case-insensitive), it uses its parent instead. It runs Sass with --update, so Sass decides which outputs need rebuilding.

Output Path

Optional output destination, relative to the workspace root by default; for example, dist/css. Match it to the input: use an output directory for a directory input, or a CSS filename for a single-file input. When blank, Sass writes CSS beside each entry point.

Resolve Paths Relative to Sass File

Off by default, preserving existing workspace-relative settings. When on, configured Update Path and Output Path values resolve from the directory containing the saved Sass file. For example, Update Path . and Output Path ../css compile the saved file's directory into its sibling css directory.

Blank values retain the default behaviour described above. A leading / is ignored in either mode; these settings do not accept absolute filesystem paths. Relative mode follows the file being saved, including partials, so account for different directory depths.

Sass Installation

Sass Executable

Choose a detected installation or enter a custom absolute executable path, without shell quotes or escaped spaces. Detected choices show the version and location. Use the reload control to refresh them.

With no saved choice, the settings resolver selects the first detected installation. Automatic lookup checks /opt/homebrew/bin/sass, then /usr/local/bin/sass, then sass on Nova's process PATH. An existing choice is preserved, even if it is no longer valid. The PATH entry may refer to the same installation as an absolute-path entry.

Check Sass Installation

Runs the selected or automatically located executable with --version. A successful check says “Dart Sass [version] is installed” and displays its location. This checks the executable, not whether your project's Sass compiles. The button stops spinning without waiting for the notification to be dismissed.

Compilation scope example

With Update Path and Output Path blank:

project/assets/css/combined.scss
project/assets/css/combined.css
project/assets/css/scss/_include.scss

Saving either Sass file runs an update of project/assets/css. The entry point must load the partial for its changes to affect the result. Sass partials (filenames beginning with _) are not standalone CSS outputs.

In a project containing several websites, this default scope does not include neighbouring websites. An explicitly configured Update Path can broaden the scope. The parent-folder rule applies only when the saved file's immediate folder is named scss; deeper nested partials may need a custom Update Path.

Custom paths from the project root

Use this when a project has one source directory and a separate output directory:

project/
  source/styles/main.scss
  source/styles/partials/_header.scss
  public/css/main.css

• Update Path: source/styles
• Output Path: public/css
• Resolve Paths Relative to Sass File: Off

Saving either Sass file updates entry points under source/styles and writes CSS under public/css. Because the paths start at the project root, saving a nested partial does not change the scope. The entry point must load the partial.

File-relative paths for multiple websites

Use this when several websites share the same folder layout:

project/
  site-a/assets/scss/main.scss
  site-a/assets/scss/_header.scss
  site-a/assets/css/main.css
  site-b/assets/scss/main.scss
  site-b/assets/scss/_header.scss
  site-b/assets/css/main.css

• Update Path: .
• Output Path: ../css
• Resolve Paths Relative to Sass File: On

Saving site-a/assets/scss/main.scss updates site-a/assets/scss and outputs to site-a/assets/css. Saving the equivalent file in site-b uses site-b's directories instead. The same project settings work for both websites.

Here, . explicitly selects the saved file's directory, overriding the automatic rule that would otherwise move up from a folder named scss.

Watch for nested partials: these paths are relative to the file you save, not its entry point. Saving scss/components/_button.scss would target scss/components and output to scss/css. For nested layouts, use a fixed project-relative Update Path as in the previous example, or trigger compilation from the main file.

Compile a single entry point

Use this when you want one stylesheet to be the compilation target, even when saving its nested partials:

project/
  source/styles/main.scss
  source/styles/partials/_header.scss
  public/css/site.css

• Update Path: source/styles/main.scss
• Output Path: public/css/site.css
• Resolve Paths Relative to Sass File: Off

Saving main.scss or its loaded partial triggers an update of main.scss, producing public/css/site.css. A single-file input needs a CSS filename as its custom output, not just a folder. Leave Output Path blank to generate source/styles/main.css instead.

These examples apply equally to automatic compilation and Sass: Compile Now. All use incremental updates, so unchanged outputs may be skipped.

Troubleshooting

• Sass not found: select the correct executable and use Check Sass Installation. Nova's process PATH may differ from your Terminal PATH.
• Warnings about @import: these are Dart Sass deprecation warnings, not compilation errors. To hide them from the Issues sidebar and editor highlights, set Compilation & Output → Deprecation Warnings → Off in the Sass project settings. Full diagnostics remain in the Extension Console, and compilation errors and other warnings are still shown. Hiding deprecations does not fix the underlying compatibility issue: migrate your stylesheets to @use and @forward when possible. The extension does not rewrite them. See the Sass migration guidance.
• Compilation errors: inspect Nova's Extension Console (enable extension development items in Nova Settings → General if necessary). The notification is abbreviated; the console contains full diagnostics.
• Unexpected or missing output: check Update Path, Output Path, relative mode, and whether the entry point loads the saved partial. Compilation happens after save, not as you type.
• BOM remains: cleanup only runs for CSS filenames reported by a successful Sass update. It does not sweep existing CSS or run after a failed update. Cleanup failures are logged in the Extension Console. Expanded CSS may contain an @charset declaration; that is not a BOM.

ChangeLog

Version 1.7.2

• Add a GitHub Sponsors link to the extension details.

Version 1.7.1

• Correct Compile Now availability in the Extensions menu using the active local Sass file.
• Keep Check Sass Installation independent of the active file type in both menus.

Version 1.7

• Add Sass menu groups with Compile Now and Check Sass Installation in the Extensions and Editor menus.
• Restrict Compile Now menu availability to saved SCSS and Sass files.
• Compilation behaviour, saved settings and defaults are unchanged from 1.6.

Version 1.6

• Add Remove UTF-8 BOM (On by default); Off preserves Sass output without post-compilation BOM removal.
• Add Deprecation Warnings (On by default), with immediate filtering of Issues and editor highlights while retaining errors, other warnings, and full console diagnostics.
• Add Sass: Compile Now to the Extensions menu and Command Palette for the active Sass file, using the same compilation scope as saving, even with compile-on-save disabled.
• Group settings into Compilation & Output, Paths, and Sass Installation.
• Use On/Off radio buttons for Compile on Save and Deprecation Warnings, preserving existing checkbox preferences.
• Explain automatic css/scss path handling in the Paths heading and placeholders, with shorter field descriptions.
• Correct single-file Update Path handling when no Output Path is configured, generating CSS beside the input file.
• Show located Sass errors and warnings in Nova's Issues sidebar, including imported partials.
• Require saving modified Sass/CSS documents before manual compilation.
• Compile after the source document has been saved.
• Strip a UTF-8 byte order mark from CSS files reported as generated by a successful Sass update.
• Resolve Sass's relative output filenames against its working directory before BOM cleanup.
• Report Sass deprecation warnings in the Extension Console instead of as compile errors.
• Skip remote documents and show one notification per extension activation; local documents remain eligible for compilation.
• Disable source maps by default for projects without an explicit preference.
• Fix the Embedded source-map option so it passes --embed-source-map to Sass.
• Add an opt-in setting for resolving Update Path and Output Path relative to the saved Sass file.
• Detect Sass in standard Homebrew locations and show detected versions in project settings.
• Add a Check Sass Installation action with version/location feedback and an “is installed” success message.
• Automatically select the preferred detected Sass executable when no workspace choice exists.
• Stop the installation-check spinner immediately after displaying its result.
• Log generated-file status, warnings, and complete compilation errors in Nova's Extension Console while retaining concise error notifications.
• Refresh the extension icon.

Version 1.5

• Move config items to configWorkspace (Thanks to @JohnWickham)
• Added a new preference to enable compile on save for the project

Version 1.4

• Fixed bug where the output path was not relative to the workspace path

Version 1.3

• Added support for .sass file extensions and indented format
• Added preference for an output directory relative to workspace

Version 1.2

• Added preference to manually set the path that an update will be performed on, relative to the workspace directory

Version 1.1

• Added preference for the compile scope

Version 1.0

• Icon change and internal re-structure

Version 0.9

• Auto hide the error notification after 10 seconds or if the file is re-saved without an error.
• Other bug fixes
• See README Notes for a change to the compile directory
• Updated README

Version 0.8

• Changed the update root from the workspace root to the files current directory

Version 0.7

• Updated Icon

Version 0.6.5

• Bug fix if only one line of message

Version 0.6.4

• Remove unused preference

Version 0.6.3

• Removed Editor command option
• Implemented the preferences
• Bug fixes and code cleanup
• Wording updates
• Added notification when a compile error occurs

Version 0.5.1

• Just README changes

Version 0.5

• Basic functional release

MIT License

Copyright (c) 2020 Vine Code Limited

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.