{"id":6236,"date":"2013-12-02T13:18:45","date_gmt":"2013-12-02T10:18:45","guid":{"rendered":"http:\/\/railsware.com\/blog\/?p=6236"},"modified":"2021-08-11T18:41:22","modified_gmt":"2021-08-11T15:41:22","slug":"organizing-stylesheets-in-ruby-on-rails-project","status":"publish","type":"post","link":"https:\/\/railsware.com\/blog\/organizing-stylesheets-in-ruby-on-rails-project\/","title":{"rendered":"Organizing stylesheets in Ruby on Rails projects"},"content":{"rendered":"\n

The asset pipeline in Ruby on Rails<\/a> is a very powerful, but somewhat confusing feature. By default, Rails scaffold generates a stylesheet per controller so that your styles were organized according to your application\u2019s domain model. Which is not really convenient when you are building a modular codebase and reusable components. We need to come up with some custom CSS architecture that will allow us easily create, modify and reuse elements.<\/p>\n\n\n\n

The asset pipeline basically performs the following: precompiles, concatenates, minifies assets and places them in the public\/assets folder. The asset pipeline is powered by the two technologies: Sprockets<\/a> and Tilt<\/a>.<\/p>\n\n\n\n

Tilt<\/strong> is the template engine that is used by Sprockets. It allows file types like sass, erb, coffee, etc. to be used in the asset pipeline.<\/p>\n\n\n\n

Sprockets<\/strong> itself performs the asset packaging, i.e. takes the assets from all the specified paths, compiles them together and places them in the public\/assets folder.
How does Sprockets know which files to concatenate and in which order? Here comes a keystone of the asset pipeline – a manifest file. It uses directives to declare the files to be included and an order of inclusion. You can have as many manifest files as you need – one per layout or one pre page, that’s entirely your choice.<\/p>\n\n\n\n

CSS Preprocessing<\/h2>\n\n\n\n

Asset pipeline makes it easy to use any CSS preprocessors like LESS<\/a>, SASS<\/a> or Sylus<\/a>. We usually work with SASS because it\u2019s awesome and it comes with a Rails app from the start.<\/p>\n\n\n\n

Every CSS preprocessor allows you to use functions, variables, mixins and other useful stuff that is shared across all modules and files. But in order to use them, SASS source code should be first combined and then compiled to CSS.<\/p>\n\n\n\n

In this case, there is an issue with using Sprockets \/\/=require<\/em> syntax to specify which files should be combined together. Sprockets compiles your Sass source code first as independent stylesheets, and then merges the resulting CSS into a single file. That’s why you need to import your mixins.sass at the top of each file, otherwise you’ll see an exception if you try to use any mixin. By using the @import<\/em> syntax, you are instructing the Sass compiler to combine the Sass source code first, and then perform the compilation.<\/p>\n\n\n\n

File organization<\/h2>\n\n\n\n

In most Rails projects, there are several layouts that have different styles, but there’s still common codebase that should be shared. So, here are some guidelines on how to organize you assets files and directories, so that they were easily extendable and had a flexible and well defined structure.<\/p>\n\n\n\n

Base styles.<\/strong>
All base styles that will never be changed – i.e. reset, grids, spaces and helpers – go to the base folder and are added to every manifest.<\/p>\n\n\n\n

Manifests files per layout.<\/strong>
First of all, you should create one manifest file per layout (if these layouts have different styles). By manifest I mean not sprockets manifest, but .sass file with all @imports of necessary files (variables, mixins, objects and modules).<\/p>\n\n\n\n

  \/\/ Base styles\n  @import \"base\/mixins\"\n  @import \"base\/reset\"\n  @import \"base\/grids\"\n  @import \"base\/spaces\"\n  @import \"base\/helper\"\n\n  \/\/ Layout specific styles\n  @import \"application\/typography\"\n  @import \"application\/layout\"\n\n  \/\/ Objects\n  @import \"application\/objects\/buttons\"\n  @import \"application\/objects\/inputs\"\n  .......................\n\n  \/\/ Modules\n  @import \"application\/modules\/profile\"\n  @import \"application\/modules\/dashboard\"\n  .......................\n<\/pre>\n\n\n\n
Folder for each manifest.<\/strong>
There should be one folder for each manifest file with the same name. application<\/em> folder for application.sass<\/em> file as a default layout. This folder will contain layout styles, typography, all objects and modules that are used in this particular layout.<\/p>\n\n\n\n
stylesheets\n  \u251c\u2500\u2500 base\n  \u2502   \u251c\u2500\u2500 mixins.sass\n  \u2502   \u251c\u2500\u2500 reset.sass\n  \u2502   \u251c\u2500\u2500 grids.sass\n  \u2502   \u251c\u2500\u2500 spaces.sass\n  \u2502   \u2514\u2500\u2500 helpers.scss\n  \u251c\u2500\u2500 application.sass\n  \u251c\u2500\u2500 application\n  \u2502   \u251c\u2500\u2500 layout.sass\n  \u2502   \u251c\u2500\u2500 typography.sass\n  \u2502   \u251c\u2500\u2500 objects\n  \u2502   |   \u251c\u2500\u2500 buttons.sass\n  \u2502   |   \u251c\u2500\u2500 inputs.sass\n  |   |   \u2514\u2500\u2500 ..........\n  \u2502   \u251c\u2500\u2500 modules\n  \u2502   |   \u251c\u2500\u2500 profile.sass\n  \u2502   |   \u251c\u2500\u2500 dashboard.sass\n  |   |   \u2514\u2500\u2500 ..........\n  \u2502   \u2514\u2500\u2500 responsive\n  \u2502       \u251c\u2500\u2500 tablet.sass\n  \u2502       \u251c\u2500\u2500 mobile.sass\n  |       \u2514\u2500\u2500 ..........\n  \u2514\u2500\u2500 shared\n      \u251c\u2500\u2500 popup.sass\n      \u251c\u2500\u2500 markdown.sass\n      \u2514\u2500\u2500 ..........\n<\/pre>\n\n\n\n
Inside every manifest folder you can put responsive styles under responsive<\/em> folder, divide your interface into objects and modules and put them inside the proper folder. This keeps your styles independent and modular. If you need to reuse some styles of different manifest folder – move them to a shared folder that is located on the same level as manifests.<\/p>\n\n\n\n
Conclusion<\/h2>\n\n\n\n
Proper assets organization is really important, because if you’re not doing it from the start, you will easily get lost in your stylesheets a month after the development has started. Conventions will help avoid messing styles of different layouts and slice your styles into smaller reusable parts. And, as a result, you will find everything in a designated place.<\/p>\n","protected":false},"excerpt":{"rendered":"
The asset pipeline in Ruby on Rails is a very powerful, but somewhat confusing feature. By default, Rails scaffold generates a stylesheet per controller so that your styles were organized according to your application\u2019s domain model. Which is not really convenient when you are building a modular codebase and reusable components. We need to come…<\/p>\n","protected":false},"author":23,"featured_media":9460,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[3],"tags":[],"coauthors":["Alex Chaplinsky"],"class_list":["post-6236","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-development"],"acf":[],"aioseo_notices":[],"categories_data":[{"name":"Engineering","link":"https:\/\/railsware.com\/blog?category=development"}],"post_thumbnails":"https:\/\/railsware.com\/blog\/wp-content\/themes\/railsware\/vendors\/images\/article-thumbnail-default.jpg","amp_enabled":true,"_links":{"self":[{"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/posts\/6236","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/users\/23"}],"replies":[{"embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/comments?post=6236"}],"version-history":[{"count":60,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/posts\/6236\/revisions"}],"predecessor-version":[{"id":13938,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/posts\/6236\/revisions\/13938"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/media\/9460"}],"wp:attachment":[{"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/media?parent=6236"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/categories?post=6236"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/tags?post=6236"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/railsware.com\/blog\/wp-json\/wp\/v2\/coauthors?post=6236"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}