Choosing the right static site generator

All this buzz about generating static files…

When researching different React frameworks for a new project we are barraged with an array of features that both Gatsby.js and Next.js tout to have, such as improved SEO, server-side rendering, and superior performance. However, to find out how these frameworks work and how they differ takes a little more digging beneath the surface. Let’s take a little trip back in time so that we can better understand how they fit in the greater scheme of things.

What is HTML anyway?

The year is 1989 and a rather gifted computer scientist by the name of Tim Berners Lee was coming up with a system for the increasingly complicated task of computers communicating with one another. At this point, the precursor to the internet was nothing more than a few machines spread out across different university campuses in the USA sharing data. It was becoming a complicated task and Lee’s solution was a way of mitigating this complexity and it turned out to become one of the cornerstone concepts of the Internet as we know it today.

Essentially Lee borrowed a concept from a fellow colleague at CERN Ted Nelson. This was the concept of the hypertext and Berners Lee applied it to a protocol he was creating that would become known as HTTP and subsequently the WorldWideWeb. Now there are dissertations written on this topic and I am by no means qualified to get into the details, but at its core HTTP is a series of links that point to different resources, and since it’s a protocol it needs to operate with certain parameters. One such parameter is the relationship between a server (the system that serves the information) and the client (the system that receives it).


One aspect of the new information management system that Berners Lee had created was a language known as HyperText Markup Language (HTML). So this might be common knowledge for most of us because HTML is still widely used today and is still the first file a browser will begin compiling when it gets a website’s data back from a server.

A lot has changed since 1989 and we need to take a lot more into consideration, but this underlining principle remains the same, the client asks the server for some information to build the site and will begin with the HTML document. Before we start talking about parsing this data let’s quickly look at the other crucial steps that must happen nowadays.

To start with we need to verify our IP address and in order to do this, we make a request to the DNS server and verify our own address as well as get the IP of the address we are requesting. Also, we don’t actually use the original HTTP these days and for scalability and security reasons HTTP/1.1, HTTP/2, and SSL/TLS are all much more widely used because of the aforementioned issues.

The critical rendering path

Let’s not forget these are computers we’re dealing with so the browser isn’t actually going to read the HTML itself, but rather it consumes the HTML as bytes of data and then converts that data into characters, which are further processed into tokens. So your browser sees HTML and it will trigger this chain reaction. HTML — bytes — characters — tokens. The browser then takes the tokens and creates a tree-like data structure that we refer to as the document object model, DOM.

So the browser is busy away constructing the DOM from top to bottom and it comes across a style tag. Well, what does it do? Yep, you guessed it… It converts the CSS into data. Then characters. Then tokens, and begins creating another object model, this time the CSS Object Model or CSSOM. This new CSSOM can actually be constructed concurrently as the DOM is being put together. In fact, it’s critical that these are the first things that the browser starts creating. This is one of the reasons we’ll often see the styles included at the top of our HTML file, the other being, that we can’t start parsing our JS until the CSSOM has completed, so let’s talk about that a little now.

Performance and the browser

When the HTML parser finds a <script> tag, it pauses the parsing of the HTML document and has to load, parse, and execute the JavaScript code. This is because JavaScript might be used to change the shape of the document model. Yes, that’s right the browser has to stop processing the HTML and the construction of the DOM in order to interpret the JS. We will often leave our JS code at the bottom of the HTML for this reason so that you can allow the DOM to be created first before processing it. So the browser encountering a script tag will stop it in its tracks. By default, the DOM will stop being compiled if it encounters a script, but this is not the case for the CSSOM, which will actually take precedence over the JS. So that pretty much rounds out the default order of priorities when compiling our code.

How can we be more deliberate with how we want our code to run?

So I still want to move onto server-side rendering, but a quick note on performance and some important keywords to keep in mind. We can use the async and defer keywords on a script tag to instruct the browser to run our code asynchronously and continue parsing the document when they encounter a script tag. With async, the file gets downloaded asynchronously and then executed as soon as it’s downloaded. With defer, the file gets downloaded asynchronously but executed only when the document parsing is completed. With defer, scripts will execute in the same order as they are called.

How Next and Gatsby work

So what’s the difference here? If you compare them by the questions they’re answering then essentially they’re solving the same problem, but they’re doing it in very different ways. With Gatsby.js, we’re going to physically create our static assets during the build phase, but by contrast, Next.js performs automatic server-side rendering so it renders your assets on the server and then sends them to the client. Applying our history lesson here. What exactly happens when you type a URL into the browser when using these frameworks? With Gatsby.js and Next.js you get an HTML file, but the mechanics differ behind the scenes. However, it’s important to be aware of how this will be parsed. In Next.js, when you request something, it goes to Node.js. Node.js pre-renders all the content on the server, and it serves it right down to you as if your browser had rendered itself. They are both fantastic and have their own individual pros and cons depending on your situation.


So much is done for us these days when we spin up a new react app, which is fine because it lets us focus our attention on actually building things, but how the browser works and renders your files is a crucial aspect to grasp in order to debug your applications and to improve performance. As always, the browser dev tools are your friend and are constantly rolling out new and improved features so I’d encourage you to keep up to date with those developments and don’t forget to run reports on your sites to catch any underlining issues.

The author of this tutorial is Kahil Nayton, a web developer at Kworq, a creative digital agency based out of NYC.

Full stack developer based out of Brooklyn, NYC.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store