VSCode plugin (Visual Studio Code plugin) to compile scss files using Dart SASS Compiler.
Usage
It uses the Dart/JS Sass Compiler to generate the .css and .min.css files automatically for the given .scss file in the editor.
Install
Inside VSCode
You can install it from inside VSCode by using the following command
ext install codelios.dartsass
VSCode Marketplace
You can install codelios.dartsass from the VSCode Marketplace.
Like it , then feel free to share
OpenVSX Marketplace
You can install irispixel.dartsass from the OpenVSX Marketplace
Activation
The plugin gets activated when .scss / .sass files are opened.
More details of the plugin can be found at vscode-dartsass Page.
Properties
This extension contributes the following properties:
dartsass.disableAutoPrefixer
Default: false. Disables postcss processing using autoprefixer library.
dartsass.disableSourceMap
Default: False. Flag to disable source maps file generation (*.map). Source Maps are generated by default though.
dartsass.disableCompileOnSave
Default: False. This disables a compilation with every save.
dartsass.enableStartWithUnderscores
Default: false. Enables compilation of files that start with underscores.
dartsass.includePath
Default: [ ]. Set of directories to be specified as includePath for sass compilation. Important: Currently we do not support spaces in includePath given the quirks associated with that. So ensure that you do not have spaces in the same.
dartsass.nodeExePath
Default: node.exe. Sets the PATH to the node.exe executable.
Important: This property is applicable on the windows platform only. On Linux, this property is completely ignored and not used at all
Default: host. Property to mention the execution platform of the dart sass plugin.
For the most part , this plugin attribute is best left untouched. In case when you are working on a Windows host but remotely editing files on the Linux platform, then changing this option is helpful.
Possible values:
host: Sass source files are compiled on the samae platform as that of the vscode editorlinux: Sass source files are compiled on the linux platform and accessed possibly but not necessarily from a windows host.windows: Sass source files are compiled on the windows platform and accessed possibly but not necessarily from a windows host.
Important: This property is experimental and not guaranteed to work though.
Default: both. Property to customize the format of the output files, generated by the scss compiler.
Possible values:
cssonly: Generetes only the compiled css file and not the minified fileminified: Generates only the minified css file and not the compiled css fileboth: Generates both the compiled css file and the minified file as well. Default Value.
Important: This property replaces the formerly deprecated property disableMinifiedFileGeneration that is not used anymore.
If you had earlier set disableMinifiedFileGeneration to be true, then you can set outputFormat to be cssonly to achieve the same effect.
If you had earlier set disableMinifiedFileGeneration to be false ( default value for the property ) , then you can set outputFormat to be both ( again , default value for the new property as well ).
dartsass.pauseInterval
Default: 3. Pause Interval (in seconds) before kicking off another scss compilation to not compile frequently and hog resources.
dartsass.sassBinPath
Default: Empty.
The watch functionality launches a sass command line process behind the scenes and delegates almost all of the watching functionality to the same.
sassBinPath references the location of the sass binary that needs to be launched when we watch a directory of input scss files for changes.
Hence, you need to install sass binary locally or globally for the watch functionality to work.
[ Use a recent sass version or a different relevant version for your use case as appropriate ]
Linux
Sass Compiler can be installed locally as follows:
npm install -D sass@1.47.0
After installation, you can set the property dartsass.sassBinPath to be one of the following as applicable.
Set dartsass.sassBinPath to node_modules/.bin/sass
Aliter (global sass installation):
Sass Compiler can also be installed globally, as follows:
npm install -g sass@1.47.0
Determine the path to global sass compiler returned by which sass. ( say, /usr/local/bin/sass ).
Set dartsass.sassBinPath to /usr/local/bin/sass.
(assuming , that was the path returned by which sass run previously ).
Having said that, we recommend local installation as mentioned above to prevent unnecessary quirks.
Windows
Sass Compiler can be installed locally as
npm install -D sass@1.47.0
On Windows, the path to sassBinPath slightly differs because of a quirkiness [ See [Issue #24](https://github.com/codelios/vscode-dartsass/issues/24) ]
Set dartsass.sassBinPath to node_modules\\sass\\sass.js.
dartsass.targetDirectory
Default: Empty. The target directory to write the generated css files.
This can be an absolute directory or a directory, relative to project root.
dartsass.debug
Default: false. Best applicable for developers of this extension only. If you are the end-user, feel free to ignore this altogether.
DartSass: Sass Watch
In the file explorer on the left hand side, when we right-click on a directory, we get a menuitem DartSass: Sass Watch .
This option appears only in the case of a directory and not in case of individual files.
This command watches the directory using the option sass --watch input:output .
Important: For this menu / feature to work, the sassBinPath
property must point to an external sass binary.
Otherwise it will indicate an error.
After the directory is successfully watched, an entry is added to the statusbar on the lower right bottom - Sass Watchers: 1 (or any number as appropriate).
When the IDE is closed the subprocesses launched for watching get killed automatically.
To view the list of watched processes / directories, use the command: DartSass: View Sass Watchers and then check the Output under DartJS Sass.
It will list all the watched source directories and the pid (tested in unix) for those processes.
DartSass: Sass Unwatch
In the file explorer on the left hand side, when we right-click on a directory, we get a menuitem DartSass: Sass UnWatch .
This option appears only in the case of a directory and not in case of individual files.
If a directory was watched before, this kills the process used to watch the directory.
In case the directory was not watched before, a warning message appears indicating that no watcher exists for that directory.
Commands
QuikSass: Compile Current File
Compiles the current scss file in the active editor to .css and .min.css file as appropriate.
QuikSass: Sass Compiler Version
Prints out the current sass compiler version being used.
QuikSass: View Watcher List
Views the list of watchers by this sass plugin
QuikSass: Clear All Watchers
Clears all existing sass watchers without trying to figure out all the existing watchers and unwatching them individually.
Useful in case we want to do a quick project watcher reset.
Features
Sass Watcher
This plugin has integrated functionality for sass watcher ( sass --watch input:output) in it.
Pure Javascript SASS
This VSCode plugin directly depends on the native pure-javascript sass implementation.
Check Dart implementation of SASS for more details.
It does not depend on node-sass (or indirectly the platform-specific libcss either !).
Customize Directory
By default, it looks for packages in package.json in the root directory of the current project. ( and hence, the packages in node_modules)
To customize the same, check dartsass.sassWorkingDirectory. More details below in extension settings.
FAQ
Does this plugin come pre-built with Sass Compiler ?
Yes. by default - the plugin comes pre-built with one of the more recent releases of sass compiler. So - you would not need to install sass compiler locally in your system for the plugin to be active.
I already have Sass compiler installed in my system in PATH or would like to try a sass compiler installed in a specific path ? How can I configure the same ?
By default - the plugin uses the built-in sass compiler used internally. To use an external binary, see option sassBinPath mentioned above. Point sassBinPath to the binary (say, /usr/local/bin/sass ) in User / Workspace for vscode and then start saving the files. Now the plugin will use the external sass binary as opposed to the built-in sass library for the compilation.
I don't have a global sass installation / I don't have the write permission to write to the global files / I don't want to have a single global sass binary. What are my options to set sassBinPath now ?
In your project package.json , under devDependencies, add an entry for sass (version 1.47.0 , say)
"devDependencies": { "sass" : "1.47.0" }
Install the packages as npm i --no-optional
Modify the property dartsass:sassBinPath: "node_modules/.bin/sass" at the workspace level ( and not at the user level). This can also be done through "File -> Settings -> search for "DartSass" under workspace tab".
This should help install a local sass binary in your project under your project tree, and can be used for watching Sass directories, if you don't have a global sass installation.
Can I use node-sass package in place of sass in step 3) above ?
The plugin has been written for sass package only and does not support node-sass. Not to mention , node-sass is platform dependent and deprecated as well. Hence we do not support the same.
I have scss files that contain import statements that begin with "~" and used to work fine , until I had upgraded the plugin to v0.1.0+ ? What gives ?
So earlier, we used to support the "~" prefix in import statements by using an importer called node-sass-package-importer . Hence it used to work.
Starting from v0.1.0 though, support for node-sass-package-importer has been removed since then. So now your import statement becomes as follows.
Earlier - @import "~/bootstrap/scss/functions.scss"
would now be rewritten without the prefix "~/" as below:
@import "bootstrap/scss/functions.scss"
Also - you would want to set the includePath property (list of strings) as below:
"dartsass.includePath": ["node_modules"]
assuming the node_modules is in the root of the project under discussion. Else modify the above property accordingly.
Changing the import statements and adding to includePath property should fix any changes broken by the upgrade.
It is also better because eventually when the css files get packed /minified for distribution, they can be passed the conventional parameter sass -I includeDir .. to be compiled so avoiding any non-standard prefixes like ~ in the files helps that case.
The autocompile (of sass) files that comes predefined with the plugin is too aggressive and is killing the CPU. What can I do ?
By default, the Dart/JS compiler gets activated with every save of the current editor file.
If that is too aggressive, see pauseInterval configuration option above ( in seconds ). It can be used to configure the pause interval between successive compilations to use resources less aggressively.
I would like to use Autoprefixer for my compilation. Does this plugin support the same ?
The plugin comes built-in with autoprefixer support. See autoPrefixBrowsersList option to configure the browserslist for which autoprefixer needs to generate code (using postcss).
I would like to compile a directory of .scss files everytime the files in the directory are changed. How do we do that ?
The plugin has an option called "Watch Directory" that goes with the context menu associated with a directory in the file explorer panel.
This option launches a separate sass watch command in the background to implement the same.
When I launch a "Watch Directory" , I get an error saying - "Directory watcher is not supported.". What could be going wrong ?
The directory watch functionality depends on the sass command line binary (platform-specific). So you need to install sass binary separately and then specify the binary using sassBinPath plugin configuration property ( See above ).
I have watched a directory. Now I would like to unwatch the same and kill external processes that are watching as well.
Right click on a directory that is being watched already. Click "DartSass: Unwatch directory". This will unwatch the directory and kill the sass watch external process, if any.
If the directory was not being watched , a warning message will popup indicating that the directory was not being previously watched.
License
This VSCode extension is released under MIT license.
ChangeLog
See CHANGELOG for more details.
Contributing
The code of this plugin is published under MIT License.
So if you are contributing to this plugin / extension, it is important that the source code is distributed under MIT license.
Almost all the heavy-lifing of this plugin (say, interacting with sass library or using sass command line) is done by the common library -
DartSass Plugin Common.
So if you are looking for a bug / feature, check the dartsass-plugin-comon repository for the code that does most of the heavy-lifting.
Credits
- [ TOC Credit: ekalinin/github-markdown-toc ]
Share
Like it , then feel free to share
