— May 23, 2022 · 7 min read

Migrating from Hexo to Gatsby JS static site generator was a right choice

1. Why should you choose Gatsby over other static site generators?

This website had been built using Hexo before. I was able to add various functions to my website: Make it multilingual, add social media interactions, show related and popular posts... However, as the site grows, new function developments become harder. I had struggled with these problems when I tried to enhance my website:

Manipulating data relies heavily on Hexo's site-scope variables and Hexo only exposes a handful of them. To change the data of these variables, we have to modify the implementation when Hexo creates these variables during build time, which is difficult since it needs an understanding of nodejs and Hexo core.
Hexo's page creation process is opaque. We are not in total control of which pages are created and located in what permalinks, besides being able to tweak some of page creation options in config.yml.

Those two above limit the freedom of how you dictate your site organization and hinders your site capabilities. Developing with vanilla JS and having to depend heavily on plugins are also not a pleasant experience. Therefore I decided to look for a platform change and after researches, I picked up Gatsby.

So why Gatsby? Gatsby hooked me up with these features I had been looking for.

2. Pros when choosing Gatsby

I'm in total control of how my site's pages are created. To build which template at which link, or building multiple page versions for each language for a multilingual website is no longer a hassle. I can fully do it without the intervention of 3rd plugins.
By utilizing GraphQL I can query for exactly which piece of data I need at a particular place. No need to memorize the structure of exposed environment and site-scope variables.
You don’t have to familiarize yourself with generators’ defined templates. Jekyll, Hexo, Hugo, Pelican… each has its own page template with predefined syntaxes that you have to remember and look up the documentation when creating pages and interfaces. Gatsby doesn’t employ templates, just pure JS files. On top of that, Gatsby uses ReactJS, which is an exceptionally strong front-end library and Webpack which is gradually becoming the norm of front-end development environment. Using ReactJS means you can tap into the gigantic plugin ecosystem which will solve most of website common use cases for you. Creating each page is simple as creating a new JS file, throw some JS and/or JSX code into it, and the webpage is done, just like when you make a normal create-react-app.

The technologies packed with Gatsby are really productivity boosters, I was able to build a full-fledged static website blog from a vanilla Gatsby starter project. With Hexo I had spent a month or so on developing my blog from scratch to production-ready state, with Gatsby I only needed a week. That's an insight I can offer to prove that how game-changing technologies maybe.

3. Gatsby's shortcomings

If you read the pros of Gatsby above and you are considering adopting Gatsby for your next project, you should consider its caveats too and prepare for workarounds.

Gatsby's build time is noticeably long compared to Hexo, Hugo or other generators that are famous for their build speed. My blog contains near 30 markdown files, 78 pages to be generated and Gatsby takes me around 50 seconds to build. With Hexo the build time is 10 seconds. The disparity will become much larger if your website contains hundreds of webpages.
GraphQL in Gatsby has its limitations. Using StaticQuery which is available at component level won't allow passing query variables dynamically or as string interpolation. The only workaround that the community has discovered is to query all pages and filter the ones you need, which undeniably affects build performance. Passing variables dynamically is only available at page level, where variables' values are decided at page creation times.

However, I do think that the pros outweigh the cons. Gatsby is being adopted by more and more people and big companies, which means its shortcomings are fully recognized and there will be workarounds, patches released to the community that you can take advantage of.

4. A brief guide for Gatsby quick start

So did you decide to choose Gatsby? If yes then let's head to the quickstart I write below. I will point out the basics of Gatsby so you can quickly tweak it and get your site up and running early. For the implementation details, best practices and common use cases design patterns, please refer to the official Gatsby documentation. They are carefully and kindly written that anyone should comprehend easily.

gatsby-node.js

This is the place where you get to define which page is available at which link. You use the function below to define the page layout and the permalink of the page.

// Exampple of createPage function which is one of the few APIs that Gatsby exposes
createPage({
	path: `/en/technologies/migrating-from-hexo-to-gatsby-js-static-site-generator-a-right-choice/`,
	component: path.resolve("./src/templates/blog-post.js"),
	context: { language: "en" },
});

gatsby-config.js

If you use some Gatsby plugins, this is where you define them with their options. For all the options of each plugin please refer to its homepage. Some vital plugins for blogging that should be looked at are gatsby-source-filesystem (for sourcing data from local files), gatsby-transformer-remark (for adding your markdown file contents to graphQL node to query).

src/pages

A file inside this folder will be rendered available at the link address that is the same as its relative path. For example, if you put a file named contact-us.js inside folders that structured as src/pages/about/ then you can access it at the address https://<yoursite.com>/about/contact-us. This is useful if some of your pages don't need to be programmatically created in gatsby-node.js.

html.js

This file defines the html template that every Gatsby page uses. This file is not available when the project is first created. You need to type this command to make it available after executing gatsby develop at least once.

cp .cache/default-html.js src/html.js

static

Any files in this folder will be copied to the root of the production static site folder. Generally, favicon, CNAME file, robots.txt, sitemap.xml, any files that need to be at root folder like verification html, site setting files... should be put in this folder.

You only need these basics to start building a fully functioning website. With these, you can define permalinks, layouts and get your website running on the Internet. The official Gatsby document provides a very thorough tutorial that will guide you through other aspects of Gatsby, like deploying, theming, data manipulating, much more to stretch your website function beyond displaying static pages, and it is really easy to understand.

5. Conclusion

After struggling with Hexo's caveats for years, deciding to migrate my site implementation to Gatsby was the right choice. Gatsby has the power of latest technologies: React, graphQL and Webpack, while it also provides flexibility to customize your webpage layouts, contents and URL without memorizing environment variables and getting used to defined templates. Currently, it is the most advanced static site generator with the fewest flaws. With all these benefits, Gatsby will certainly see a rising adoption rate in the next years. You can't be wrong when choosing Gatsby!