Rapid Wowchemy Development With Netlify

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.

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!

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.