WebStorm 2023.3 Help

Sass, SCSS, and Less

WebStorm integrates with compilers that translate Sass, Less, and SCSS code into CSS. To use a compiler in WebStorm, you need to configure it as a File Watcher based on the relevant predefined template.

Before you start

  1. Make sure you have Node.js on your computer.

  2. Install and enable the File Watchers plugin on the Settings | Plugins page, tab Marketplace, as described in Installing plugins from JetBrains Marketplace.

  3. Make sure the File Watchers and Less or Sass required plugins are enabled on the Settings | Plugins page, tab Installed. For more information, refer to Managing plugins.

Installing Sass/SCSS

  • In the embedded Terminal (Alt+F12) , type:

    npm install -g sass

    Learn more from the Sass official website.

Installing Less

  • In the embedded Terminal (Alt+F12) , type:

    npm install --global less

    Learn more from the Less official website.

Compiling your code into CSS

To compile your code automatically, you need to install a compiler and configure a Sass, Less, or SCSS File Watcher which will track changes to your files and run the compiler.

When you open a file, WebStorm checks whether an applicable File Watcher is available in the current project. If such File Watcher is configured but disabled, WebStorm displays a popup that informs you about the configured File Watcher and suggests to enable it.

If an applicable File Watcher is configured and enabled in the current project, WebStorm starts the compiler automatically upon the event specified in the New Watcher dialog.

  • If the Auto-save edited files to trigger the watcher checkbox is selected, the File Watcher is invoked as soon as any changes are made to the source code.

  • If the Auto-save edited files to trigger the watcher checkbox is cleared, the File Watcher is started upon save (File | Save All, Ctrl+S) or when you move focus from WebStorm (upon frame deactivation).

Learn more from File Watchers.

WebStorm creates a separate file with the generated output. The file has the name of the source Sass, Less, or SCSS file and the extension .css. The location of the generated files is defined in the Output paths to refresh field of the New Watcher dialog. However, in the Project Tree, they are shown under the source file which is now displayed as a node.

Create a File Watcher

  1. In the Settings dialog (Ctrl+Alt+S) , click File Watchers under Tools. The File Watchers page that opens shows the list of already configured File Watchers.

  2. Click Add button or press Alt+Insert. Depending on the tool you are going to use, choose the Less, Sass, or SCSS predefined template from the list.

  3. In the Program field, specify the path to the compiler archive depending on the chosen predefined template.

    • lessc for Less.

    • sass for Sass/SCSS.

    If you followed the standard installation procedure with npm, WebStorm locates the required files itself and fills in the field automatically. Otherwise, type the path manually or click the Browse button and choose the file location in the dialog that opens.

  4. Proceed as described in File Watchers.

Example: compiling SCSS into CSS

Suppose your project is structured as follows:

Compiling SCSS into CSS: project structure

As you can see, _grid.scss is imported in Page.scss. The example below shows how Page.scss is compiled into CSS when you save your project manually or automatically and how the changes to _grid.scss are reflected in the generated CSS file.

  1. Create a File Watcher of the type SCSS: open the Settings dialog (Ctrl+Alt+S) , go to Tools | File Watchers, click the Add button on the toolbar, and select SCSS from the list.

    Compiling SCSS into CSS: creating a File Watcher
  2. In the New File Watcher dialog, that opens, all the mandatory fields are already filled in.

    SCSS File Watcher: settings

    Actually, these settings are sufficient to run the compiler successfully.

  3. Let's change grid.scss, for example, replace margin-left: 0; at line 31 with margin-left: 12px;. This triggers our File Watcher and the compiler processes Page.scss. As a result, two files are generated and shown nested under Page.scss:

    • Page.css with compiled CSS code

    • Page.css.map with source maps that let you step through your app during a debugging session.

    SCSS File Watcher: a CSS file generated

Although the default settings are sufficient to run the compiler successfully, let's still take a closer look at them to see how the File Watcher's behavior can be customized.

Change the action that triggers the File Watcher

The File Watcher wakes up and launches the transpiler as soon as your project is saved manually (File | Save All or Ctrl+S) or automatically.

In general, your code is saved automatically when you move the focus from WebStorm (on frame deactivation). With File Watchers, auto-save is also performed when you edit a file from the File Watcher's scope. As a result, the transpiler may be running all the time you type, which may cause performance issues. To solve the problem, suppress saving edited files automatically.

Press Ctrl+Alt+S to open the IDE settings and then select Tools | File Watchers. . Select the required File Watcher (SCSS in our example) and click the Edit button on the toolbar. In the Edit File Watcher dialog, expand the Advanced Options area and clear the Auto-save edited files to trigger the watcher checkbox.

Auto-save edited files off

By default, the File Watcher wakes up even when a file from its scope is edited from outside WebStorm. To override this behavior and transpile files only on editing internally, clear the Trigger the watcher on external changes checkbox.

Trigger the File Watcher on external changes is off

Change the scope

By default, WebStorm monitors changes in all files with the .scss extension in the entire project. This works for our example. However, you can change the scope to process, for example, only uncommitted changes. In a large project, this will save time.

Press Ctrl+Alt+S to open the IDE settings and then select Tools | File Watchers. , select the required File Watcher (SCSS in our example) and click the Edit button on the toolbar. In the Edit File Watcher dialog, select the applicable scope from the list. Learn more from Scopes and file colors.

SCSS File Watcher: change default scope

Custom output location

By default, the generated .css and .css.map files are stored in the folder where the original file is and are shown as its children in the Project tool window. You can change this default behavior to store all generated .css and .css.map files in a separate folder.

Let's start with a simple case. Suppose you have a custom_output.scss file in the project root.

Project structure

Let's edit custom_output.scss, for example, replace fill-opacity: abs(50); at line 6 with fill-opacity: abs(60);. With the default File Watcher configuration, the generated files custom_output.css and custom_output.css.map will be stored in the project root and shown as children of custom_output.scss.

Default settings: the output is stored in the project root

It would be convenient to store all the output in a separate folder, for example, css. Let's create a custom SCSS_custom_output File Watcher with the css folder as the output location.

Press Ctrl+Alt+S to open the IDE settings and then select Tools | File Watchers. , then create a SCSS File Watcher as described above.

Update the default settings as follows:

  • In the Arguments field, type:

    $FileName$:$ProjectFileDir$/css/$FileNameWithoutExtension$.css
  • In the Output paths to refresh field, type:

    $ProjectFileDir$/css/$FileNameWithoutExtension$.css:$ProjectFileDir$/css/$FileNameWithoutExtension$.css.map
New File Watcher with custom output path

Save the new File Watcher and make sure it is enabled.

New File Watcher with custom output path saved and enabled

Now, if you edit custom_output.scss, for example, replace fill-opacity: abs(50); at line 6 with fill-opacity: abs(60);, WebStorm creates a css folder and stores the generated custom_output.css and custom_output.css.map files in it.

Custom settings: the output is stored in a separate folder

Custom output location: preserve the original folder structure

Let's now consider an example where .scss files are stored in a folder structure, for example:

Project structure

With the default File Watcher, the generated files will be stored next to the original .scss files. If we use the custom File Watcher as described above, all the generated files will be stored in one same css folder:

Custom output: the generated files are stored in a separate folder in a plain structure

To have WebStorm preserve the folder structure, let's create another custom File Watcher.

Press Ctrl+Alt+S to open the IDE settings and then select Tools | File Watchers. , then create a SCSS File Watcher as described above.

Update the default settings as follows:

  • In the Arguments field, type:

    $FileName$:$ProjectFileDir$/css/$FileDirRelativeToProjectRoot$/$FileNameWithoutExtension$.css
  • In the Output paths to refresh field, type:

    $ProjectFileDir$/css/$FileDirRelativeToProjectRoot$/$FileNameWithoutExtension$.css:$ProjectFileDir$/css/$FileDirRelativeToProjectRoot$/$FileNameWithoutExtension$.css.map
Custom output with folder structure: File Watcher updated

Save the new File Watcher and make sure it is enabled.

Custom output with folder structure: File Watcher saved and enabled

Now, if you edit custom_output_body.scss, custom_output_header.scss, or custom_output_footer.scss, WebStorm creates a css folder with the subfolders' structure that preserves the structure of styles_structured.

Custom settings: the output is stored in a separate folder, the structure preserved

Example: compiling Less into CSS

Suppose, your project is structured as follows:

Compiling Less into CSS: project structure

The example below shows how my-styles.less is compiled into CSS when you save your project manually or automatically and how the changes to my-styles.less are reflected in the generated CSS file.

  1. Create a File Watcher of the type Less: open the Settings dialog (Ctrl+Alt+S) , go to Tools | File Watchers, click the Add button on the toolbar, and select Less from the list.

    Compiling Less into CSS: creating a File Watcher

    Alternatively, click Yes in the Enable File Watcher to compile LESS to CSS? pane at the top of the editor tab with a .less file.

    Compiling Less to CSS: creating a File Watcher from the pane in the editor
  2. In the New File Watcher dialog, that opens, all the mandatory fields are already filled in.

    Less File Watcher: settings

    Actually, these settings are sufficient to run the compiler successfully.

  3. Let's change my-styles.less, for example, change the value of @color at line 1. This triggers our File Watcher. As a result, two files are generated and shown nested under my-styles.less:

    • my-styles.css with compiled CSS code

    • my-styles.css.map with source maps that let you step through your app during a debugging session.

    Less File Watcher: a CSS file is generated

Although the default settings are sufficient to run the compiler successfully, let's still take a closer look at them to see how the File Watcher's behavior can be customized.

Change the action that triggers the File Watcher

The File Watcher wakes up and launches the transpiler as soon as your project is saved manually (File | Save All or Ctrl+S) or automatically.

In general, your code is saved automatically when you move the focus from WebStorm (on frame deactivation). With File Watchers, auto-save is also performed when you edit a file from the File Watcher's scope. As a result, the transpiler may be running all the time you type, which may cause performance issues. To solve the problem, suppress saving edited files automatically.

Press Ctrl+Alt+S to open the IDE settings and then select Tools | File Watchers. . Select the required File Watcher (Less in our example) and click the Edit button on the toolbar. In the Edit File Watcher dialog, expand the Advanced Options area and clear the Auto-save edited files to trigger the watcher checkbox.

Auto-save edited files off

Change the scope

By default, WebStorm monitors changes in all files with the .scss extension in the entire project. This works for our example. However, you can change the scope to process, for example, only uncommitted changes. In a large project, this will save time.

Press Ctrl+Alt+S to open the IDE settings and then select Tools | File Watchers. , select the required File Watcher (Less in our example) and click the Edit button on the toolbar. In the Edit File Watcher dialog, select the applicable scope from the list. Learn more from Scopes and file colors.

SCSS File Watcher: change default scope

Custom output location

By default, the generated .css and .css.map files are stored in the folder where the original file is and are shown as its children in the Project tool window. You can change this default behavior to store all generated .css and .css.map files in a separate folder.

Let's start with a simple case. Suppose you have a custom_output.less file in the project root.

Project structure

Let's edit custom_output.less, for example, change the value of @color at line 1. With the default File Watcher configuration, the generated files custom_output.css and custom_output.css.map will be stored in the project root and shown as children of custom_output.less.

Default settings: the output is stored in the project root

It would be convenient to store all the output in a separate folder, for example, css. Let's create a custom Less_custom_output File Watcher with the css folder as the output location.

Press Ctrl+Alt+S to open the IDE settings and then select Tools | File Watchers. , then create a Less File Watcher as described above.

Update the default settings as follows:

  • In the Arguments field, type:

    $FileName$ $ProjectFileDir$/css/$FileNameWithoutExtension$.css --source-map
  • In the Output paths to refresh field, type:

    $ProjectFileDir$/css/$FileNameWithoutExtension$.css $ProjectFileDir$/css/$FileNameWithoutExtension$.css.map
New File Watcher with custom output path

Save the new File Watcher and make sure it is enabled.

New File Watcher with custom output path saved and enabled

Now, if you edit custom_output.less, for example, change the value of @color at line 1, WebStorm creates a css folder and stores the generated custom_output.css and custom_output.css.map files in it.

Custom settings: the output is stored in a separate folder

Custom output location: preserve the original folder structure

Let's now consider an example where .less files are stored in a folder structure, for example:

Project structure

With the default File Watcher, the generated files will be stored next to the original .less files. If we use the custom File Watcher as described above, all the generated files will be stored in one same css folder:

Custom output: the generated files are stored in a separate folder in a plain structure

To have WebStorm preserve the folder structure, let's create another custom File Watcher.

Press Ctrl+Alt+S to open the IDE settings and then select Tools | File Watchers. , then create a Less File Watcher as described above.

Update the default settings as follows:

  • In the Arguments field, type:

    $FileName$ $ProjectFileDir$/css/$FileDirRelativeToProjectRoot$/$FileNameWithoutExtension$.css --source-map
  • In the Output paths to refresh field, type:

    $ProjectFileDir$/css/$FileDirRelativeToProjectRoot$/$FileNameWithoutExtension$.css $ProjectFileDir$/css/$FileDirRelativeToProjectRoot$/$FileNameWithoutExtension$.css.map
Custom output with folder structure: File Watcher updated

Save the new File Watcher and make sure it is enabled.

Custom output with folder structure: File Watcher saved and enabled

Now, if you edit custom_output_body.less, custom_output_header.less, or custom_output_footer.less, WebStorm creates a css folder with the subfolders' structure that preserves the structure of styles_structured.

Custom settings: the output is stored in a separate folder, the structure preserved

Configuring syntax highlighting

You can configure Less/Sass/SCSS-aware syntax highlighting according to your preferences and habits.

  1. In the Settings dialog (Ctrl+Alt+S) , go to Editor | Color Scheme | Less/Sass/SCSS.

  2. Select the color scheme, accept the highlighting settings inherited from the defaults or customize them as described in Colors and fonts.

Last modified: 20 February 2024