Automatically compiles SASS files on save or via shortcut, with extensive configuration possibilities.
Inspired by less-autocompile package, written by lohek, I have created a counterpart for SASS. This package can automatically compile SASS files (file ending: .scss
or .sass
) when you save it. Or you can use shortcuts to do that. Beside that this package is highly configurable to fit all your needs.
At the moment, you can only use this package when you install node.js and node-sass on you system. It's important that you install node-sass globally (command: npm install node-sass -g
), so it's possible to access it via CLI.
The reason why sass-autocompile needs that is because node-sass is not compatible with atom shell in the current version (2.0.1), so it cannot be added as dependency. Probably that will change later, so you won't have to install node.js and node-sass additionally ‒ I put it to the roadmap.
Important: Install node.js and node-sass before, see requirements.
After you have installed this package, option Compile on save is enabled, so if you save a SASS file it's automatically compiled to a CSS file. Since version 0.10.0 you don't need a first-line-comment to compile SASS files any more, except you set this by option.
Alternatively you can use shortcuts for starting compilation:
ctrl-shift-c
: Compile SASS file to a CSS filealt-shift-c
/ cmd-shift-c
: Direct compilation; replaces SASS text with compiled CSSThe third method is to use the Tree View context menu where you can find a Compile SASS item when right clicking on a file with .scss
or .sass
extension.
Note: When you want to compile a SASS file to a CSS File (→ Compile to file) the file extension must be .scss
or .sass
. You don't need a first-line-comment since version 0.10.0.
After compiling a SASS file, you should see a notification or a panel at the bottom of the editor, depending on your settings, showing you an error or success message. If you use panel notification (see options -> Notifications
) , you have the possibility to access the output CSS file by clicking on the compilation message. If compilation fails, you can even jump to error position in the corresponding SASS file where error occurred.
When using panel notification you can use Show detailed output link in the header caption of the panel to open detailed output of node-sass
command (available since 0.7.0). Additionally you can set option Show node-sass output after compilation to automatically show output after compilation.
This feature is the default behaviour and the method you will use most. It compiles a SASS file to a CSS file. When you save a SASS file or use the Tree View context menu this method is used.
When you want to instantly compile a SASS text, you can copy it to a new tab and press alt-shift-c
/ cmd-shift-c
shortcut. This package then compiles the SASS input and replaces it with the compiled CSS.
Since version 0.10.0 there are many new options. So have a look at the package options and configure the general behaviour for compiling SASS files. In the options section everything is explained in detail.
To overwrite general options in order to use specific configuration per project you can set parameters as comment in the first line. Have a look at the parameters where any parameter is described and how you can use it.
With this option you can en- or disable auto compiling on save functionality. If enabled and you save a file with .scss
or .sass
file extension, it's automatically compiled based on general options and on inline parameters, if defined.
Default: true
With this option you can decide if you want to compile every SASS file or only these which have a first-line-comment. Do I have t explain more about that? ;)
Default: Every SASS file
When you compile a Partial file (by saving it) and there is no first-line-comment, you can control if sass-autocompile compiles this file or not.
Default: false
If enabled and output file already exists, you are asked if you want to overwrite it. Else files are automatically overwritten .
Default: false
If enabled and you compile an erroneous SASS file, this file is opened and jumped to the problematic position.
Default: false
If enabled there is a menu item in the Tree View context menu called Compile SASS. This item is visible only on files that has .scss
or .sass
file extension.
Default: true
With these four options you can en- disable four different output styles. For each style the SASS file is compiled to the corresponding output file. So if you want to have the compressed and expanded style, activate that options, set the corresponding filename patterns and compile your SASS files.
Default: compressed: true
With this options you can define a filename pattern for the output filename of each output style, include a relative or absolute output path.
You can use $1
and $2
as placeholder for the original basename respectively the file extension. Furthermore you can add a relative or an absolute path where compiled files are stored to. For example: When you compile Foo.sass
and have ..\css\$1.minified.$2.css
as filename pattern, the resulting filename will be Foo.minified.sass.css
and is stored in the relative path ..\css\
. Alternatively you can use absolute paths.
Default (compressed): $1.min.css
Default (compact): $1.compact.css
Default (nested): $1.nested.css
Default (expanded): $1.css
With this option you can set the indention type: space or tab.
Default: space
This option defines the number of spaces or tabs to be used for indention.
Default: 2
Used to determine whether to use cr
, crlf
, lf
or lfcr
sequence for line break.
Default: lf
If enabled a source map is generated. Filename is automatically obtained by taking the output CSS filename and appending .map
, e.g. output.css.map
.
Default: false
If enabled source map (see option Build source map) is embedded as a data URI.
Default: false
If enabled contents are included in source map information.
Default: false
If enabled additional debugging information are added to the output file as CSS comments. If CSS is compressed this feature is disabled by SASS compiler.
Default: false
Paths to look for files that are referenced by @import
declarations (e.g. SASS frameworks or your own general SASS style collection). Multiple paths must be separated by commas. If you need spaces, commas or semicolons in a path, it must be surrounded by quotes.
/path/to/your/project/lib, "/path to your/project/mod"
Default: ''
Used to determine how many digits after the decimal will be allowed. For instance, if you had a decimal number of 1.23456789 and a precision of 5, the result will be 1.23457 in the final CSS.
Default: 5
If you want to use a custom import functionality, you can use this option to define a path to a JavaScript file that contains your code.
Default: ''
If you have custom functions you want to include, you use this option to set a path to your corresponding JavaScript file.
Default: ''
This options allows you to decide which feedback you want to see when SASS files are compiled: notification and/or panel.
Panel: The panel is shown at the bottom of the editor. When starting the compilation it's only a small header with a throbber. After compilation a success or error message is shown with reference to the CSS file, or on error the SASS file. By clicking on the message you can access the CSS or error file.
Notification: The default atom notifications are used for output.
Default: Panel
Select on which event the panel should automatically disappear. If you want to hide the panel via shortcut, you can use ctrl-alt-shift-h
/ ctrl-cmd-shift-h
.
Default: Success
Delay after which panel is automatically hidden.
Default: 3000
Decide when you want the notifications to automatically hide. Else you have to close every notification manually.
Default: Info, Success
If enabled and you added the notification option in Notifications
, you will see an info-message when compile process starts.
Default: false
If enabled additional info like duration or file size is presented.
Default: true
If enabled detailed output of node-sass command is automatically shown in a new tab after each compilation. So you can analyse the output, especially when using @debug, @warn or @error in your SASS.
Default: false
If enabled any time you compile a SASS file und you use old inline parameters, an warning will be occur not to use them.
Default: true
Maximal amount of time (in milliseconds) node-sass is allowed to run. If it's set to 0, there is no time limit for execution.
Default: 10000
Absolute path where 'node-sass' executable is placed (Mac OS X: /usr/local/bin
, Linux: ?
). This option is especially for Mac OS and Linux users who have problems with permissions and seeing error message command failed: /bin/sh: node-sass: command not found
.
Default: ''
Add following parameters in comma-separated way to the first line of your SASS file. See examples for demonstration:
With this option you can control compile on save functionality by first line parameter. If you define this option, global option is overwritten. Examples:
Enable compile on save
// compileOnSave
// compileOnSave: true
Disable compile on save
// !compileOnSave
// compileOnSave: false
With these parameters you can define which output files should be generated. If one of these parameters is set, every other output styles are deactivated. So, if you have enabled all four output styles in global options and set e.g. compileCompressed
in your inline parameters, only the compressed file is generated.
Note: Please read documentation about patterns too! You can combine the compile and filenamePattern parameter.
With this parameter you can define a filename pattern for the output filename of each output style, including a relative or absolute output path.
You can use $1
and $2
as placeholder for the original basename respectively the file extension. Furthermore you can add a relative or an absolute path where compiled files are stored to. For example: When you compile Foo.sass
and have ..\css\$1.minified.$2.css
as filename pattern, the resulting filename will be Foo.minified.sass.css
and is stored in the relative path ..\css\
.
Note: There is a short form for combining the compile and filenamePattern parameter. For Example:
// compileCompressed: /path/to/your/project/css/test.css
This line tells sass-autocompile to output a compressed version of the SASS input and to store in in test.css
.
Path to your main SASS file to be compiled. See http://sass-guidelin.es/#main-file for more info about that feature.
Value: <main.scss>
Example: ../main-scss.scss
Indention type: space or tab, default: space.
Value: space | tab
Indention width, maximum: 10, default: 2.
Value: <number>
Defines the linefeed of output files.
Value: cr | crlf | lf | lfcr
Creates a source map file if a filename is given or if true, source map filename
is automatically set as CSS filename, extended with .map
.
Value: true | false | <filename.css.map>
If true source map is embedded as data URI.
Value: true | false
If true the contents are included to the source map information
Value: true | false
If true additional debugging information is added to the output file as CSS comments, but only if CSS is not compressed.
Value: true | false
Paths to look for files that are referenced by @import
declarations (e.g. SASS frameworks or your own general SASS style collection). Can be relative or absolute paths. If spaces, commas or semicolons are needed, a path must be surrounded by quotes.
When you want to apply multiple paths, you have to surround the paths by []
, see examples above.
Value: <path> | [<path1>, <path2>, ...]
Examples:
includePath: ../my-framework/scss/
OR
includePath: [/path/to/your/project/lib, "/path to your/project/mod"]
The amount of precision allowed in decimal numbers.
Value: <number>
Path to .js file containing custom importer.
Value: <filename.js>
Path to .js file containing custom functions.
Value: <filename.js>
These parameters are supported, but will be removed in future. Please use the corresponding parameters described above.
Defines the output filename pattern. If you set this parameter only one output file is generated. You should use this parameter in combination with outputStyle
. If you use out
but do not define outputStyle
the default output style will be compressed
.
You can use $1
and $2
as placeholder for the original basename respectively the file extension. For example: When you compile Foo.sass
and you define $1.minified.$2.css
as out parameter, the resulting filename will be Foo.minified.sass.css
.
Values: <filename.css>
You can define the output style. Have a look at this page where the difference is explained and shown in examples. If you set this parameter only one output file is generated.
Values: compressed | compact | nested | expanded
Instead of using outputStyle
you can set this parameter in order to en- or disable compression. If enabled outputStyle
is set to compressed
, else to nested
.
If you use compress
and outputStyle
, compress is ignored.
Values: true | false
Defining a compressed output and save compiled CSS files to a relative CSS directory.
// compileCompressed, compressedFilenamePattern: ../css/$1.css
.. or in short version:
// compileCompressed: ../css/$1.css
Or you only want to overwrite some filename patterns?
// compressedFilenamePattern: ../css/min/$1.css, expandedFilenamePattern: ../css/$1.css
If you use @import
command in SASS, you should define the main
parameter in the child files. Imagine you have the following structure:
main.scss // main file which imports colors and layout files
colors.scss // contains color definitions
layout.scss // contains layout definitions
Add this to colors.scss
and layout.scss
to enable auto compilation on saving each of these two child files.
// main: main.scss
The special about this parameter is, that when you save a child file, the main.scss
is compiled, not the child file itself. So you can structure your SASS files, modify them and after saving, everything is compiled correctly, not only the saved file.
ctrl-shift-c
Compiles current file to a CSS file (see [Compile to file)(#compile-to-file)]). This only works on files with .scss
or .sass
file extension.
alt-shift-c
/ cmd-shift-c
Direct compilation of current text (see [Direct compilation)(#direct-compilation)]). This works with every file, but throws an error if content is not valid SASS.
ctrl-alt-shift-s
/ ctrl-cmd-shift-s
Toggles Compile on save functionality. You will see a notification if you change this value.
ctrl-alt-shift-h
/ ctrl-cmd-shift-h
Hides the panel.
For other concerns like questions or feedback have a look at the discussion thread on atom.io.
See CHANGELOG.md.
Good catch. Let us know what about this package looks wrong to you, and we'll investigate right away.