The New SASS Module System: Out with @import, In with @use
Tags: css, sass, frontend, webdev
Published: 2020-08-04 22:32:49

In October of 2019 Sass [announced] (https://sass-lang.com/blog/the-module-system-is-launched) 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] (https://sass-lang.com/documentation/modules).


## 


## 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] (https://sass-lang.com/guide) 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:

![Proposed SCSS Folder Structure & Styles Organization](https://dev-to-uploads.s3.amazonaws.com/i/4ma2pntpb5llbs5lm7rn.png)


The key things to highlight in having this format are:
1. 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.
2. 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.
3. 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] (https://sass-guidelin.es/#the-7-1-pattern) is very well known and highly recommended by the Sass developers.


---


## Resources
- <https://css-tricks.com/introducing-sass-modules/>
- <https://blog.logrocket.com/the-definitive-guide-to-scss/>
- <https://sass-lang.com/guide>
- <https://www.studytonight.com/sass/sass-forward-atrule>
- <https://sass-guidelin.es/#the-7-1-pattern>