Rapid Wowchemy Development With Netlify

Sep 29, 2022

I have been using Wowchemy (Academic Hugo) for a couple years now - to be exact, since 2019. It has been such a pleasure to see how both Hugo and Academic have evolved for the past couple of years. They both have become great tools to use and have been adopted by so many others.

One thing that I remain adamant about however, is continuing to learn the easiest and most efficient way on maintaining and upgrading my personal website.

Why?

It’s because my main expertise is not on building websites, and I usually like to reserve my personal time for other projects. Hence - today’s topic! How do we leverage some of the newer tools provided by Hugo to minimize the development and testing process for our Wowchemy website?

I tend to break rapid development for Wowchemy into two parts: development and integration/deployment phase.


Development Phase

The development phase has a very simple requirement: fast rendering for real-time changes. This is done easily using Hugo even from 2019’s standards. Hugo has a CLI tool that allows you to compile your website and serve a development version in your local machine with your new changes.

The steps are as follows:

  1. Download the Hugo CLI tool. You can do this on Windows by using a third-party package manager like Scoop or Chocolatey.

  2. Run the hugo server command in the terminal from the root directory of your website. This will bring up the website on your local machine.

Scoop and Chocolatey for Windows is very similar to Homebrew for Macs.

When you run hugo server successfully, you should be able to see a printed message on your terminal. One of the lines should say something similar to:

Web server is available at http://localhost:1313/ (bind address 127.0.0.1)

You can access the local version of your hosted website at the http link mentioned in this message.

Once you’ve finished the previous two steps, you’re pretty much good to go. The local server will track all changes to the assets, layouts, content, data, and static folders of your local website directory. Newer Hugo versions will also track changes to the internal configuration files under config/_default and the go.mod file.

I recommend using the hugo server command when you’re looking for a easy way to test UX/UI-related changes. The server will refresh with your changes whenever you hit the save command.


Integration and Deployment Phase

This phase is where things get a little tricky. Let me explain.

In an ideal situation, the changes that you see on your development environment should match exactly to what you see when you deploy the same changes to your “production” server. This may not be the case though!

Why?

The answer usually has something to do with the fact that your production server is not the same as your local server. For instance, I complete all of my local testing/development on my laptop where I’m able to run hugo server and see the website hosted on my own laptop. My “production” server; however, is not hosted from my laptop (AKA the site you are reading from right now)!

I use a third-party service called Netlify to deploy my static website so readers like you can see it. This implies several things:

  1. Whatever build tools my website uses must be available on Netlify
  2. Whatever settings my website uses must be available to Netlify

Luckily Netlify solves these issues relatively easily. Each website deployed via Netlify is able to contain a configuration file called netlify.toml which instructs the main versions of tools netlify should be using.

For example, my current settings look like this:

[build]
  command = "hugo --minify -b $URL"
  publish = "public"

[build.environment]
  HUGO_VERSION = "0.101.0"
  HUGO_ENABLEGITINFO = "true"

[context.production.environment]
  HUGO_ENV = "production"

[context.deploy-preview]
  command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL"

[context.branch-deploy]
  command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"

[[plugins]]
  package = "netlify-plugin-hugo-cache-resources"
  [plugins.inputs]
    debug = true

Notice that you’re able to see the version of Hugo (the static site generator that powers Wowchemy) that is compatible with my website.

Now, does this mean that since all of your settings are duplicated between your local and production setup that you won’t have any differences?

Unfortunately the answer to that is still a no. It turns out that merely having the same settings between different machines is not enough.

Take Chrome and Firefox as an example. Both browsers are commonly used browsers by many people around the world, but you’ll sometimes notice that a feature supported by one browser is not always supported by the other. As a result, some sites may look different on separate browsers.

A Simple Netlify Trouble

I have been using the same Wowchemy/Netlify setup that I originally made my first deployment with back in 2019. Or at least I had been until recently. So what changed?

A couple months ago, I decided to update my version of Wowchemy. I usually do this every few months since the website builder is constantly releasing new features (for instance, check out my new cool Post format). I also tend to pick and choose new features that may not be available to my version of Wowchemy had I decided not to fully upgrade to a newer version. You can do this by adding the Wowchemy base code and the corresponding SCSS blocks within your Wowchemy “customization” directories.

One day though, this setup that I’ve been doing for the past couple of years broke. No matter how hard I tried finding the problem, Netlify just wouldn’t deploy my new changes despite me being able to see the changes on my local server!

Most Wowchemy users who choose to deploy their site with Netlify are told to use the Github release auto-deployment system.

What this essentially means is that whenever you git push your code into your remote Github repository, Netlify will automatically start a new build and deploy that as your “production” version.

After a couple hours of trying, I decided to call it quits and looked for another solution.


The Hero (We) Needed - Netlify CLI

I’ve always been a sort of a CLI fan after I learned how to use it properly. In a way it gives you more control, so when I saw that Netlify had just released a Netlify CLI, I immediately started looking into it.

And voila, I saw just exactly what I needed in order to fix my Netlify bug!

Netlify’s command line interface (CLI) lets you configure continuous deployment straight from the command line. You can use Netlify CLI to run a local development server that you can share with others, run a local build and plugins, and deploy your site.

I tried manually building my website using the hugo command. Then I tried deploying a draft deployment using netlify deploy.

To my surprise, it worked! Or maybe it shouldn’t have been too much a surprise since deploying via the CLI will grab the local compiled files from your website’s public folder and upload it for deployment to Netlify’s servers.

But I did certainly feel great after the bug plaguing me for hours had finally been vainquished.


Conclusion

In this post, I talk about some of the methodologies I use for ‘rapid’ Wowchemy development - mainly that generally it’s better to have distinct phases for development (responsive) and integration/deployment testing.

I also talked about the possibility that the changes seen in development do not match the changes seen in production. In this case, don’t panic! There may be solutions to get around this. At least for Wowchemy + Netlify, it’s possible to manually build your local website and perform a test deploy with the new Netlify CLI.

An important reason why the Netlify CLI command will replicate the exact view you see in production is due to the fact that static site generators are the main tool that will format your general code into a proper HTML site with styling.

Netlify, in its CI setting, will use the hugo build command provided in netlify.toml to build your code files in Github. It will then serve the built files (usually in the public directory) for external users to see.

In the CLI case, you have to build the website yourself on your local machine. Then you run the netlify deploy command to view how it’d look like in a prod-like environment. The netlify deploy command is the moment where the local files are transferred to Netlify’s servers.

Yiping Su
Yiping Su
Software Engineer

I am interested in data, software engineering, and the application of computer science concepts in real-world scenarios.

Related