Step-by-Step Guide to Deploy Hugo on Vercel

Sassi Med — Sun, 06 Oct 2024 16:18:38 +0000

This guide will walk you through deploying a Hugo website to Vercel.
I will ensure you avoid at least one common mistake.

1. Create Your Hugo Site Locally

Assuming Hugo is already installed:

hugo new site <my-hugo-site>

2. Push Your Hugo Site to GitHub

Then set up a git repository for the site.

git init

Add commit and push your project files:

git add . git commit git push -u origin master

3.Add a theme for your Hugo site.

For instance, you can use a Nno jQuery, no Bootstrap super fast theme like hugo-blog-awesome:

As a github module:
git submodule add https://github.com/hugo-sid/hugo-blog-awesome.git

Or a Hugo module
hugo mod get github.com/hugo-sid/hugo-blog-awesome

4. Add vercel configuration (vercel.json)

In root dir add vercel.json where we gonna define hugo version Go version and the buildCommand, after defining hugo as Framework Preset in vercel those config will be auto detected.

vercel.json

{
  "build": {
    "env": {
      "HUGO_VERSION": "0.135.0",
      "GO_VERSION": "1.19.5"
    }
  },
 "buildCommand": "hugo --gc --minify"
}

- use hugo env to show versions of Go and Hugo you're using

Then push update to Github:
git add . git commit -m "vercel deploy" git push -u origin master

5 . Deploy Your Site on Vercel

During the import process, ensure that the project is connected correctly to your Hugo repository.

Vercel detect env and command build:

Or you ou can set it manually in Vercel environment variables here

Deployement logs:

After a successful build 🎉🎉, Vercel will provide a preview link where you can view your live Hugo website. You can also configure a custom domain through Vercel's settings for your project.

6. Add a Domain

If you have a domain name you can add the domain name to the vercel in domains section of the project settings. Then add a CNAME to your domain provider to point to the vercel domain.

🛠️ Fix Common Deployment Issues

The main problem is that hugo support is not that good even if vercel already updated their Node image to have Hugo and with default settings, I met with the error of hugo layout not found and my deployment leads to an XML page.
This is because the env parameter Hugo and Go versions need to be defined with in the json file vercel.json

Setting up a personal site with Hugo and Vercel is really easy, despite some minor problems. I hope this post can help you to set up your own site. For more details about the changes I made to the site, see the commit history of my site.

Some Sources:
https://vercel.com/guides/deploying-hugo-with-vercel
https://vercel.com/docs/projects/project-configuration
https://blog.gusibi.site/article/Best-Practices-for-Deploying-Hugo-on-Vercel

DEV Community: Sassi Med