How Hygraph uses Hygraph I: Why a rewrite

Every now and then there comes a new developer in the marketing team, who looks at the codebase and thinks to himself “Hey, instead of figuring out this monster, why don’t we re-write the thing in {insert_new_trending_JS_framework}”. And that’s exactly what we did.

However, it didn’t exactly happen that way. At some point last year, we realized that following the rebrand from GraphCMS to Hygraph, we had a lot of pages that had survived multiple cosmetic changes and have reached a point where it really made sense to make something new, funky, fresh, and scalable (and, yeah, perhaps also consistent).

Joking obviously on the JS framework part, we love them all, but we were quite happy with the tech stack we had: Next.js on the frontend, Hygraph on the backend, and a couple of other things in between that I’d let other, more skilled people talk about in the next parts of this article. So on the tooling side, it didn’t change much and we were lucky to have it happen at the time when Next.js 13 came out so we could also incorporate App Router right from the start. But more on that later.

Having said that, this article is part 1 of the 5-part saga on this journey and I aim to give you a glimpse into our website rebuilding project: what did we do, why didn’t we make the changes incrementally, why this may be the way to go sometimes, and, well, what are the drawbacks if you decide to take inspiration from us.

#What did we do and why not incrementally?

Given the issues I have briefly mentioned, when we were deciding what to do with the website, we came to the conclusion that we might require a design system. There are a few ways of thinking about this.

On one hand, our website is rather small with less than 1000 pages and you can reduce that to a certain number of templates that just keep getting reused. So why build a full-fledged design system for a website of that size? We might want to be flexible and keep changing things and when we need a new page that has a whole new set of requirements we can just build it from scratch without the constraints of a design system.

However, that kind of thinking led us to this path and precisely because we do change things quite often we wanted to have a centralized system where those things can be changed. And, there were other issues.

No link between the designers and developers

The way we worked prior to making this change involved very few reusable elements. New page designs were almost entirely from scratch, as was the implementation. This meant that the review process was taking too long and was rather inefficient.

The codebase was too big

You could almost predict this point reading the previous one. As we built the new pages almost from scratch, the codebase was getting out of hand. Some GraphQL queries were in the .tsx file for the page, some were in a separate folder, some content was in the CMS, some of it was hardcoded and I can go on, but you get the idea.

Inconsistency across pages

Throughout the years, we have changed a few things here and there regarding our visual identity, some smaller, some bigger, and it was getting harder and harder to make the required changes on the website as well. This led to many inconsistencies across different pages in terms of color schemes and other design details.

Improve collaboration between designers, developers, and content editors

If you think about the lifecycle of a certain landing page, our old way of doing things, would make it so that the stakeholder or person in charge of delivering a page, for example a PMM, would start with a rough mockup and content and pass it on to the designer who would then pass it on to the developer.

Oftentimes, this would cause the back and forth regarding what’s possible and what not between the three. The new way is that, in this instance PMM, can refer to the design system in Storybook to see which components and variations are available and construct a mockup and content around that or request a new addition in order to achieve what’s required.

Lack of single source of truth to refer to

This is probably one of the items that ChatGPT would offer us as one of the reasons to have the design system to begin with. Having it in place means we have no more doubts about the color codes, shadows and more.

Build pages more quickly

At the end, most likely one of the most important reasons to undertake this project is to become a bit more agile and built new pages more quickly and efficiently. When I mentioned the new page creation process before, here’s how that looks like now. We’ve got two types of pages:

• Templatized pages: page templates that require only content input in the CMS and will be rendered accordingly. Most obvious one is the one you’re reading this article on, but similarly the individual resource pages, events pages and alike.
• Modular pages: these take different inputs and a content editor can use nearly all available components to create a page. With this the content editor has a lot of flexibility, to choose the layout of certain sections, include an image, video or codeblock and a lot more. Here’s a quick overview of how would that look like for a hero section:

Accessibility

At the end, accessibility was also not something that we paid a lot of attention to in the past and at this stage we wanted to address it properly. So having a design system in place would allow us to work with a color scheme that is accessible. On the keyboard side we still have some work to do, but we did make a big first step.

#Again, why not incrementally?

Now, given the nature of the project, it was effectively a rewrite and the only way we could do it incrementally, was to serve parts of the website from the new repo as we progress. And, we categorically agree that all migrations should be incremental. So, we did come across the possibility of using the rewrites in Next.js, however, we (read: I) were skeptical for a few reasons:

• Setting up rewrites and reverse-proxy would cause a certain delay and possibly affect our page load speed. Now you may say, if properly done it’s insignificant and you may be right, but we didn’t want to risk it as our organic traffic was on a roll
• In addition, going through that process and making sure everything was correctly set up (only pages on hygraph.com are indexable in search engines, and similar) seemed not worth it, considering the effort vs. benefit given the size of the website. (Famous last words incoming) It was also highly unlikely we’d introduce something that would cause a major disruption in the world.

I have touched upon what we consider as the benefits we reap from successfully completing this project, but I’ll go over those now in more detail.

Future-proofing the marketing website

We wouldn’t go this route if we weren’t sure that this will set us up for success for a long period of time. The whole idea around it was to build something scalable that is also flexible enough to be agnostic to any kind of brand or visual changes in the future. At the same time, regardless of what type of pages we want to put out there, we can always add new components and new component variations.

Easier to change the templatized pages

This one is also an obvious one: say we want to update one component on a page that’s used across 300 pages such as blog articles; that’s something we can do rather easily and in one file that will reflect all of those 300 pages.

Easier to make bigger changes

I have touched upon this topic a few times previously but it deserves special attention, because we did go through a rebranding process and it required quite a bit of work to get things updated. Nowadays those can be updated in one central place and we are good to go.

Reduces dependency on horizontal resources

I have mentioned the way we build the modular pages and this means that there’s quite a lot we can do with the existing components. Meaning not every page will require a designer and developer in order to make it happen.

Brand consistency

At the end, this also helps us keep our brand consistent across the website.

#Is it all milk and honey?

Of course, it’s not. This kind of project requires a significant upfront investment. And you may argue whether for a website of our size it’s worth it or not, but we are doing things a lot more efficiently nowadays so it’s just a matter of choosing the right moment to do it.

Now I am not big on high-level graphs and quadrants, but if we wanted to make a scalability/investment and a time/investment graph on the design system vs. not having one, it may look something like this:

The other thing is that sometimes having to choose from a pre-defined set of components may seem like a significant constraint, but it’s doable and we consider our design system as something that’s constantly evolving.

That said, head over to the next part and find out how our design system is set up.