Forem: Stefanie Fluin

The New SASS Module System: Out with @import, In with @use

Stefanie Fluin — Tue, 04 Aug 2020 22:32:49 +0000

In October of 2019 Sass announced their new module system, which primarily addressed the switch from using @import to @use instead. Let's dive into what this means and how you should be using this new way to structure your SCSS files.

📝 Note: The new Sass modules and what is outlined below is only compatible with Dart Sass 1.23.0. If you are using LibSass as your Sass engine (ex. VS Code CompileSass uses LibSass) you may have to wait a while longer.

What is @use

@use is the replacement for @import which allows other stylesheets to use its variables, functions, and mixins.

What makes the @use import different is that the module (file imported using @use) is only imported once, no matter how many times you reference it in your project.

💁🏼 Tip: You'll see references to what Sass calls "members" - these include variables, functions and mixins within stylesheets.

How to Use @use

General File Import

The syntax to import a file is almost identical as to what we were already used to with the @import method.

Before:
@import '_buttons.scss';

After:
@use '_buttons.scss';

Referencing Members

The new modular system does not make all variables available globally. Furthermore, it creates what is called namespaces for each partial / module, which is the file name by default.

This means that you have to append the variable name with its namespace name when referencing it in your stylesheet. This helps with naming conflicts in the event you have the same variable name across multiple files, such as $width in _card.scss and $width in _button.scss.

Before:

footer {
    background-color: $forestGreen;
}

After:

footer {
    background-color: constants.$forestGreen;
}

Changing the Namespace (Reference)

If typing out partial stylesheet names seems like too much of an effort, you can modify the name reference as follows:

To Change the Namespace Reference
When importing: @use 'constants.scss as c;`

When using: background-color: c.$forestGreen;

To Avoid Having to Use a Namespace Reference
When importing: @use 'constants.scss' as *;

When using: background-color: $forestGreen;

💁🏼 Tip: You can also explore using the @forward rule which does not add any namespaces to names. This is primarily intended for library authors who want to expose only certain parts of their systems or when you want to group several individual pieces into one namespace. Read more about it below.

Private Variables

Members that begin with - (hyphen) or _ (underscore) are private to the current stylesheet with @use.

For example, you can reference a private color variable named $_primaryRed in your _buttons.scss partial which will only be accessible in that file, and not globally, say in a _footer.scss partial elsewhere.

Internal Built-In Modules

You may have used built-in Sass functions in the past, such as adjust-hue and map.get. Most of these built-in functions will remain available, but not on a global level. This means that you will also need to import these modules using the new @use import rule.

@use "sass:color"; or @use "sass:math"; or @use "sass:map";

There are a total of seven built-in modules with very useful functions that you can import. You can read more about them here.

File Types

Partials

Partial files are formatted with an _ (underscore) at the beginning of the name such as _.buttons.scss. These files are intended to be parts of a larger system. They are meant to be used as modules and not compiled on their own. I typically have partials roll up into the a main directory file (see next section) that is grouped by types of styles.

Index Files

Index files are automatically loaded when you load the URL for the folder into the main stylesheet (styles.scss).

In the past, you may have created a partial directory file such as _components-dir.scss that may have imported (@import) partial files such as _labels.scss and _buttons.scss. Now you simply have to either @use or @forward the partials into an _index.scss file within that folder, and make sure you @use the folder name, in this case components, in your main styles.scss file.

// components/_index.scss
@forward 'labels';
@forward 'buttons';

// styles.scss
@use 'component';

📝 Note: Sass can also load plain .css files using the same @use 'avatar'; format! Just remember that plain .css files can't take advantage of special Sass variables, functions or mixin features, but it can be extended using @extend in a Sass stylesheet.

@forward Rule

After some digging, the @forward rule is quite interesting. What it does is let your members, such as variables, of a forwarded stylesheet be accessible outside of the @use stylesheet that imports it.

Using this rule follows a similar syntax as the other import rules:
@forward 'list';

💁🏼 Tip: You can include both @use and @forward rules for the same module in the same file but it is recommended that you write the @forward first.

Conclusion

The new modular system that implements @use is now available as of October 2019. As of October 2021 @import will be deprecated, along with global built-in functions, and one year after that (no later than October 2022) @import support will be dropped. Make sure you go check out the newly refreshed Sass documentation for the latest updates.

After Thoughts

I personally really enjoyed having globally-accessible variables with my Sass structure, and leaving the modularity to the folder structure itself. This worked for me because I was very meticulous about never using the same variable names, and I often had the liberty of setting up a project stylesheet system by myself, instead of working with several developers (at least usually not until everything was set up).

With that in mind and my personal preference in naming things, this is how I think I will be formatting my Sass folder and file structure in the future:

The key things to highlight in having this format are:

The main folder names have numbers in front of them, such as 0-base to ensure that the folders stay in that particular order. You can certainly omit this or choose different folder names.
The folder index files use @forward with stylesheets that have members that I may want to use in other stylesheets so that they can be easily imported. For example, I import the 3-helpers files using @use which then lets me freely use the color variables from the _constants.scss file. You could theoretically do this with all index files, but if you want more control you can only @forward the files that you want access to more frequently.
I rename the namespace of the 3-helper import so that I can use it freely without having to type the extra namespace characters - color: $forestGreen versus color: $helper.forestGreen.

Tip: If you want to check out a different structure system, the 7-1 Sass architecture method is very well known and highly recommended by the Sass developers.

Resources

How to Structure SCSS in an Angular App

Stefanie Fluin — Fri, 31 Jul 2020 23:17:59 +0000

If you're a lover of SCSS, you'll definitely want to make sure to use it in your Angular applications. Luckily the Angular CLI does all the setup for you!

Let's first walk through the file changes that the Angular CLI handles for us and how you can modify existing projects to switch over to SCSS for styling. I'll then go over how I like to set up my SCSS files and folder structure when working on Angular projects.

Let's get into it!

New Project Setup Using Angular CLI

When creating a new Angular app using the ng new app-name command, the CLI will ask you "Which stylesheet format would you like to use?" - select SCSS.

When choosing this option when creating a new project, the main things the CLI does is the following:

Adds the src/styles.scss reference to the angular.json build/options/styles section
Creates a styles.scss file and adds it to your src folder

The CLI will configure the testing files and references as well, but we won't go into those here.

💁🏼 Tip: Run ng --version in your terminal to check what @angular/cli version you are running, and update to the latest using npm i -g @angular/cli@latest.

Switching Existing Angular Project to SCSS

If you ever need to switch to the SCSS stylesheet format in an existing project, having the two items above should be all you need to get going!

Updating CLI Config

The other thing you need to do is update your CLI configuration to create SCSS files instead of CSS files when you create new components. There are two ways to do this - using the CLI command or adding the reference manually. To use the command type the following into your terminal:

ng config schematics.@schematics/angular:component.styleext scss

💁🏼 Tip: Sometimes this command modifies the angular.json in the wrong place. Make sure it is modified in the top section of your file under your project (usually line 8 or so if you don't have many configuration changes).

To make the change manually add the following schematics reference into your angular.json file:

"schematics": { "@schematics/angular:component": { "style": "scss" } },

Using the SCSS-Scaffold NPM Package

A while back ago I created an Angular Schematic (you can read more about it here) that adds of all of the SCSS folder structure for you with the easy command npm add scss-scaffold, so you don’t have to 😊.

You can check it out the post I wrote about it here.

SCSS Structure

Global Styling Philosophy

You certainly can keep things simply by having one global styles.scss SCSS file, and you can also use styling on a component-by-component basis.

I like to keep my styles as global as possible avoiding component styling as I find that things can get very messy very quickly, especially when working on teams with multiple developers.

Having global styles keeps everyone using the same structure and system, and encourages discussions about patterns and use cases.

SCSS Folder Structure

Once you have your Angular project ready and set up to use SCSS, it's time to move some things around.

To get things started:

Create a folder in your src project folder called styles.
Move your styles.scss file into the newly created styles folder.
Update your angular.json file to point to the new location of your styles.scss file.

Now, it's time to build out our folder scaffold. I like to follow something similar to the 7-1 Pattern but modify some of the names.

Below is an example of how I lay out the style folders:

Base Folder

My base folder contains global styles which has some general layout items, a few general default overrides (think normalize.css-type styles), and my base font size so I can use rems consistently.

The other thing my base folder contains is a typography stylesheet for all things fonts. This not only includes headings and general fonts, but also links and other custom font classes as needed.

Pages

I try to use pages sparingly but this is where I put non-standard styles that apply only to a certain page. I often look for patterns and systems to apply globally to re-usable elements, but sometimes when there are some custom considerations, this is where I'll place them.

Modules (or Components)

The Modules (or commonly known as Components), keeps all of my reusable component styles. This includes things like the header and footer, buttons, labels, navigation, cards, or any other elements that you are using throughout your project in several places.

Helpers

Helpers is where some of the most important things are. The first thing you'll need is your constants. This stylesheet contains all of the variables for your colors, font-families, z-indexes, and some default sizing. For example, I like to add $border-radius-large and $border-radius-small variables to help keep that aspect consistent throughout the app.

You'll also want to add a mixin stylesheet for some custom-made reusable elements. Mixins allow you to take in arguments - I like to use them for shapes and also for font groups (such as defining a base "title font" style that I can then build upon in my other stylesheets.

Vendors (Optional)

Lastly, you might want to include a vendor folder if you're incorporating a third party library like Bootstrap or Normalize.css. Sometimes it helps to keep any vendor-specific configuration or override styles in this vendor folder. You can also import only those specific stylesheets (such as Bootstrap base tools) and keep that here.

💁🏼 Tip: When installing a vendor library, say using NPM, make sure you update your angular.json file to reference it's source location such as:

"styles": [ "../node_modules/bootstrap/dist/scss/bootstrap.scss", "styles/styles.scss"

Print Stylesheet (Optional)

The other file I sometimes like to include is the print.scss stylesheet that covers any custom print styling of your site. This is especially helpful on very animated or colorful websites that contain technical documentation - you might want to include styles that simplify things, and possibly omit elements for printing for easier content digesting. You could easily put this in your base folder, but I like keeping it separate as it often modifies content significantly different than intended for the overall application when used in its natural format (digital device).

SCSS Directory Files

SCSS structure includes having a directory file (i.e. _base-dir.scss) in each folder that includes all of the individual stylesheets within that folder. Those directory files, then roll up into the 'main' styles.scss folder which helps keep things clean and organized, and easy to read. I like to set up my directory files to look something like this:

The header helps me quickly know what I'm looking at - especially when I'm editing a lot of files. Below are the important pieces where you import the individual stylesheets within that folder, in this case, the base folder.

💁🏼 Tip: Make sure that you add your import to your directory file every time you create a new stylesheet inside of a folder.

SCSS Main File Roll-Up

The last thing that you need is to roll-up all of those directory files into your main styles.scss file that is actually being read by your app (as we told it to in the angular.json file).

This is what my styles.scss folder might look like:

💁🏼 Tip: Remember that the order of imports matters! If you're using constants / variables that your other stylesheets reference, you'll need to make sure that directory import is at the top being imported before the files that are using those variables.

Using Component Styling

If you do want to use component styling but still want to use some of the SCSS structure, you can simply import the specific stylesheet into your your-component.component.scss file using this format:

@import 'styles/variables';

Note that you'll have to update this path if you ever move this file or change its name.

Summary

That's it! Once you have SCSS up and running and a nicely organized folder structure, it should help you be much more efficient and organized when it comes to maintaining your stylesheet / CSS code.

Happy coding!

After-Thoughts 📋

Although the CLI has lots of configuration options — I find myself wishing there was a “no styles” flag (similar to the --skipTests=false flag that currently exists) when creating components. Since I structure all of my stylesheets independently in my styles folder, I don’t ever have the need for component based stylesheets.

Luckily, if it’s something you’re looking for there are flags for inline styling, external styling and changing your stylesheet preference configurations (as we saw above).

Resources 🧰

Here are some resources if you want to learn more about SCSS and the using SCSS with Angular and the CLI:

SASS Guidelines
Official SASS Lang Layout
Scotch.io Tutorial (outdated but helpful background info)
Angular CLI Commands