How to Deploy a GatsbyJS Blog on GitHub Pages as a User Site
Tags: gatsby, react, github
Published: 2019-03-07 13:45:40

---
title: How to Deploy a GatsbyJS Blog on GitHub Pages as a User Site
published: true
description: Hosting a GatsbyJS blog on GitHub Pages for your user site requires additional configuration. Here's how to deploy.
tags: Gatsby, GatsbyJS, React, GitHub
canonical_url: http://jarednielsen.com/deploy-gatsbyjs-github-pages-user/
---

![How to Deploy a GatsbyJS Blog on GitHub Pages as a User Site](https://thepracticaldev.s3.amazonaws.com/i/m3dvx2xcdpxcdwgvqp16.png)

_This article originally published on [jarednielsen.com](http://jarednielsen.com/deploy-gatsbyjs-github-pages-user/)_

GatsbyJS is a great option for a static site generator, even if you're unfamiliar with React. It's very easy to use, super snappy, and has a robust ecosystem. Win win win! To deploy a GatsbyJS blog as a User site on GitHub Pages requires some minor additional configurations. According to the docs, [your personal User site on GitHub Pages repository must be deployed from `master` branch](https://help.github.com/articles/user-organization-and-project-pages/#user-and-organization-pages-sites). This creates an issue for us (no pun intended). When we run `build` our `master` branch will be cluttered with files (not to mention entirely transformed). The solution is to work locally from a `develop` branch and use `gh-pages` to deploy to `master` on remote.

## Install GatsbyJS and Create a New Blog
If you're entirely new to this, run the following commands from the command line:

```sh
npm install -g gatsby-cli
gatsby new <your-gh-pages-repo.github.io> https://github.com/gatsbyjs/gatsby-starter-blog
cd <your-gh-pages-repo.github.io>
gatsby develop
```

Your terminal output should read:

```sh
You can now view gatsby-starter-blog in the browser.

  http://localhost:8000/
```

## Initialize Git
If you haven't already, create your repository on GitHub and initialize it locally. Add your remote origin; then add, commit and run:  

```sh
git branch -m develop
```

This will _move_ your `master` branch to a new branch named `develop`. I name mine `develop` to mirror the GatsbyJS command for local development, but you can name it whatever you like.

If you run `git branch`, you will notice you don't have a `master` branch anymore. This is fine and good. If you navigate back to GitHub, you will find your `master` branch there. You won't push to `master`. Instead, you will run:

```sh
git push -u origin develop
```

## Install & Configure gh-pages
Install [`gh-pages`](https://www.npmjs.com/package/gh-pages):

```sh
npm install gh-pages --save-dev
```

To your `package.json`, add the following script:

```js
{
    "scripts": {
        ...
        "deploy": "gatsby build && gh-pages -d public -b master",
    }
}
```

Note the `-b master` flag. When we run `gh-pages`, we will do so from our `develop` branch, but we want it to deploy to our `master`.  

To deploy, run:

```sh
npm run deploy
```

## Draft Branches
When I'm working on a draft for a blog post, I create a new branch and when I'm ready to publish, I merge it with `develop`, then add/commit/push and `npm run deploy`.

## Using a Custom Domain Name with GitHub Pages
If you own and want to use your custom domain name with your personal GitHub Pages, the set up is fairly easy, but different depending on your DNS provider. I refer you to the GitHub Help article on [Using a custom domain with GitHub Pages](https://help.github.com/articles/using-a-custom-domain-with-github-pages/) for your specific situation.

Add your `CNAME` file to your `static` directory in your `develop` branch. The `CNAME` file only needs to contain the name of your domain, so, in my case there is one line that reads:

```
jarednielsen.com
```

Happy blogging!


---

I write a weekly newsletter where I share articles about programming, problem solving and lifelong learning. [Join now](http://eepurl.com/cP8CMn)