Published May 2, 2021

Sass Clean Architecture

In today’s trends, Sass is becoming one of the most popular CSS Pre-processor in the world. As a front-end developer, we should make the project structure to be clean so it will become more maintainable in the future, particularly if you’re working with a team that requires teamwork.

Every company has its own project structure that may fit their requirement. Every frontend framework may have their own structure, but somehow they have similarity to make clean architecture. For instance, if you’re using Vue.js, sometimes you might code the Sass directly in the .vue component.

But for this article, I will show you my Sass project structure which I use in every single project.

sass/ 
| 
|– base/ 
|   |– _index.scss       # Entry file 
|   |– _reset.scss       # Reset/normalize 
|   |– _typography.scss  # Typography rules 
|   ...                  # Etc… 
| 
|– components/ 
|   |– _alert.scss       # Alert 
|   |– _buttons.scss     # Buttons 
|   |– _dropdown.scss    # Dropdown 
|   |– _index.scss       # Entry file 
|   |– _header.scss      # Navigation 
|   ...                  # Etc… 
| 
|– helpers/ 
|   |– _functions.scss   # Sass Functions 
|   |– _helpers.scss     # Class & placeholders helpers 
|   |– _index.scss       # Entry file 
|   |– _mixins.scss      # Global Mixins 
|   |– _utilities.scss   # Some utilities
|   |– _variables.scss   # Sass Variables 
|   ...                  # Etc… 
| 
|– layout/ 
|   |– _admin.scss       # Admin 
|   |– _index.scss       # Entry file 
|   |– _home.scss        # Home 
|   |– _user.scss        # User
|   ...                  # Etc… 
| 
|– mixins/ 
|   |– _alert.scss       # Alert mixins
|   |– _index.scss       # Entry file 
|   |– _buttons_.scss    # Button mixins
| 
|– pages/ 
|   |– _home.scss        # Home specific styles 
|   |– _contact.scss     # Contact specific styles 
|   |– _index.scss       # Entry file 
|   ...                  # Etc… 
| 
|– vendors/ 
|   |– _bootstrap.scss   # Bootstrap 
|   |– _datatable.scss   # DataTable
|   ...                  # Etc… 
| 
| 
| – main.scss             # primary Sass file

There are a bunch of folders and files in this structure, but we’ll breakdown it so you can understand it better.

main.css

As you can see above, we have main.css which have the responsibility to wrap all the code into one file. Thanks to Sass feature @import or @use that allow us to put all files in one root file. The following screenshot is the example content of main.scss file:

@use "./base";
@use "./components";
@use "./layouts";
@use "./mixins";
@use "./pages";

// Import specific vendors
@use "./vendors/bootstrap";

Sass has the feature to make css to be a module system. This is very helpful to organize your code into several parts so you it will be easily maintained and much more cleaner.

We can also use @import for substituting the @use. But, @import is being replaced with more explicit @use and @forward rules. Over the next few years Sass @import will be deprecated, and then removed. Read more about Sass module system at CSS-Tricks.

You may wonder why there’s _index.scss in every sub-folder. That’s the entry point for every modules. For example, we have one in components/index.scss in order to import all the components in a single file. Therefore we can simply import by using a single line @use "./components" which automatically refers to @use "./components/_index.scss"

base/

In the base/ folder are containing the root code of CSS that we setup every time we start new project. It includes some setup like reset CSS, importing and set up font family, and also you can put typography styles in there. Particularly when you are customizing the font styles, font color, etc.

components/

This is where all your components are located. Put your HTML5 components styling here, such as input, button, alert and many more! Make sure you don’t put another component’s styles on another file, it’s a bad practices. For example:

navbar.scss

.navbar {
    .btn {
        padding: .5rem .8rem;
    }
}

Pay attention to above code, putting base class .btn is a bad practice though. Insted, you could make a new class which is the modifier of button. For example below, I’m using BEM CSS methodology to make the modifier:

button.scss

.btn {
    &.btn--navbar {
        padding: .5rem .8rem;
    }
}

After you make all the component’s scss file, import all of those in entry file _index.scss so it can be more simple when you import in root file (main.scss). Below is the example of _index.scss:

@use "alert";
@use "avatar";
@use "badge";
@use "buttons";
@use "breadcrumb";
@use "carousel";
@use "card";
@use "divider";
@use "dropdowns";
@use "forms";
@use "modal";
@use "sidebar";
@use "navs";
@use "navbar";
@use "pagination";
@use "table";

layout/

Layout folder contains all the site’s style layout. If you have some different page layout like homepage layout (which has topbar and sidebar), product layout (with grid or flexbox), etc you might have to make a different sass file for every layout. In example above, I’ve made _admin.scss for admin layout and _user.scss for user layout page.

mixins/

Mixins are one of the most used features from the whole Sass language. They are the key to reusability and DRY (Don’t Repeat Yourself) components. This allow authors to define styles that can be reused later within a single line. If you’re familiar with functions in most programming language, this will help you alot.

Put your component mixins in one file. Especially, if you have bunch of mixins in one component then you really should put it in organized separate file. For instance, the following code is example of Bootstrap’s mixins folder structure:

mixins/ 
| - _alert.scss
| - _border-radius.scss
| - _box-shadow.scss
| - _buttons.scss
| ....

The _alert.scss contains only specific mixins for a component that we can use it. We can recall the mixin simply by using @include.

@mixin alert-variant($background, $border, $color) {
  color: $color;
  @include gradient-bg($background);
  border-color: $border;

  .alert-link {
    color: shade-color($color, 20%);
  }
}

pages/

You could additionally make the separate scss styling for specific page as well. For example, you want to customize just the admin dashboard page, then you have to make new _dashboard.scss file in pages folder. Then import it to the root file main.scss.

Be careful, don’t be too lazy by putting your CSS directly in the HTML page with <style></style> or somewhat inline css. Because it will cause the project more unorganized and messy code unless you’re using javascript to style directly on inline CSS.

vendors/

If you are using third party libraries on your project, you might have to import and explicitly make the separate file for that library. In this case, we’re making new vendor sass file in this vendors/ folder. If the vendors are serve the code with native css, you can move the content to the new .scss file.

For instance, you have to use bootstrap and want to import specific bootstrap component, therefore you have to copy bootstrap’s scss code to your project structure.

Conclusion

Every person has their own preferably project structure. You could find dozens of articles that shows one’s architecture, such as Kevin Powell’s Sass partials structure, or you may take a look at this article that present you numerous popular Sass architectures. I hope you find your favorably architecture which you can use in everyday’s project.