How using a monorepo has transformed how our Web Development team approach the build and maintenance of a family of websites for The Adaptavist Group.
You’ve started using a monorepo across multiple websites in The Adaptavist Group family. What was the history of this decision?
WS: We in the Web Dev team are building multiple websites for The Adaptavist Group (TAG) because they’re acquiring businesses, and those businesses need websites to be up fairly quickly.
So the history (which was over 2 years ago) started when adaptavist.com was built. Another brand asked for a website with a relatively quick turnaround, consisting of similar functionality, look and feel. We created a new project, copying much of the code that was used for adaptavist.com with some changes and improvements. This seemed like the right thing to do until another brand came along wanting something similar. We were like, ‘Oh, no, you're joking!’
So we had to ask ourselves; do we start thinking about how we can create something more reusable? We decided to build a package of common UI components and it went pretty well but there was room for improvement.
...we wanted to do things differently...ship functionality quicker, for multiple brands concurrently, but also provide a great developer experience. We did some R&D...a monorepo was the way forward!
Fast forward 18 months and the question around building a family of websites came up. We’d been here before and this time we wanted to do things differently, creating a solution that allowed us to ship functionality quicker, for multiple brands concurrently, but also provide a great developer experience. We did some R&D and came to the decision that a monorepo was the way forward!
Why is using the same code the wrong way to go?
WS: When two websites have a similar look and feel (using very similar code) it’s very easy to compare them. Imagine you're brand A and you want this new feature. We say, ‘That's not a problem’. But then Brand B comes along, with a very similar website, and sees the feature and says ‘You've given them that new feature! We want that as well!’ And all of a sudden we are having to maintain two projects to do the same thing, just to provide the same functionality. DRY (Don’t Repeat Yourself) is one of the principles of software development and we were breaking it.
So the premise is you have a ‘mothership’ where you do all the changes in one place and then they get pushed out to the ‘satellites’?
WS: Yeah, you have one source. And there's two ways of doing it; the first approach (which we took the first time round) was creating a shared ‘package’. It worked but it was difficult to maintain across multiple projects. When we made changes to the ‘shared package’ you had to manage the versioning and any potential changes across the projects that consumed the code. This meant more Jira tickets, more branches, more PRs and more deployments!
The second approach, a monorepo is much simpler; we manage one repository that houses multiple websites as well as the shared code (UI, schemas for the CMS, helper functions, etc).
You mentioned that you did some R&D. Was it a case of having to try a monorepo before you knew if it was the right way?
WS: Yeah, we'd never taken this approach before so myself and Matija (part of the Dev team) went away and created a proof of concept. The opportunity to use technologies, and the learning that comes with it, is what makes developers tick so we were stoked to get going. We quickly recognised that we could easily implement a design system which would provide websites a consistent look and feel, making the monorepo a very appealing solution.
You had to go through the pain of the initial fixes to understand how a particular sort of architectural solution lends itself to the evolving organisation?
WS: Yes. One of the advantages is that for each brand that comes on board, they get their website faster because we’ve done the hard work…
It sounds like it’s been a massive learning curve for everybody. Are you creating docs as you go?
WS: Yes, the importance of documenting as we go on this project can't be overstated. We have a team of developers using new technologies, and the potential risks are more significant than usual. Making a mistake or introducing a bug has the potential to impact multiple websites rather than just one, and documentation helps prevent this. We can't all be experts on every aspect of the project, but when tasked with something out of our comfort zone, we can work it out with good documentation. It also seriously helps when onboarding new team members!
What capture tools do you use?
WS: We use Storybook to showcase the solution to clients and streamline the workflows between departments, but it provides so much more than that from a developer's perspective. It offers tools that make it easier to test and build accessible, responsive, and compatible UI in isolation – in one convenient environment. Oh, and it provides automated documentation too!
Did everything go according to plan? Or were there challenges?
MS: There have been some hairy moments! Getting the deployments working with the Monorepo was a challenge. It's easy with a single site – but getting all the work flow in place is more challenging. And there were issues that weren't even our fault, like limitations with the platform we were using, and so we had to find workarounds to that. You can write something perfectly that works locally and it's brilliant, then when you come to deploy it, it won't deploy!
Do you put that down to the learning curve?
MS: In some situations… I have a list of things that I need to do to improve it. Eventually I'll have a slick system in place that we’re really pleased with.
This feels like the storm period…
MS: From my point of view and the issues I've had, I think it's probably lasted a little bit longer than I'd have liked. But you're still learning and you can never really account for everything that may happen. All you can do is deal with it when it comes up and make sure you learn from it.
WS: To give credit to the team, we thoroughly researched the different potential approaches and technologies before making any decisions, so the storm hasn’t felt too rough. We've frequently mentioned the monorepo, but much thought was put into the other technologies used too. For example, the developers were tasked with researching and recommending a CMS based on a list of requirements formed by clients, project managers, developers and designers. This gave us the confidence to move from Prismic to Sanity, which has been a revelation. I think this level of due diligence at the beginning, plus taking what we learnt from similar projects, has really paid off.
...we're excited to start thinking about the future...deliver websites faster, putting the control into our clients’ hands. As a team, we’ll start thinking about adding functionality that makes the product as self-serviceable as possible, and automating workflows.
You can't predict everything; there are always unknowns when choosing new tech. In this project, we didn't know what it would be like to use TypeScript instead of JavaScript. On the whole, I would say the team loved it, but finding a sweet spot for its implementation was tricky because people had varying skills using it.
Now the storm is settling, we're excited to start thinking about the future. We want to deliver these websites faster, putting the control into our clients’ hands. As a team, we’ll start thinking about adding functionality that makes the product as self-serviceable as possible, and automating workflows.
