JAMstack adventures — HUGO vs Gatsby and Contentful
Lessons learned from migrating our website
Everything Changes
“Tα πάντα ρει” (everything changes) is a famous quote by the greek philosopher Heraclitus, indicating that change is constant. Presumably he wasn’t referring to web development, but the same applies in this world.
When I started working at Lenses.io I was introduced to the world of Hugo.
Hugo is an open source static site generator that the company was using at the time, and its syntax is similar to the GO programming language.
But what is a static site generator, I hear you ask?
The line is a bit thin when thinking of web application stacks and static site generators, but as nicely stated in netlify’s blog here:
“The greatest difference between a static site generator and a traditional web application stack, is that instead of waiting until a page is requested and then generating its view on demand each time, a static site generator does this in advance so that the view is ready to serve ahead of time”.
The need
Being a developer at a high-tech startup company like Lenses.io means that you will learn a lot.
Personally I think that’s the best part, and one of the reasons why I got interested in web development in the first place.
Constantly learning and evolving your skill-set/ knowledge is great. People at startups tend to be friendly, supportive and eager to help you grow. Or at least that is the reality I’ve experienced with Lenses.io.
But working at a startup can also have its downsides. Usually structures and roles are not strictly defined, processes are fluid and ad-hoc requests increase over time. All of this is natural and expected, but if not tackled properly and on time, can lead to under-productivity.
Zooming into our marketing department, and more specifically the website, let’s have a closer look at the pains we were facing.
The pains
After gaining the grasp of how things work in Hugo, we figured out there was room for improvement in some of our processes.
One of our most time-consuming tasks was blog publishing. It was really difficult for the whole team to collaborate without using a content management system (CMS).
Instead we consolidated everything in code, relying on the developer (me). This is how things looked:
To analyze the diagram above:
- The technical writer would need to communicate with the designer about design needs.
- They would each provide the developer with the content and the designs.
- The developer would need to upload the blog and communicate with the SEO specialist to ask for keywords.
- The SEO specialist would provide the keywords back to the developer and the blog would need to be re-updated.
- Assuming this was a straight-line journey (which wasn’t always the case), the blog would be ready to go live.
This falls under a greater umbrella: any website changes were dependent on the developer.
Another challenge? Websites are built mainly around Javascript, whereas Hugo is applying its own functionality mainly through markdown/yaml files. In most of the cases this is fine, but should you need to combine some logic with markdown code and Javascript, well… let’s just say that this was taking more time than it should.
Gatsby/ Contentful, parts of the JAMstack family
Now static site generators are great, and that’s one of the reasons why JAMstack got increasingly famous over the last couple of years.
But what is JAMstack?
Were we to define JAMstack it would stand for Javascript API and Markdown, and as you may have guessed, Gatsby is also part of the JAMstack family ,although it can be configured to serve dynamic pages as well!
But Gatsby wasn’t the only change we applied. Contentful was also implemented as part of our migration journey. Contentful is a headless Content management system (CMS), that comes with an out-of-the-box configuration with Gatsby (cool stuff!). But what exactly does that mean, and how would it be helpful in our case?
Basically a headless CMS allows content to be provided by non-technical people (e.g. Marketing team) on the UI of the platform. Then through API calls, we serve that content on our website, controlling the look and feel in code.
On the other hand traditional CMS systems (e.g. Wordpress), would be responsible for the front-end too.
Now let’s gain a better understanding of Hugo, Gatsby/Contentful (a Jamstack CMS stack). What are their differences? What challenges should you expect? And what lessons can you learn when migrating your web stack?
Disadvantages
Let’s start by examining the downsides (yes there are downsides too) of migrating the website from Hugo to Gatsby:
- You no longer have all of your website content in one place. If you’re not mindful about what pages/sections of the website you want to store in your CMS, things can easily get out of hand.
For example, if you add parts of the website that you’ll need to frequently update in terms of style, page structure, integrations, you might spend more time trying to catch-up the CMS-code with the new pages than releasing new, high value web experiences. At this point it could have been better just storing those pages in code and making the changes directly there. - Another significant disadvantage would be the development/build times. Hugo claims to be “The world’s fastest framework for building websites”, and for good reason. Their build times are blazingly fast!
- Also breaking down the skillset, Gatsby andContentful have a bigger learning curve to begin with.
For Hugo we need HTML, CSS, JS, Hugo,
whereas for Gatsby and Contentful we’d need HTML, CSS, JS, ReactJS, Gatsby, Contentful and GraphQL basics. This can be overwhelming at the beginning (may the Stackoverflow force be with you).
Advantages
Now for the good stuff.
One of the biggest advantages is, for the Marketing team being able to produce content as a service, when it is efficient to do so. Usually this touches on sections of our website that tend to get repetitive and the Marketing team should have control on e.g. (blogs, SEO fields, etc…)
Touching on our previous example, the marketing/content team can now directly collaborate in Contentful, and our content gets stored there.
Now this looks like a happy developer! All he needs to do is build the website, and the blog will be live.
What’s more, utilizing Contentful’s preview mode, we can preview our blog while only stored in Contentful — without having to deploy or build something.
This solves several other problems too. We now have an elevated platform that marketers can use in parallel.
Let’s have a look at some challenges that this use case solves:
- Ever been in a situation, where you had to make a change that the content writer requested, only to find out that the previous version was better, and then revert that change? ✅
- Ever published a blog, only to find out that you had forgotten to add SEO meta tags e.g. keywords, and then had to update and re-deploy to live? ✅
- Ever needed to build your site (in a dev environment) to see how the blog will look once it’s live? ✅
What’s great in using a headless CMS is that you can be as flexible as you want with the schema, plus the content model can be fully modularized to meet your needs. You also have total control over the front-end design.
- Moving onwards to the more technical side of things, Gatsby comes with all the benefits of React in place — not a small thing, is it :) ?
- It connects with Contentful through GraphQL in a pretty neat way.
Each page has its own GraphQL query, pulling the requested data. When developing locally, a GraphQL server is spun up, allowing us to easily select our desired data through the GraphQL API.
If you’re interested in GraphQL, and how it differentiates from the REST API see: GraphQL vs REST API - Lastly, since Gatsby is based on Javascript, we have a much cleaner architecture in terms of data, APIs, and how we mess around with them. With Hugo, it was proving a bit of a challenge combining Javascript with its templates, variables etc… (creative hacking was needed there :D ).
Challenges
Migrating a website can be challenging. You need to make sure that all the integrations, pages, styles remain in place. Of course some things might break in the process of migrating and some will take more time than expected, but in the end everything should be completely functional. On this node, let’s pin-point the main challenges that we’ve faced when migrating from Hugo to Gatsby and Contentful:
- Updating your HTML files to JSX.
What is JSX? JSX is what we’re using when coding in React and it stands for JavaScript XML. Its syntax is more strict than the one of pure HTML. On the one hand this makes the code readable and clean. On the other hand, transforming all of your HTML files into React JSX and formatting the code to obey those restrictions will take time. - Developing the appropriate Schemas in Contentful.
With great power comes great responsibility. Having total control of what your content model will look like is great, but trying to keep things simple is a challenge: Decide what you actually want to store in your CMS. - Bridging the first setup-gap.
Connecting Contentful with the website on all the relevant sections, taking care of stuff like pagination, SEO, external scripts, can be tricky initially, and most likely will take more time than anticipated. - Migrating blogs.
If every blog was written purely in markdown code, this would have been easier. Contentful comes with an API that can transform your markdown into a rich text editor format. But we’re always tempted to add some HTML on that markdown file, in order to make our blog more beautiful, or add an extra element (a video perhaps?). Being guilty of this myself, as you can guess it took some time to convert HTML to markdown. - Providing a stable timeline
Like in any project, unexpected issues will pop-up. And being in the technical world some bugs might take seconds to fix, while others might take even days. All of this happening while you’ve almost blocked the development on the old stack, in order to prevent doing duplicate work. Yes, this can be tough. - Last but not least, learning the technology.
Ok, we already know HTML, CSS and JS as web developers (can even add React here). But even so, it will be a challenge learning the internals of Gatsby, how it integrates with Contentful, some GraphQL basic queries knowledge and how Contentful works internally. This will improve over time, but in the beginning the progress most likely will be slow due to the learning curve.
Lessons learned
Time to take a deep breath, look back and assess what could have worked better and what mistakes we could have avoided.
No need to migrate the whole website at once.
Ideally you would like to split this into smaller deliverables which will make it easier to provide timelines.
This would also make testing easier as well and lower the pressure of building the new website all at once.
Of course this has the disadvantage of having to handle the routing, urls and hosting on the short term, but will make the transition much more smoother.
An example in our case, would be to split pages of the website that will be using Contentful, pages of the website that include integrations with the CRM (Customer relationship management system), and rest of the pages.
Cleanup but with caution.
Migrating is a great opportunity to clean-up your website. All those useless parts of code that you didn’t need, the many CSS files that can be beautifully restructured, the outdated parts… Just be careful with the pages that you’re excluding!
Not all pages exist to be of use or linked with your website. There can be external systems that point to them, or are used by them.
We actually had to revert to our old website after a couple of hours of going live, because we’d skipped a page from which clients would get their licenses. A big no-no, but luckily resolved quickly.
Take your time to properly structure your Content Model.
If you think that you’re spending too much time when considering the alternative options of your schemas in your content model, you’re probably not. Spending more time now to do things the right way will save you time in the long run.
Don’t constrain yourself on the previous stack architecture.
It might seem easier to blindly follow the structure of your previous stack. In the short term it may be faster.
You have the structure in place, you just need to make minor modifications. However, in the long term you’ll most likely be missing some of the advantages of your new stack.
Each tool has its own strong points and sticking to the old one, you might end up underusing the new. The earlier you structure things properly the better.
Make sure what you’re building takes your team in consideration.
In our case (a small team), trying to create totally self-service pages didn’t work out well.
At the beginning it sounded great. It felt like we were giving the marketing team the flexibility to directly create new pages on the website.
But the page’s needs were changing from multiple sides (new style, new page components/sections, new integrations etc).
So we ended up investing our time to make these adjustments, rather than directly adjusting the code, and storing the pages in Gatsby, which would have been more efficient.
Of course with a bigger team that could support this, things could have worked just fine.
Wrapping up
By no means we’re stating that one tool is better than the other. At the end of the day we want a fast and secure website, that can be modularized based on our needs. On this aspect both tools are great and have a big community supporting them.
Gatsby and Contentful would be more friendly towards front-end developers, with a bigger learning curve and somewhat better data handling.
Hugo would be faster for a developer-heavy team, with a smaller learning curve, but harder to combine data and functionality between Markdown and Javascript.
Nevertheless a website migration may not be an easy task, but it definitely provides valuable lessons. It was our pain points that drove us on the decision of moving from Hugo to Gatsby/Contentful. In doing so we were able to move to a partially self-service web stack that is more performant and flexible, matching our needs.
So pay attention to your pain points and resources, and let those guide you towards the right direction. Try to avoid rushed decisions as they will haunt you later on. Of course no perfect tool exists, and since technology constantly changes we need to make sure we’re adapting to it.
Useful resources:
https://jamstack.org/generators/
https://www.gatsbyjs.com/blog/2017-11-06-migrate-hugo-gatsby/
https://stackshare.io/stackups/gatsbyjs-vs-hugo/
https://www.gatsbyjs.com/
https://gohugo.io/
