Beginner's Guide to Static Site Generators Part 2

3. Gatsby

Last updated: October 27, 2020

 

Gatsby is the most popular static site generator built on top of React.js, the most popular Javascript framework. Kyle Mathews later founded Gatsby, Inc. with Sam Bhagwat, with a mission to "make website building fun".

 

3-1 Gatsby Story

GatsbyJS was born in 2015 as a simple static site generator and has become the most popular solution in the market over the past 5 years. Thanks to Gatsby, Jamstack has grown to what it is today.

 

In 2019, Gatsby, Inc. secured $15 million in funding in Series A and built its first commercial product, Gatsby Cloud, a CI platform specialized in fast incremental builds. We will talk about this later. First, let's explain the overview of SSG.

 

3-2 Content Mesh

The most common issue with Gatsby is data retrieval. Gatsby creates a GraphQL API internally, which acts as a middleware between the content source and frontend templates.

 

 

Gatsby can connect to any popular headless CMS. With a wide range of Gatsby source plugins, it's easy to connect. You can mesh sources with just one GraphQL query, creating one big graph.

 

To enjoy the Mesh Concept, you need to learn GraphQL and Gatsby API. It may be difficult to achieve with a simple static website. Working with GraphQL can be painful and may result in errors. Debugging can be challenging. Some people may enjoy it, while others may not.

 

In my opinion, GraphQL API is suitable for unifying and standardizing the way products are created in agencies like ours. Regardless of which CMS is chosen, the methods for generating pages and retrieving data are the same.

 

For example, let's take a look at how to retrieve products from Shopify and content from Contentful.

 

  import React from 'react'
   import { graphql } from 'gatsby'

  

  const HomePage = ({ data }) => {
     return (
       <div>
         All products:
         {data.allContentfulProducts.edges.map(({ node }) => (
           <div key={node.id}>
             <h2>{node.title}</h2>
           </div>
         ))}
       </div>
     )
   }

  

  export const query = graphql`
     query HomePageQuery {
       allContentfulProducts(filter: { node_locale: { eq: "en-US" } }) {
         edges {
           node {
             id
             slug
             title
           }
         }
       }
       allShopifyProduct {
         edges {
           node {
             id
             title
             productType
             vendor
             variants {
               id
               title
               price
             }
           }
         }
       }
     }
   `

  

  export default HomePage
  

 

You can retrieve data from anywhere. Headless CMS, local file system, external GraphQL or REST API, Google Spreadsheet, Airtable, etc. You can create your own source plugins to perform custom integration with the backend.

 

GraphQL queries are only executed during build time. If you make any changes in the CMS, you will need to rebuild the project. Like other React apps, you can also fetch data on the client side. For example, you can use SWR or even simple fetching, but it will not be pre-rendered.

 

3-3 File Configuration

Here is an example of file structure.

 

  ├── gatsby-browser.js
   ├── gatsby-config.js
   ├── gatsby-node.js
   ├── gatsby-ssr.js
   ├── package-lock.json
   ├── package.json
   ├── src
   │   ├── html.js
   │   └── pages
   │       ├── 404.js
   │       ├── about.js
   │       ├── blog.js
   │       ├── contact.js
   │       └── index.js
   └── static
       └── logo.png

  

 

The first four files are accessing the Gatsby API. This means that Gatsby can change what is happening under the hood. You can add plugins, generate pages from the API, adjust SSR, and manage what is happening during the initial render in the browser. The official documentation covers all the features of the API.

 

3-4 Ecosystem

The Gatsby developer community has created thousands of themes, plugins, and starters over the years. Gatsby has the largest ecosystem among Jamstack. When we last checked the plugin library, there were over 2400 packages available for immediate installation.

 

 

Some people may like plugins, while others may not. However, there is a good chance that someone else is facing the same problem as you and has published a solution for it.

 

The most popular plugins are gatsby-plugin-react-helmet, gatsby-plugin-sharp, and gatsby-image. There are many plugins that improve page performance, such as gatsby-plugin-preact. We also talked about Gatsby plugins that were created to solve performance issues in the past.

 

A large ecosystem improves developer experience. In other words, there are already solutions for tedious tasks such as generating site maps and adding content security policies.

 

How do I get started with 3-5?

To globally install Gatsby on your computer, run the command.

 

  npm install -g gatsby-cli
  

 

To get started with Gatsby, the quickest way is to use one of the many starters that are available.

 

To create a project from a starter, select one from the gallery, copy its Github URL, and run it.

 

  gatsby new my-website https://github.com/gatsbyjs/gatsby-starter-default
  

 

To launch the Gatsby project locally, execute the following:

 

  cd gatsby-site && gatsby develop
  

 

Your development environment is available at http://localhost:8000.

 

3-6 Gatsby Deployment

Gatsby can be deployed anywhere. The only command you need to run is this.

 

  gatsby build
  

 

All publicly available static files are stored in the Public folder.

 

If your project contains a small amount of GraphQL queries and images, everything will work fine. However, with large image sets such as hundreds of images, there is a tendency for the build to take a long time and for timeout errors to occur in CI/CD tools.

 

If you want to improve your build time, the easiest solution is to switch to Gatsby Cloud. It supports fast Incremental Builds and also has enhanced cache management.

 

 

The construction part will be handled by Gatsby Cloud, but in order to deliver the website to users, it needs to be hosted somewhere. With a general hosting provider, it can easily be connected to the project. Gatsby integrates with Netlify, Vercel, Fastly, Google Storage, Azure, Firebase, and AWS S3. Please choose the one that best matches your existing infrastructure.

 

3-7 Conclusion

Gatsby.js is suitable for cases where you want to manage everything using one internal API, as it uses many data sources. Gatsby, like Next, is based on React. It allows you to easily create interactive components, but it comes with the cost of JS. Client-side routing optimizes perceived performance, especially on high-end devices.

 

Due to the need to load a large amount of JavaScript, it cannot be said that it is the most lightweight static site generator. It may be difficult to achieve a perfect score on Lighthouse, but sometimes that is not important. You can create a very fast and user-friendly website.

 

4. Eleventy

Last Updated: October 26, 2020

 

Since Zach Leatherman created Eleventy in 2018, it has gained more and more followers, especially from those who are tired of static site generators that heavily rely on JavaScript. Eleventy is zero-config by default and can adapt to any project structure. It supports up to 11 different template languages without being tied to a specific framework. Eleventy is simpler. Eleventy adapts to you.

 

Many recent static site generators use some kind of JavaScript framework, such as React, Vue, Angular, etc. In Eleventy, static pages are generated using JavaScript. No client-side framework is necessary.

 

This does not mean that you should not use any framework. It is an option and it is up to you whether to use it or not.

 

4-1 Progressive Enhancement

In JS-based static generation tools like Gatsby and Next.js, TTI (Time To Interactive) is often a problem. The browser needs to download, parse, and execute a large chunk of JS in order to hydrate the application. This incurs a cost, ultimately resulting in a delayed TTI and causing a delay before the user can interact.

 

In general websites, many components require hydration even though they are not very interactive. The React team is working on partial hydration to solve this problem, but the completion date is not yet clear.

 

At Eleventy, we first focus on providing the necessary content and then gradually add dynamic features. In some cases, creating animations and sliders can be done with just vanilla JavaScript and pure CSS.

 

4-2 Need for Speed

Excellent performance is an essential element for any modern website. Developers using Eleventy love this speed. And speed loves Eleventy. Thanks to its low JavaScript overhead, Eleventy websites achieve great results on Lighthouse. Let's take a look at the leaderboard created by Zach, the creator of Eleventy.

 

 

The leaderboard is updated every two weeks and displays a list of projects that have achieved the best scores. Most of them are very simple personal websites. So please take this with a grain of salt. In other words, this doesn't necessarily mean that Eleventy is truly the fastest SSG on the market. Many of these pages would likely achieve similar scores with other static site generators.

 

4-3 File Configuration

It doesn't have to be anything complicated.

 

  └── index.md
  

 

When you run the npx 11ty/eleventy command, it will look like this:

 

  ├── _site
   │   └── index.html
   └── index.md
  

 

_site is ready to expand the output folder.

 

Let's create a simple blog. The following example is based on the official eleventy-base-blog starter.

 

  ├── .eleventy.js
   ├── .eleventyignore
   ├── _data
   │   └── metadata.json
   ├── _includes
   │   ├── components
   │   │   ├── footer.njk
   │   │   ├── head.njk
   │   │   └── header.njk
   │   └── layouts
   │       ├── base.njk
   │       └── post.njk
   ├── index.njk
   └── posts
       ├── hello-world.md
       └── posts.json
  

 

4-4 Data Source

Eleventy retrieves data from multiple sources. The most straightforward way is through front matter in page and template files.

 

  ---
   title: Post title
   author: John Doe
   ---

  

  <h1>{title}</h1>
   <span>by {author}</span>

  

  ...
  

 

Retrieve Data from Headless CMS 4-5

In real projects, some kind of CMS is necessary, but not all content teams are satisfied with editing md files and pushing them to git.

 

To retrieve data from the API, you need to create a JS file in the _data folder. This will make the data available globally.

 

If you want to retrieve data and use it within a specific range, you need to create a *.11tydata.js file in the template folder or directory folder.

 

You need to create a file in the directory folder.

 

  module.exports = async function () {
     let response = await fetch(`https://api.domain/posts`)
     let data = await response.json()

  

    return data
   }
  

 

4-6 Ecosystem

Eleventy has a list of starters mainly created by the community. What's cool is that you can see the Lighthouse scores for each starting point, which are updated daily.

 

 

Eleventy has few ready-to-use plugins, but there are several plugins that add features such as RSS, PWA, Tailwind, and Table of Contents.

 

How do I get started with 4-7?

To install Eleventy globally, run the command.

 

  npm install -g @11ty/eleventy
  

 

Next, create a folder and index.md file.

 

  mkdir my-11ty-website && echo '# Hello world' > index.md
  

 

To launch the Eleventy project locally, execute the following:

 

  eleventy --serve
  

 

Open http://localhost:8080 and display the website.

 

4-8 Conclusion

Eleventy may be the best choice to start your adventure in the world of Jamstack. It is flexible and does not require learning specific JS frameworks like React or Vue.

 

5. Hugo

Last Updated: October 26, 2020

 

Written in Go to achieve the fastest build time in the SSG market. Created by Steve Francia and Bjørn Erik Pedersen, first released on July 5, 2013. Currently maintained by Bjørn. The popularity of Hugo lies in its speed and flexibility in creating large-scale websites.

 

Just like Eleventy, Hugo also recommends gradual enhancement rather than full JS hydration. It has nothing to do with JavaScript frameworks.

 

5-1 Data Acquisition

Hugo only supports local flat files like markdown. If you want to edit content with a clean user interface, please use a Git-based CMS. Popular options include NetlifyCMS and Forestine.

 

To retrieve data from external APIs such as headless CMS, use the getJSON function.

 

  <div>
     {{ $posts := getJSON "https://API.DOMAIN/posts" }} {{ range first 10 $posts }}
     <article>
       <h2>{{ .title }}</h2>
       <div>{{ .content }}</div>
     </article>
     {{ end }}
   </div>
  

 

5-2 File Configuration

  ├── archetypes
   │   └── default.md
   ├── config.toml
   ├── content
   ├── data
   ├── layouts
   ├── static
   └── themes
  

 

There are several high-level concepts in Hugo, such as archetypes. Think of them as places where you can define fields for sections of your website, like templates and content schemas.
If you want to learn more about specific folders, please refer to the official documentation.

 

5-3 Ecosystem

Thanks to its high performance and simplicity, Hugo has gained many fans over the years. If any issues arise, you can quickly get answers from the official public forum.

 

 

Hugo has a large collection of themes. These are not official projects. Most of them are created by Hugo developers around the world. They are provided under the MIT license and can be used and modified freely. Various categories are available, such as simple blogs, documents, landing pages, resumes, etc.

 

How do I get started with 5-4?

Installation methods may vary depending on your OS, so please refer to the installation document. You can use Hugo even if you do not have Go installed.

 

Once you have installed Hugo, let's try running it.

 

  hugo new site my-hugo-website
  

 

You can now select a theme or create a new one.

 

  hugo new theme my-theme
  

 

To add content, execute.

 

  hugo new posts/hello-world.md
  

 

To start the development server, execute the following:

 

  hugo server -D
  

 

Your development environment is located at http://localhost:1313/

 

5-5 Conclusion

For those who prefer modern JS frameworks such as React, Vue, and Svelte, Hugo may feel a bit outdated. However, Hugo's age is also its strength. It has been proven in many big projects of famous companies, so I am confident that it will not disappear tomorrow.