HTML & CSS
Article

A Good Front-End Architecture

By Matt Carella

Setting up a good front-end architecture is a fundamental step to start developing a web app or a website. Good practices and coding conventions are essential, but what about the structure? How can we conceive a good architecture that is maintainable in time? But most of all, where should we start from?

When I started thinking about the problem, I realized I needed a couple of things:

  1. I wanted a multi-page project (a web app or website).
  2. I wanted my project to support different screen sizes and resolutions, in other words: I wanted it to be responsive.
  3. I wanted the final product to be maintainable.
  4. I wanted the final product to be performant.
  5. I wanted to reuse the same template for any future project.

The right tools

Nowadays we have a lot of cool tools that can help us in a modern front-end developing workflow. So, in facing points 1 and 2 I told myself I needed a breakpoint-based CSS architecture that could help me support different devices and desktop sizes. On the other hand, I also knew that such huge amount of CSS and files could be a bit messy (and so incompatible with point 3.), that’s why I decided to start using a CSS preprocessor (which was Sass with Compass in my case).

And what about the point 4? The answer was easy: I decided to use Gruntjs. Finally, what about point 5? Even in that case, the answer was there: Yeoman, the best solution in my opinion.

Organizing the workflow

Every front-end project always includes libraries, jQuery plugins, and a lot of JavaScript and CSS files (or SCSS files in this case) for different purposes and aims. Blending all those elements means working with different technologies and putting them together means setting up a good front-end workflow. We would find ourselves having to manage a huge workflow that involves different technologies. That’s why having everything organized in folders, following a pattern or a convention in order to keep things clear and neat, is really important.

We can choose to split all fundamental front-end components in macro-groups, such as the following:

  • SCSS files
  • scripts
  • views

Can we we split them in smaller groups? Of course we can:

  • SCSS
    • variables
    • mixins
    • common parts to every layout
    • single layouts
  • js
    • libraries (such as jquery, angularjs, gAnalytics and so on…)
    • plugins (typically jquery plugins)
    • controllers (I mean controllers such as angularjs controllers)

In a templating based architecture (for example using blade.php or jade with nodejs) we can also split views as follows:

  • views
    • common parts to every view
    • single views

But I am not discussing this case in this article, since I am assuming that there is only one view (an HTML file) for every page or layout in my project.

Starting from all of these preliminary considerations, this is how I decided to organize the architecture, here is my folder tree:

project
  \css
  \imgs
  \js
      \controllers
          pageOne.js
          pageTwo.js
      \libs
          angular.js
          jquery.js
          analytics.js
      \plugins
          jquery.tooltip.js
          textResize.js
          formValidation.js
      \views
          pageOne.js
          pageTwo.js
  \scss
      \framework
          _core.scss
          _forms.scss
          _input.scss
          _mixins.scss
          _variables.scss
      \layouts
          _all.scss
          _phablets.scss
          _tablets.scss
          _desktop.scss
          _desktop-large.scss
          _retina.scss

          \pageOne
              _all.scss
              _phablets.scss
              _tablets.scss
              _desktop.scss
              _desktop-large.scss
              _retina.scss

          \pageTwo
              _all.scss
              _phablets.scss
              _tablets.scss
              _desktop.scss
              _desktop-large.scss
              _retina.scss
      \libs
          _animate.scss
          _normalize.scss
          _reset.scss
      \plugins
          _jquery.tooltip.scss
          _jquery.fancyInput.scss

Folders explanations

imgs

I decided to put all images files here: .png , .jpg , .jpeg , wallpapers etc.

Examples: icon.png, home-background.jpeg, userAvatar.jpg

js (mainfolder)

I decided to put all .js files here, organized in subfolders as follows:

\ controllers (subfolder)

This is the folder for angular controllers, each one with the same name of the corresponding view. For example, if your home.html needs an angular controller, you should create a file like this: project\js\controllers\home.js.

Examples: home.js, user-registration.js, user-login.js

\ libs (subfolder)

I created this folder for javascript libraries. When I say libraries I don’t mean plugins, that’s why I decided to distinguish between the first ones and the second ones, creating two different folders.

Examples: jquery-latest.js, angular.js, googleAnalytics.js

\ plugins (subfolder)

Plugin need dependencies to work, libraries don’t. So here is why I created a different folder:

Examples: jquery-fancyInput.js, restangular.js, customPlugin.js, jquery-airport.js

\ views (subfolder)

I created this folder for all the presentational stuff. Each file has to have the same name of the corresponding view. For example if your home.html needs some effects, stuff, and plugins initializazion, you should create a file like this: project\js\views\home.js, that has its own document ready.

Examples: home-animations.js, user-registration.js,user-login.js, site-animations.js

css (main folder)

This folder contains all of the generated css from main the scss files. For example home.scss will generate the corresponding home.css file in this folder.

\ libs (subfolder)

Even for the CSS files I am distinguishing between libraries and plugins. Here are some CSS library examples:

Examples: _meyers-reset.scss, _normalize.scss,_animate.scss, _960gridSystem.scss

\ plugins (subfolder)

CSS files contained in this folder are necessary styles to make JavaScript plugins work.

Examples: _jquery-fancyInput.scss, _jqueryTooltip.scss

\ framework (subfolder)

I decided to put scss files shared across all project pages in this directory

The framework subfolder will be organized as follows:

  • _variables.scss (project variables declaration – colors, spacings, etc.)

  • _mixins.scss (project mixin declaration – typography, clearfix, animations, etc.)

  • _forms.scss (custom form styling & reset)

  • _input.scss (custom input styling & reset)

\ layouts (subfolder)

And here is the responsive part. Files in this directory are organized in that way that they cover all screens resolutions, following a mobile first principle. So, you should start declaring your own styles using _all.scss file. Rules declared in this file are valid for all screen sizes and all views. If you want your website to be adaptable, than just rewrite rules and declare them for any other screen resolution.

The folder is organized as follows:

  • phablets (481up) _phablets.scss

  • tablets and small laptops (768up) _tablets.scss

  • desktops (1030up) _desktop.scss

  • desktops with large screens (1204up) _desktop-large.scss

  • retina displays exceptions (@2x) _retina.scss

These files will handle layout exceptions and are called by mediaqueries.

Please note: those files are shared across all views (HTML pages). That’s why you need to create a new folder under scss\layouts to give a specific style to a specific page.

EXAMPLE – if you want to style a responsive home page and a responsive user-login page

  1. Create under scss\layouts a new folder naming it with the same name of the views that you want to make adaptive (ex. home and userLogin) so: scss\layouts\home and scss\layouts\userLogin

  2. Put the same files listed up above into these folders: _all.scss , _phablets.scss , _tablets.scss , _desktops.scss , _desktop-large.scss and _retina.scss.

The final result

The final result is a Yeoman generator to scaffold a responsive multipages web app or website. I also decided to include some Grunt tasks for minification, obfuscation and Sass compiling. You can have a look at it here https://github.com/mcarella/wormhole, or download it directly from NPM: https://www.npmjs.org/package/generator-wormhole.

Where to go from here

I know this is not a universal solution, maybe in your case it looks like it includes some redundancy, and I know that it cannot suit all situations, but I think it is a good starting point. You can add as many grunt tasks as you want or organize your scss in a different way, making it lighter or fatter. No matter what your aim is, I usually advice people to roll their own architecture or framework tailored on their needs, paying particular attention to performance and maintainability without neglecting user experience.

Comments
independentbrit

Good advice. However, back in the days of dos this would have been standard practice. Are we re-inventing the wheel or has modern computing made us lazy?

Michael_Morris

What is old hat to some will always be new to others. Instructional articles tend to be aimed at newcomers unless the topic is an emerging technology.

independentbrit

My apologies, I didn't mean to sound patronising. I mis-read the article and thought the layout was being proposed as a new technique. As instruction, it is good advice and will create a sound base to work from.

andersomxp

Nice article. I'm also using sass in search of a template to streamline and organize the workflow find this, FireShell

niall_obrien

I disagree. I think having device specific stylesheets is a bad idea. Also, with the above structure, if I have phablet.scss open, I've no idea which feature it belongs to.

Instead, give your breakpoint variables sensible names and name your stylesheets by feature. Then use media queries with your breakpoint variables to style each feature per device. See how http://refills.bourbon.io/ do this. It makes for very modular code and this is the approach I always recommend, especially with large projects.

Tarabass

This is why I choose ExtJs as my main platform. It has it all without all the hassle.

Michael_Morris

Because of the rise of phablets I've started working with size classes, orientation and aspect ratio in tandem to determine item placement.

Landscape width breakpoints: 480, 568, 667, 768, 840, 950, 1024, 1280, 1600, 1920
Portrait width breakpoints: 320, 375, 414, 480, 600, 768, 1080, 1200
Aspects (most to least square): 5/4, 4/3, 5/3, 3/2, 16/10, 16/9

ralphm

You can easily end up chasing even more and more of these numbers. "Responsibly responsive" layouts (as they are being called) needn't worry about all those numbers, but only make sure there are a few key styles ("breakpoints" if you must) to accommodate the particular layout in question.

Michael_Morris

It really depends on the design. In any event, I rarely use more than a few with a given layout. But I test most all of those dimensions.

ralphm

I guess I test them by just widening and narrowing the viewport on my desktop browser—which covers all widths. These days I prefer pretty much a single column, flexible layout where breakpoints are almost (if not entirely) irrelevant. Many designers are not prepared to go that far with layout, which is understandable, but I'm less and less convinced that multi-column, elaborate layouts really offer much of use on the web.

Michael_Morris

I used to do that, but that can miss some outliers and my QA department would invariably find something I missed. I now have Firefox DE setup to run through the 16 most common devices sizes on the market, and so far that's kept them happy.

PaulOB

The problem with pre-defined device breakpoints is that you never know what size the next device will be and thus you may miss the next big thing. You are always working in the past instead of looking into the future.

A few years ago the ipad didn't exist so the existing pre-defined breakpoints were useless and missed a great share of the market. Designers then added the ipad breakpoints to their system but a year later the ipad mini came out so they missed that one also.

Phones first got smaller and now they are getting bigger again. The iphone 4 was a 320px wide device but the 5 and 6 have changed again.

Chasing devices is futile in nearly all respects.

Following the method that Ralph outlined above you would have collected all those devices old and new by simply catering for the design and not the device. You won't miss anything and nothing will break because you have created a page that goes from large to small with a few well chosen design-breakpoints.

Of course some designs are awkward to code like this where the designer has essentially created a series of fixed width sites but that is a methodology that is bound to fail at some point.

Recommended
Sponsors
Because We Like You
Free Ebooks!

Grab SitePoint's top 10 web dev and design ebooks, completely free!

Get the latest in Front-end, once a week, for free.