VSCode plugin (Visual Studio Code plugin) to compile scss files using Dart SASS Compiler.
- Usage
- Install
- Activation
- Properties
- dartsass.includePath
- dartsass.disableMinifiedFileGeneration
- dartsass.disableSourceMap
- dartsass.disableCompileOnSave
- dartsass.pauseInterval
- dartsass.enableStartWithUnderscores
- dartsass.disableAutoPrefixer
- dartsass.autoPrefixBrowsersList
- dartsass.targetDirectory
- dartsass.sassBinPath
- dartsass.nodeExePath
- dartsass.debug
- Menus
- Commands
- Features
- FAQ
- License
- ChangeLog
- Todo
- Contributing
- Credits
- Share
It uses the Dart/JS Sass Compiler to generate the .css and .min.css files automatically for the given .scss file in the editor.
You can install it from inside VSCode by using the following command
ext install codelios.dartsass
You can install codelios.dartsass from the VSCode Marketplace.
Like it , then feel free to share
The plugin gets activated when .scss / .sass files are opened.
More details of the plugin can be found at vscode-dartsass Page.
This extension contributes the following properties:
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.
Default: False. Flag to disable minified file generation. Minified files are generated by default.
Default: False. Flag to disable source maps file generation (*.map). Source Maps are generated by default though.
Default: False. This disables a compilation with every save.
Default: 3. Pause Interval (in seconds) before kicking off another scss compilation to not compile frequently and hog resources.
Default: false. Enables compilation of files that start with underscores.
Default: false. Disables postcss processing using autoprefixer library.
Default: ["> 1%", "last 2 versions"]
. List of browsers to be specified for autoprefixer. See https://github.com/browserslist/browserslist#readme for more details.
Default: Empty. The target directory to write the generated css files.
This can be an absolute directory or a directory, relative to project root.
Default: Empty.
You may need to install sass binary locally or globally for the watch functionality to work.
Sass Compiler can be installed locally as npm install [email protected]
, say . (Choose relevant version as appropriate )
After installation, you can set the property dartsass.sassBinPath
to be one of the following as applicable.
node_modules/.bin/sass
( Linux ) ornode_modules\\sass\\sass.js
( Windows ) - See Issue #24
You can install the sass compiler globally as npm install -g [email protected]
(if not installed already, that is !).
You can set the property dartsass.sassBinPath
as below, according to the platform
- Linux:
Determine the path to global sass compiler ( /usr/local/bin/sass
if exists ), or any other path returned by which sass
.
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: false. Best applicable for developers of this extension only.
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.
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.
Compiles the current scss file in the active editor to .css and .min.css file as appropriate.
Prints out the current sass compiler version being used.
Views the list of watchers by this sass plugin
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.
This plugin has integrated functionality for sass watcher ( sass --watch input:output
) in it.
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 !).
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.
-
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. PointsassBinPath
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
, underdevDependencies
, add an entry forsass
(version 1.19.0 - say)"devDependencies": { "sass" : "1.19.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 ofsass
in step 3) above ?The plugin has been written for
sass
package only and does not supportnode-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.
This VSCode extension is released under MIT license.
See CHANGELOG for more details.
- The list of directory watchers need to be better visualized than the naive output in the console.
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.
- [ TOC Credit: ekalinin/github-markdown-toc ]