Deploying Gatsby to GitHub Pages
Tags: github, gatsby
Published: 2020-09-06 00:48:07

Sometimes you just want a simple hosting solution. For Gatsby projects I have been using Gatsby Cloud for builds and pushing to Netlify for hosting. It works well. However, I recently built a couple personal projects with Gatsby that don't need a cloud pipeline and decided to use GitHub pages to host. What follows is everything I had to do to get that working with a project directory as well as with a personal subdomain.

## Setting up GitHub to Receive Your Built Files

* First, create a branch in your project named `gh-pages` and push it to your repo.

* Next, go to your repo on GitHub and click on "Settings", then "Options" and scroll down to the Pages section:

![Deploying Gatsby to GitHub Pages](https://dev-to-uploads.s3.amazonaws.com/i/wfzq21dps58a5wqoso7z.png)

* In the source drop-down menu, select your `gh-pages` branch:

![Deploying Gatsby to GitHub Pages](https://dev-to-uploads.s3.amazonaws.com/i/8mjj41mh60798hoo5wk0.png)

* This will set up the website to deploy from the `gh-pages` branch to a project directory off your GitHub user domain. For me, the default is `arnonate.github.io/<project-name>/`.

## Setting up Gatsby to Deploy to GitHub

There are a few changes you will need make in your Gatbsy project in order to resolve this directory url:

* Install the `gh-pages` package:

```bash
yarn add gh-pages -D
```

* In your `gatsby-config.js`, add the following line (which should match the project directory created in step 4 above):


```js
module.exports = {
  pathPrefix: `/<project-name>`,
}
```

* Add a deploy script to your `package.json`:

```json
"scripts": {
  "deploy:github": "gatsby build --prefix-paths && gh-pages -d public",
```

* Run the deploy! **Note**: If you ever change the `pathPrefix` setting be sure to run `gatsby clean` before the next deploy to clear the build cache.

## Deploying to an Apex or Subdomain

If you don't want to prefix your pages/assets paths and would rather push to the root directory of an Apex or Subdomain, there are a couple extra steps:

* Remove the `prefixPaths` setting in your `gatsby-config.js`:

```json
module.exports = {
  pathPrefix: `/<project-name>`, // Delete this line
}
```

* If you have already deployed with this setting, make sure you run `gatsby-clean` to clear the build cache.

* Remove `--prefix-paths` from your deploy script:

```json
"scripts": {
  "deploy:github": "gatsby build && gh-pages -d public",
}
```

* In your project settings on GitHub, enter your custom domain name or subdomain:

![Deploying Gatsby to a Custom Domain on GitHub Pages](https://dev-to-uploads.s3.amazonaws.com/i/vlj5r7s8rzbc7r2mxiwi.png)

* Add/change records for your domain at your domain provider. Specifically, if you are using a subdomain, then add a _CNAME_ that points to your root domain on GitHub (username.github.io). If you are using an apex domain, then you need to point an _A_ record or an _ALIAS_ to GitHub Pages:

```bash
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153
```

* Add a _CNAME_ file in the `static/` directory of your Gatsby project with your custom domain address:

```bash
my-domain-name.com
```

For an example of a _CNAME_ file, check out my [Gatsby/Wordpress starter repo](https://github.com/arnonate/gatbsy-wordpress-starter/tree/master/static). Check out the [full project](https://github.com/arnonate/gatbsy-wordpress-starter) if you want a starting point for Gatsby, WordPress, TypeScript and Jest!