Front-end Architecture — Part 1: File Structure

For years, as front-end developers, we structured our files by separating the three pillars of the internet: HTML, CSS, JavaScript. This separation of concerns was great as it allowed us to layer up our pages from the bottom up.

This style suited content focused sites like blogs and documents (the origins on the net) well. However, as websites have become more interactive and software like, the mindset has had to change.

Following the principles of something like Atomic Design, you can think about the UI elements of your site as a series of separate components linked together in a snapshot view (page).

Atomic design is methodology for creating design systems. http://bradfrost.com/blog/post/atomic-web-design/

Each component should only be concerned about itself, displaying the data passed to it, and dispatching appropriate actions when interacted with.

Split by components

Leading on from our first awesome site, we might decide to split out the HTML, CSS and JavaScript into separate files to help manage our site’s components. We can use tools such as SCSS, Twig and Browserify to handle compiling the files into a fully working site.

This is an even better separation than we had before. Each component has its own file for HTML, CSS and JavaScript which lets us focus on a smaller piece of code to perfect. Smaller focus means more of your brains processing power can be devoted to making that piece of code solid as a rock.

The problem we have with this setup is that, whilst we have split our files into components, we have still split them into their respective languages. This leads to a dual split in the mental model, and finding all the code related to a component can be difficult in a large project.

Grouped by components

The next stage is to regroup our files purely by component.

We still have a couple of base SCSS and JavaScript files in their own folders, but the majority of the UI code is now grouped by component. This means each component is entirely focused on itself and can be refactored or removed with little concern for the rest of the UI.

Working with a back-end team

In a traditional waterfall development flow, the front-end team might build out full templates and pass them to the back-end team to integrate. Conversely the back-end team might build out the functionality and pass to the front end team to style up.

Schema driven

To allow us to run both development flows in parallel, we turn to Schema driven development.

A JSON Schema is a way of defining the expected data for a component. In the one above, we require a title and content property to be passed to the component as strings.

By defining this schema before starting build, both the front-end and back-end teams can be working towards the goal of either providing the data or dealing with the display of the data, without needing to be concerned with the state of each others work.

This massively speeds up our build process to make better software faster.

Prototyping with dummy data

Whilst focusing on the UI, we’ll need a way to test different data variations to make sure our component handles them correctly.

We add a folder called variants within the component folder. This can store multiple JSON files containing different states/variations for the components display.

These can be fed to the component in our styleguide/component library so we can see the behaviour live. Importantly, this also gives us a nice array of data for testing.

Testing: functional and visual

Now we have a self contained component with a variety of dummy data, we have a component that can be tested in an isolated environment.

This is an important development as it opens up testing our UI independently of the rest of the state of our app.

We’ll need a route in the styleguide/component library where the variants can be viewing individually and we can then run functional and visual tests in them.

Functional component testing adds another layer of stability to your web site/app.

For visual testing, we can use something like Wraith or BackstopJS to test the visual appearance of our components has not changed since signoff.

This also gives us a library of reference images for each component that can be used without needing to run the app.

Documentation

Finally, we may need some documentation for our component. Good things to include are a brief description of the expected usage and functionality, as well as some typical use cases.

Component focused

As you can see we’ve come a long way since the simple split between HTML, CSS and JavaScript, but the internet has come a long way too. Whilst this may seem like a lot of initial work, it gives us a much more stable and flexible system to work with going forwards.

Prototyping becomes a breeze as we can throw different components together quickly on a page and know they will work.

Refactoring is safe and stable as we have a single source of truth for the behaviour and display of a component. We also know all the potential data structure from our schema.

Deployments are less nerve racking because we can be confident that our UI is solid, tested and working as expected.

Coming up in this series we’ll be going more in depth on each area of our component folder from CSS to JavaScript to testing and everything in between.

Make better software.