How to Build Your First JAMstack Site: A Complete Guide

Are you wondering what all this new hype is over JAMstack? What is a JAMstack site? How do I build one? Where do I deploy it?

If you've asked any of these questions over the last couple of months, this article is for you. We're going to learn what JAMstack is, and how to build our first JAMstack blog.

If you already have an idea what a JAMstack site is, you can skip this section and go directly to:

• JAMstack static site generators
• Where to host your JAMstack site
• Building your first JAMstack site
• Deploying your site

What is JAMstack?

JAMstack is not a framework or a product. It's a way of doing things, and it's not that new. But applying this term to this method of building sites helps increase its popularity, so I'm all for it. JeremyMorgan.com has been a JAMstack site since 2010.

JAMstack is:

• JavaScript
• API
• Markup

But that doesn't tell you much. How do these work together?

The most significant component of JAMstack, in my opinion, is building static websites that aren't so static. To explain that, we need to go back a little bit.

What Websites Were Like Before

In the past, we had two types of websites. They were static and dynamic.

Static Web Sites

A static web site is a site that's only a bunch of text-based HTML files with CSS and images pushed out through a web server.

This is how the web began. Since the webserver is just pushing out HTML files with no processing, they're extremely fast. The downside is they can't be changed. No matter what data changes, the HTML files are the same. You can't dynamically update a page when data changes.

Example: Most of the web pages from the 90s

Dynamic Web Sites

A dynamic web site runs applications in the backend that generate HTML on the fly and delivers it to the browser. This is how we've been building websites for around 20 years now.

A dynamic website is not as fast as static, but it's interactive. HTML is sent to the browser, but the user can interact with it and send messages back to the web server. It then generates new HTML to be sent back.

Example: Wordpress, Drupal, Sitecore and about a million others

JAMstack Web Sites

A JAMstack web site is the best of both worlds. You get the speed of static files being served, but in those static files is JavaScript that communicates with an API.

So if this diagram is confusing, let me explain by going back a bit.

You aren't writing static HTML files, they're being generated for you with a static site generator.

The first part of your workflow is to create and edit Markdown files. If you've never worked with Markdown, here's the basics, and here's a great course on it.

After you are finished, you run the files through a static site generator. It generates all your HTML, CSS, and JavaScript. You then host these on any static file web server (preferably a CDN).

Those files can be served up lightning fast because they're just text. The JavaScript files can then communicate with an API so that you get dynamic data. You can even attach it to a database.

So instead of the Wordpress model, for instance, that's a PHP service connected to a database and generating HTML pages, the HTML is already generated. The JavaScript can then communicate with a database.

It's the best of both worlds. You get the blazing speed of static files with database or other API connectivity.

This is why people are talking about JAMstack sites so much right now.

What Are the Benefits?

Static web site generators and JavaScript communicating with APIs has been around for a while. As I said, JeremyMorgan.com has run this way for 10 years. The most significant differences lie in the tools, workflow, and hosting models.

For instance, right now, my website is built with Hugo. I commit it to GitHub repo, and it's automatically pulled and built on Netlify. Netlify invalidates the cache, so the site is fresh and uses a CDN for speed.

10 years ago, I was generating the site with an Octopress(Jekyll Wrapper) installation on a FreeBSD virtual machine. A far cry from where we are now.

So here are some of the benefits:

• Speed - Serving static assets over a CDN is fast. Really fast. You're serving pre-built assets over a CDN
• Security - There is a smaller "footprint" as most of your site is static assets.
• Workflow - Once setup, the workflow is even easier than Wordpress or similar setups
• Scaling - If you suddenly end up on the front page of Hacker News your site won't die. It will scale up (if you use the right services)

So, if you're sold on the JAMstack idea, let's move on to see what kind of tools you'll need.

JAMstack Static Site Generators

To start with JAMstack, you'll need a static site generator. This is what turns your Markdown files into HTML. There are too many static site generators to list them all, but here are some of the top ones. I've worked with many of these in the past.

• Hugo - I have listed this first because it's my favorite. It's powered by Go, but you don't have to know Go to use it. Its advantage is a single executable and extremely fast generation of pages.

• Gatsby - Another awesome generator. This one is powered by JavaScript. It's biggest advantage is a ton of amazing features and a growing community. (You can take this course on it and get up to speed)

• Jekyll - This one is powered by Ruby. I used this for JeremyMorgan.com for years. It's extremely simple and configurable. Just watch out for those Ruby dependencies.

• Next.js - A JavaScript powered SSG. It supports statically exported React apps, or you can have it server rendered.

• Pelican - This one is powered by Python and it's rock solid. It has a simple CLI and is very configurable.

• Hexo - Another JavaScript powered static generator, this one is growing in popularity. It's very fast and easy to work with.

Whatever static site generator you choose is up to you. It depends on your skill level and comfort. JS developers like Hexo. Python folks like Pelican. React devs like Gatsby. Choose what feels best for you and makes you productive. If you would like to examine more static site generators, check out StaticGen.com.

Which One Did I Choose?

I chose Hugo for my website. It's not just because I'm a Go developer. In fact, I haven't changed any Go code to make it work. However, I spent a long time evaluating solutions and I chose Hugo because:

• It's really fast
• Single executable (less dependencies)
• Very configurable

Here's where I talk about the process of choosing in depth. So now, let's talk about where we can host it.

Where to Host JAMstack Sites

So now you've got a static generator chosen, and you need somewhere to put it. You can host it on any static host. You can create a simple virtual machine online with Nginx and host it there. However, best practices with JAMstack sites are to put it on a service with a CDN.

Here are some great places to host your JAMstack sites

• Netlify - Extremely fast, CDN backed service you can attach to GitHub. Free unless you want analytics or your site is large.
• Vercel - Also very fast and CDN backed, attached to GitHub. Also free until you grow.
• AWS Amplify - A fast, powerful way to deploy static sites (and much more).
• GitHub Pages - A fast and easy way to publish static pages for free.
• Azure Static Web Apps - A new service from Azure for hosting static pages. Fast, powerful, and scalable.

There are many options available, but these are the popular right now.

Which One Did I Choose?

After some intense evaluations, I went with Netlify. I evaluated all the options above, except for Azure, and they were all great. In my speed tests, Netlify consistently performed better from Africa and India, which are critical areas of my reader base, and I want to serve them well.

They were all very close to each other in speed, and they were all easy to connect to GitHub.

So, are you ready to build your first JAMstack site?

Building Your First JAMstack Web Site

For our first site, we'll be using Hugo. You need to install:

• Git
• Go

Both of those links cover Windows, Mac, and Linux. If you're using Pop!_OS (my preferred choice), here's a full tutorial for setting up Hugo.

Install Hugo

The first step is installing Hugo. Here are the full instructions from their site.

It's pretty easy.

Homebrew

brew install hugo

Chocolatey

choco install hugo -confirm

or from source:

mkdir $HOME/src
cd $HOME/src
git clone https://github.com/gohugoio/hugo.git
cd hugo
go install --tags extended

Create a Hugo Site

Now you'll need to create a new Hugo site:

hugo new site hellohugo

Now you're going to need a theme:

You can find a good list of Hugo themes here.

Once you find one you like, copy the link to the repo. I choose "Hyde" for this example:

cd themes
git clone https://github.com/spf13/hyde

You must then add the following to your config.toml file:

theme = "hyde"

Now create a new post:

hugo new helloworld.md

Your post will look like this:

---
title: "Post"
date: 2020-05-30T13:13:42-07:00
draft: false
---

Hello! This is the first blog post!

Add some content, and make sure to change "draft" to false when you're ready to publish.

To test it out:

hugo serve

And you're ready to view your blog on localhost:1313:

All files are generated in /public so when you're ready to publish run:

hugo

And then all the files in /public will be your new site.

So now it's built, let's deploy it.

Deploying Your JAMstack Site

So we're going to be deploying this site to Netlify. First, we need to add it to GitHub.

First, initialize it in the folder you installed Hugo in.

Note: We are not building artifacts and pushing them to Netlify. We are pushing the source code to Netlify, and Netlify will build the artifacts and host them.

git init

Now we need to add in our theme as a submodule. In my case, using Hyde looks like this:

git rm --cached themes/hyde
git submodule add https://github.com/spf13/hyde themes/hyde

Now, head to Github and create a repository.

Now let's add the origin:

git remote add origin https://github.com/JeremyMorgan/HugoTestBlog.git

And pull it:

git pull origin master

Now we'll add in our new changes.

git add .

And commit them.

git commit -m "initial commit"

Now it's ready to push to GitHub:

git push --set-upstream origin master

Now we'll go to Netlify. You can create an account for free if you don't have one.

In Netlify we want to create a new site from git:

Then we'll create a new continuous deployment from GitHub:

Next you need to allow Netlify to install the Netlify app for GitHub, and grant access to the repository you want to publish.

From here, you can select your basic build settings. We have hugo, and public here. You can click on "deploy site" and it will deploy.

Now you can grab your generated URL and visit your new site!

However, depending on the theme you choose, you may have styling that looks like this, nonexistent. That's because the base URL is set to "example.org". We didn't know what the base URL was.

In my case, Netlify created my site at https://awesome-carson-bc7cd2.netlify.app/ so I will just add that into my config.toml:

baseURL = "https://awesome-carson-bc7cd2.netlify.app/"
languageCode = "en-us"
title = "My New Hugo Site"
theme = "hyde"

And I will add it then commit. Now my site looks like this:

If you've been following along: congratulations! You've just deployed a JAMstack site!!.

Now of course, we haven't implemented the API portion into this example, but I'll be covering it in future articles.

Conclusion

I hope this has helped you understand what JAMstack is all about it. In this article we covered

• What JAMstack is
• Why it's awesome
• Static site generators you can use
• JAMstack hosts
• Built our own JAMstack site.

I hope this has been helpful. If you want to become a JAMstack superstar here are some great courses you can take to learn it:

• Writing Content With Markdown
• Build a Better Blog with a Static Site Generator
• GatsbyJS: Getting Started

If you end up building a JAMstack site, share it with me! I'd love to hear feedback and how it's going.