Github Pages does not work for me! MY FIX
If you are reading this post, and especially if your github page for your repo is displaying README.md file OR 404 Not Found Page it can mean a few things….
I have faced the exact same problem and spent several hours researching deep into this, so let me do you a favour and summarise my findings for you and SAVE YOU SOME HAIR
Here may be some google searches you have tried before reaching this medium post:
- GitHub pages not displaying correctly
- GitHub pages shows README.md file
- GitHub pages shows 404 page
- GitHub pages does not detect my index.html
- My GitHub page is pointing to the wrong root or domain
- React and GitHub pages does not work
- Cannot deploy my React/ Angular/ Vue website to GitHub Pages
- How do I deploy my React/ Angular/ Vue website to GitHub pages properly
- React BrowserRouter HashRouter not working well with GitHub Pages
FIRST OF ALL
Have you done this:
1)Configuring the publishing source for your GitHub Pages site
For your repository, go to settings and under “GitHub Pages”, select source as ‘gh-pages branch’
This is the TOP FIX for most people if you see README.md being published
…
Just as an add on, these are the scripts you should have for deployment to gh-pages:
...
"scripts": {
"predeploy": "npm run build",
"deploy": "gh-pages -d build",
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
},
...Also, make sure that your index.html is exposed in your gh-pages branch if you are not building and deploying manually and not using React/Angular/Vue..
IF THIS DOES NOT WORK
A) Try deleting your README.md, and deploy it again. What do you see? Do you see the 404 page?
AND
B) Are you building a Single Page Application (SPA) on eg React/ Angular/ Vue?
Then…
Long story short: GitHub Pages does not work well with SPAs!
Quick explanation: GitHub Pages is not ‘smart’ enough to know where to route to for SPAs….
THEREFORE, what we will be doing below is to ‘hack’ or try alternative approaches JUST SO THAT github pages can work properly!
From here on, my explanations will be for React. For Angular and Vue users, you now get the idea whats happening, so google for the correct content eg “How to get Angular to work with github pages”, and just try all the solutions people has offered.
Note what you are doing here is to find ways to make gh-pages work. If you think this takes to much effort, I recommend you to just deploy on other platforms e.g. heroku, firebase
Some Explanations for greater clarity:
#### Notes on client-side routing
GitHub Pages doesn’t support routers that use the HTML5 `pushState` history API under the hood (for example, React Router using `browserHistory`). This is because when there is a fresh page load for a url like `http://user.github.io/todomvc/todos/42`, where `/todos/42` is a frontend route, the GitHub Pages server returns 404 because it knows nothing of `/todos/42`. If you want to add a router to a project hosted on GitHub Pages, here are a couple of solutions:* You could switch from using HTML5 history API to routing with hashes. If you use React Router, you can switch to `hashHistory` for this effect, but the URL will be longer and more verbose (for example, `http://user.github.io/todomvc/#/todos/42?_k=yknaj`). [Read more](https://reacttraining.com/react-router/web/api/Router) about different history implementations in React Router.
* Alternatively, you can use a trick to teach GitHub Pages to handle 404 by redirecting to your `index.html` page with a special redirect parameter. You would need to add a `404.html` file with the redirection code to the `build` folder before deploying your project, and you’ll need to add code handling the redirect parameter to `index.html`. You can find a detailed explanation of this technique [in this guide](https://github.com/rafrex/spa-github-pages).Explanation taken from https://itnext.io/so-you-want-to-host-your-single-age-react-app-on-github-pages-a826ab01e48
OKAY… WHAT SHOULD I DO NOW:
I will just jot down all the approaches I have seen people do online (BRIEFLY) and you could possible try each one of them one by one and see which one works for you. I’ll attach useful links too.
- Add Homepage into your Package.json file
...
"homepage": "https://yourUserName.github.io/yourProjectName/",
...2. Correct deployment of gh-pages
Install gh-pages
// saves gh-pages npm module as a dev dependency
npm install gh-pages --save-devBuild and deploy from your master branch with these 2 scripts added
... //Added predeploy and deploy"scripts": {
"predeploy": "npm run build",
"deploy": "gh-pages -d build",
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
},
...
Note that these will build your master branch and deploy it. Make sure you commit and push your latest changes to master branch before you run these 2 instructions
npm run predeploy
npm run deploy3. Use HashRouter instead of BrowserRouter
It is not impossible to work with BrowserRouter, but it seems like BrowserRouter does not work too well with gh-pages… HashRouter may be a good workaround — just for react+gh-pages
import React, { Component } from "react";
import { HashRouter, Route, Switch } from "react-router-dom";
import Home from "./components/Homepage";
import Page2 from "./components/Page2";
import "./App.css";class App extends Component {
render() {
return (
<div>
<HashRouter>
<div className="App">
<Switch>
<Route exact path="/" component={Home} />
<Route exact path="/page2" component={Page2} />
</Switch>
</div>
</HashRouter>
</div>
);
}
}export default App;
This youtuber used HashRouter for React apps: https://www.youtube.com/watch?v=1wDzEjXbblM
4. Add a basename to your HashRouter/BrowserRouter
In other words follow the previous point but add basename as an attribute:
import React, { Component } from "react";
import { HashRouter, Route, Switch } from "react-router-dom";
import Home from "./components/Homepage";
import Page2 from "./components/Page2";
import "./App.css";class App extends Component {
render() {
return (
<div>
<HashRouter basename={process.env.PUBLIC_URL}>
<div className="App">
<Switch>
<Route exact path="/" component={Home} />
<Route exact path="/page2" component={Page2} />
</Switch>
</div>
</HashRouter>
</div>
);
}
}export default App;
What this does is it will use the basename of your url which is ‘/yourProjectName’ as the root of your page ifyour gh-page url is www.yourUsername.github.io/yourProjectName.
With this, your default page path can be “/” and everything else as per normal, and npm start will direct you to root at localhost:3000 instead of localhost:300/yourProjectName.
That is all that worked for me. There are more solution that other users have shared but there is no one size fits all as it depends on how you have done your routing. Just try all!
Continue to find answers on google! A good search phrase is “React BrowserRouter does not work on Github Pages”
Hope this article has helped some of you! :) Cheers.
Some useful links I have compiled my answers from:
https://itnext.io/so-you-want-to-host-your-single-age-react-app-on-github-pages-a826ab01e48
https://medium.com/@Dragonza/react-router-problem-with-gh-pages-c93a5e243819
