Example for using browserHistory when deploying a create-react-app to gh-pages.

2 years after

Using browserHistory with Gh-Page deployments for create-react-app

This project was bootstrapped with Create React App.

Live Demo:


You should read the section on client-side-routing in the create-react-app documentation for understanding why Github Pages does not play well with client-side-routing.


As noted in the create-react-app docs if not choosing to use hashHistory one needs to follow the documentation in this repository for using the browserHistory method.

The Problem:

The SPA-Github-Pages fix is a very clever way to handle the issue with client-side routing; however, it fails to handle this case:

The root path of the client-side-routing does not match the url passed as "homepage": in the package.json.


import { browserHistory, Route, Router } from 'react-router';
import App from './App';
import { Page404 } from './pages';

// "homepage": "https://<username><project-name>/",

export default () => (
  <Router history={browserHistory}>
    <Route path='/' component={App}>
      <Route path='/one' />
      <Route path='/two' />
    <Route path='*' component={Page404} />

The current configuration has the root path as / which will match 'https:/<username>'. In this instance the view seen on traveling to the GitHub Pages link will be the Page404 because the router reads /<project-name>/ as an undefined route. On traveling to 'https:/<username>' the Github 404 will be seen because it is not hosting /<project-name>/ anymore.

The Solution:

create-react-app has an env var that is exposed called process.env.PUBLIC_URL. This env var provides the application with the data provided to the package.json as "homepage":



With this exposed across the whole application we can make the following adjustment:


<Route path={`${process.env.PUBLIC_URL}/`} component={App}>

Now when visiting the Github Pages link you will be directed to the root path's view.

Routing Tree for <Router/> vs Browser

All subsequent routes on the router will replace /<project-name>/:

Router Browser
'/' ''
'/one' ''
'/two' ''
'*' '*'

GitHub 404's will be reached if traveling to:

Please Note that any navigation back to the root path outside of the <Router/> must explicitly be stated in the same manner.

Related Repositories



A web app for crowdsourcing immigration raid info so undocumented people can avo ...



Searchkit starter app. Based off create-react-app ...

A home for generative art ...



Starter project for React with React Router, React Bootstrap, Redux and Sass ...



Portfolio website ...