How to publish a Gatsby app to Github pages

Using Github Pages with Gatsby

GitHub Pages is a service offered by GitHub, which allows you to host websites straight from the repository. With a few configurations a Gatsby site can be hosted on GitHub Pages.

There are several ways to publish to Github Pages:

• to a path like username.github.io/reponame/ or /build
• to a subdomain based on your username/organization name username.github.io or orgname.github.io
• to the root subdomain at `username.github.io, and then configured to use a custom domain with CNAME.

Configure source branch

You have to select which branch will be deployed from your repository in Github. Navigate to your site’s repository and update the branch in the Github Pages Section under settings. Select main for publishing to the root subdomain or gh-pages for publishing to a path.

Install gh-pages package

The easiest way to publish a Gatsby app to Github pages is with the package gh-pages, see npm gh-pages.


npm install gh-pages --save-dev


Custom deploy script

A custom script in your package.json makes it easier to build your site and move the contents of the built files to the proper branch for GitHub Pages. This also helps to automate that process in the future in a CI/CD pipeline.

Deploying to a path on GitHub Pages

If you choose to deploy at a path like username.github.io/reponame/, you have to use the ---prefix-paths flag, because the website will end up in a folder username.github.io/reponame/. In this case the path has to be prefixed with /reponame in the gatsby-config.js.

Add path prefix in gatsby-config.js.


module.exports = {
pathPrefix: '/reponame',
};


Then add a deploy script to package.json:


{
"scripts": {
"deploy": "gatsby build --prefix-paths && gh-pages -d public"
}
}


When you run npm run deploy all contents of the public folder will be moved to your repository’s gh-pages branch.

Deploying to a GitHub Pages subdomain at github.io

If you choose to deploy to a repository like username.github.io, you don’t have to prefix the path and your website needs to be pushed to the main branch. GitHub Pages forces deployment of user/organization pages to the main branch. So if you use main for development you need to do one of these:

• Change the default branch from main to something else, and use main as a site deployment directory only. Create new branch source with the command git checkout -b source main and, change the default branch from main to source.
• Have a separate repository for your source code

Then add a deploy script to package.json:


{
"scripts": {
"deploy": "gatsby build && gh-pages -d public -b main"
}
}


After running npm run deploy you should see your website at username.github.io (it could take a few minutes).

Deploying to the root subdomain and using a custom domain

If you use a custom domain, prefixing the path is not required. Path prefixing is only necessary when the site is not at the root of the domain.

Add a file named CNAME to the static directory.


WWW.DOMAINNAME.COM


Then add a deploy script to package.json:


{
"scripts": {
"deploy": "gatsby build --prefix-paths && gh-pages -d public"
}
}


TL;DR

• Host your Gatsby website for free with Github pages.
• Use gh-pages package to make deploying simple.
• Deploy your website to a path, a subdomain or a custom domain.

Thanks for reading and if you have any questions , use the comment function or send me a message @mariokandut.

If you want to know more about Gatsby, have a look at these Gatsby Tutorials.

References (and Big thanks):

Gatsby, Github Pages

Comments

[Domhnall O Hanlon]

Thanks for the resource @mariokandut - have you published your own site with Gatsby?
How does it compare to other static site generators?

[Mario]

@domhnallohanlon you are very welcome. I hope I was able to create some value for the community. Yes, mariokandut.com is published with Gatsby and hosted on github via gh-pages. There are some github actions to automate the deployment, as well.
For comparing, Next.js would be a good alternative if you are planning to build some APIs. I worked with Hugo, Jekyll and kirby (getkirby.com) a lot in the past. Kirby is a file-based CMS, but PHP. Hugo and Jekyll are ok, but the entire development process is not as smooth as with Gatsby. Hugo and Jekyll are imo very suitable for documentation or just plain text websites.

[Mario]

btw. please add https to your website, it results in a warning in Chrome.