When using monolithic frameworks such as Angular, it’s easy to lose sight of just what they are. They’re Single Page Application (SPA) frameworks. They’re built for purpose and Angular is a strong candidate in the running for one of the best SPA frameworks today.

We use Angular over at Old St Labs. We haven’t always loved it but we’re getting there.

The Problem

The problem with some projects is that we aren’t always aware of how big they’re going to become. We might set out to build a small application and two years down the line, it’s huge. It happens, we add features, we add tests and we improve.

This is a common problem in software development and it’s also what happened to us at Old St Labs.

When we started to build Vizibl, we knew how we wanted it to feel. We wanted it to be mobile first. We wanted it to be responsive. We wanted it to flow well for the user, much like a native application.

What we didn’t know was how much of a beast the application was going to become.

We started using Angular in its early stages. We had a small team and few features. Both of these things soon changed and it became difficult to work on the application.

Angular lacks structure and good documentation. There is no right or wrong way to structure your application. Too much left open for interpretation is not always a good thing.

This wasn’t the only issue we were running into.

Our application had a tonne of features. Each feature was using another’s CSS rules and styles to keep CSS file sizes down.

This was great in one aspect, but a terrible idea as soon as the application began to scale. You change one feature and it’s game over. Styles all over the app start to change and you have no idea what happened. It’s an easy thing to lose track of.

A Component Based Architecture

We decided to adopt a component based architecture, the savior to all our problems.

We decided that every component would live alone. Then building templates and pages would be like building blocks. You chose the components that make up a template (minus some minor configuration).

This is a good way to approach large application structure and it worked well for us. It still does work well for us.

Rather than build templates, we build components. A series of components make up a template. Or a template can consist of one component only. A component can be a sole individual that doesn’t need a template to exist. It just makes everything easier.

Each component has its own individual set of JS and CSS that it relies on. They are completely independent.

This is helpful to us in many ways. The key factor here is consistency. We have a brand. When we change one of our components, we want every instance of that component to change too.

There are many others reasons why this approach works so well for us:

Components are stateless. They’re built to accept data and display it the way they’re told to. They may manipulate data but they never keep the manipulated state. Should anything need to go via an API, it’s handled elsewhere.

Components have their own CSS.

They lower specificity and help make CSS more maintainable.

They lower specificity and help make CSS more maintainable. It’s organised.

The Brand Guide

A component based architecture is great. It’s a great way to scale a SPA. It’s a great way to organise code. It’s a great way to keep developers happy.

We took it a step further. We decided that a component based architecture wasn’t enough.

As a team of engineers grow, it becomes more and more difficult to manage output. Code must be reviews and tested. It has to meet specific criteria and adhere to the internal documentation, if any exists.

The same rules apply when an application grows too. You want to ensure that your code does not affect anything else in the application.

There are ways to prevent this. Unit testing, regression testing, end to end testing, smoke testing. Testing. We live for these tests at Old St Labs. But it’s not always enough.

CSS changes can slip through the net. JS changes can have adverse affects depending on their environment. A component in one place might behave completely different to its replica in another. Just because of its surroundings.

This is why we have The Brand Guide.

This is nothing new. Many companies adopt the use of a brand / style guide to aid in their development workflows. It’s also a great way to showcase your components and it’s attractive.

We decided to package up our components and core styles into its own bundle. It lives completely separate to our main application. On its own subdomain. On its own own server. Deployed alone.

We do this so we keep better track of changes to components and also version our components.

Every time we make a chance to something, we bump the version number with either patch, minor or major. Typical semvar.

We now have a log of what has changed in each version release. Every release gets published to an AWS S3 bucket. We know if there was a new feature added, a breaking change or a bug fix.

This makes thing much simpler in our main application. We can update our build script to accept a version of the components files we want our application using.

This makes testing new features in their environments much simpler. We can be running v1 in production, v1.3 on our staging site, and even give certain users access to v1.5 if we wish.

This also makes rolling back changes much simpler. Should we find an issue. We can roll back to the last working version of our components while we address any issues.

Components go through their own suite of tests on the brand guide before they get published. They’re subject to code reviews and QA by other peers.

If components don’t pass their tests on the brand guide, they’re not going to get published. They can’t be used in the application.

This approach means we can have many instances of a component running on the brand guide. Each can have its own set of fixture data from the API to simulate a replicate component.

This approach has improved our work flow and increased stability within our application. It stops bugs from slipping into our application and it keeps our components consistent.

Whilst this isn’t a perfect solution. It’s getting there and it’s working for us. Maybe in the future we will improve this workflow to include a small library of reusable classes. Who knows?

We get better at this stuff every day. We’re always learning and there’s always a challenge to solve. If that sounds like your sort of thing, give us a shout.