How to host your (Angular, ReactJS, VueJS, …) SPA on GitHub Pages

If you have ever used Github Pages, you know that it is very simple (and fast) to put a website online (if you don’t know what I’m talking about, don’t be scared. Read the post and learn here). In the first tests I did, everything worked perfectly, it was beautiful!

But recently when I hosted a SPA and I noticed a small problem with the application routes. After a little research I was able to find a viable solution.

Today I share this solution, showing how you can host your Single Page Application, whether in Angular, ReactJS or VueJS, without any problems with the routes.

For this example I’ll use Angular, but the proccess is the same. So let’s start.

Step 1: What is GitHub Pages?

From the help of Github, we have:

“GitHub Pages is a static site hosting service designed to host your personal, organization, or project pages directly from a GitHub repository.”

Basically, with GitHub Pages, we have the possibility of easily hosting a static site using a repository.

To do this simply upload the files of your website to a repository that follows the pattern <yourusername>.github.io. In my case it looks like geeksilva97.github.io.

Step 2: Our App

We already understand how github pages works. Let’s now understand the proposed application for this post.

Well, for this post we will build an Angular application with only three pages which are: home and about, with only a text example, and a not found page for show 404 message.

Basically, you need to create a component for each page. See the our application structure and routing:

Image 1 — Folde structure and Routing

In my application I added the Bulma CSS Framework, but you can be free to choose your favorite framework. If you want to add Bulma CSS to your application, see the following post:

https://medium.com/@edigleyssonsilva/adding-bulma-css-framework-to-your-angular-6-app-8e0b28ac2cf5

Step 3: Build your app

Our app works perfectly. When I run ng serve command I can see the Home Page:

Image 2 — Home page

I can see the About Page too:

Image 3 — About page

And finally, when I find with a unknown URL I can see the Not found Page:

Image 4 — NotFound Page

So, you can replicate this in ReactJS or VueJS or someone. Maybe you have already an application. The point is, this post is about GitHub Pages so let’s upload our app to it.

You know that to hosting we need to generate the dist. In Angular we can do this with the following command:

ng build --prod

The --prod option is only to optimize the build files.

In Angular, the builded app can be found at dist folder.

Step4: Host app on GitHub Pages

The most easy part is here, really. Once you have your app dist files on dist folder you need to push it to a GitHub Repository. You can think what repo is??

Yeah, the repo is the <yourusername>.github.io.

You have several ways to do this, here we will push it using the git-cli.

So, copy the content of dist to another folder, like my-gh-app, and move to this folder. In this folder you should have run the command:

git init

This command will initialize a git repo in your current folder.

Now you need to create the repo at https://github.com. When you create you will a page like the following (my repo is geeksilva97.github.io):

Image 5 — Created repo

Our case is the second. So, run the following command line in the current terminal:

git remote add origin https://github.com/geeksilva97/geeksilva97.github.io.git

With this you defined the remote repo. Now you need to commit your files and push it to github with the commands:

git add .
git commit -m "First commit"
git push -u origin master

After that you will can see your files in your remote repository at github.com. See the command in terminal:

Image 6 — The command in our terminal

Now you can see the files in your GitHub repo. Refreshe yout github repo and you will see something like:

Image 7 — First commit on GitHub

Now we can access we app by the address https://geeksilva97.github.io. Note that URL will be your repo name.

NOTE: Sometimes it takes time for the page to be available. If you access the URL and receive an error. Try pointing directly to the index.html file to make it work. Something like https://geeksilva97.github.io/index.html.

Our app is published. That is AWESOOOOOME! I will share with my friends!

Step 5: Solving problems with routes

So I sent the /about link to my friends. Hoping they can help me with the content, I’m very excited. But when they access the link they see:

Image 8 — GitHub Page Erro

I’m getting an error, but why?

So, a SPA application mount the routing at index.html file, that is the only file to do it. But when you access a URL like /about the server will not redirect it to index.html and the route will not be mounted.

Right, we know the problem, but how can we fix it? I have to say: “You are lucky” because I have the key.

To fix it we will use a special file of GitHub Pages. The file is 404.html. This file is a file that will be displayed when a URL can’t be found. In this file we will improvise a .htacces (web.config, etc.) logic, that is, we’ll redirect to index.html passing the path through the localStorage and redirect to the correct path programmatically.

Back to my-gh-app folder and create the 404.html with the content:

Code 1–404.html file

Bascially we get the path like “about” we set this path in localStorage. After, we redirect to root URL.

To finish our logic we need to change our app to redirect programatically. So in your Angular app you will add a logic in te constructor of app.component.ts. The changed file looks like:

Code 2 — app.component.ts to handle SPA routing

Basically, we get the path of the localStorage, then we remove the path (to clear) and redirect to the correct path. Note that we added this logic at starting point of app.

In your ReactJS you can add to componentDidMount() method in App.js file. In your VueJS app you can add to mounted() method at main class.

That’s it. Now you will build your app again and will copy the dist content to my-gh-app and will push it to GitHub.

Now you can share the https://geeksilva97.github.io/about with your friends. Try it!

This example is useful but quite simple, you can improve this. Se the references and access the links to libraries to do it.

Conclusion

With github Pages you have many advantages like fast and easy deploy as well as a free hosting as a subdomain of GitHub.

Increasing the power of use, with this logic you can be publishing your applications Angular, ReactJS or VueJS for testing, show your friends or to show a portfolio. You have many possibilities, so enjoy!

References

• A library to improve this logic and hadle SEO — https://github.com/rafrex/spa-github-pages