Heads up! To view this whole video, sign in with your Courses account or enroll in your free 7-day trial. Sign In Enroll
Preview
Start a free Courses trial
to watch this video
Learn how to deploy and host a React app on GitHub Pages, a free hosting solution provided by GitHub that lets others view your repository as a static website.
Resources
package.json Snippets
"homepage": "http://myname.github.io/myapp"
"scripts": {
"predeploy": "npm run build",
"deploy": "gh-pages -d build",
...
}
Set a Base URL
When using React Router, if your app is served from a sub-directory, pass the 'basename' prop to the router to set the base URL for all locations. For example:
<BrowserRouter basename="/course-directory">
Related Content
In this video, I'll deploy and
0:00
host a React app on GitHub Pages,
a free hosting solution provided by GitHub
0:02
that lets others view your repository
like a regular static website.
0:06
Meaning, a site containing HTML, CSS, and
0:10
JavaScript files, like the files
in the build folder, for example.
0:13
When you run npm run build,
in the console output,
0:17
you see a message letting you know that
you can control where you host your build
0:21
using a homepage field in
your package.json file.
0:26
It shows that you could,
for instance, build it for
0:29
GitHub Pages by setting
the homepage field to http://,
0:32
your GitHub user name,
followed by the GitHub Pages domain,
0:37
which is github.io, and
your project's repository name.
0:41
Now, I already have my
React app up on GitHub
0:45
in a repository named course-directory.
0:48
So now I'm ready to deploy the app
to GitHub Pages as a project page.
0:50
A project page means that each repository,
or project,
0:54
in your GitHub account can have its own
hosted website on the GitHub servers.
0:58
The first thing I need to do is add the
homepage field to my package.json file.
1:03
I'm going to use my GitHub username,
guilh,
1:11
in the URL with https://guilh.github.io.
1:15
And as the repository name,
I'll write course-directory.
1:21
Next, I need to install
the Github Pages package via npm, and
1:28
a couple of deploy
scripts to package.json.
1:32
In the console,
type npm install --save gh-pages.
1:35
This is going to let you publish to
a branch on Github called gh-pages.
1:42
Anything you push to that branch,
1:47
like your build, is going to
appear on the github.io domain.
1:48
Next, I'll set up my deploy
scripts in package.json.
1:53
In the scripts object, add two properties,
1:57
predeploy and deploy.
2:03
You can also copy these scripts from
the teacher's notes with this video.
2:06
Set predeploy to the build command with,
npm run build.
2:11
And to publish everything from your
build folder to your gh-pages branch,
2:17
set deploy to, gh-pages -d build.
2:22
Make sure that you write
the predeploy script first.
2:28
That way predeploy will run before
deploy runs, which means that it will
2:32
automatically create
the production-ready build of your app.
2:37
It will even generate the build folder for
you, if you haven't done that yet.
2:40
In fact, I'll delete the build folder
from my project to better demonstrate.
2:44
All right, now I can publish my
build to a gh-pages branch on my
2:50
GitHub repo by running the command,
npm run deploy.
2:55
This begins creating
an optimized production build.
3:00
As you can see, a new build folder
is generated in my project, and
3:04
now I should be all set.
3:08
I see a message in the console letting
me know that my app was published.
3:10
In my GitHub repository, if I click
Settings and scroll down to GitHub Pages,
3:13
I see that my site is published at
guilh.github.io/course-directory.
3:19
And under Source, it shows that my GitHub
Pages site is currently being built from
3:26
the gh-pages branch.
3:29
And I can view the gh-pages
branch in my repository
3:31
under the list of branches, good.
3:34
Now the app, as you know, is served from
a subdirectory named course-directory.
3:38
So when I first view the app
on the GitHub domain,
3:44
I immediately get the app's
Page Not Found route.
3:46
This is because I initially set
React Router to load the home component
3:50
at the root path using a forward slash,
as you can see here.
3:54
Well, currently,
the URL path is /course-directory, so
3:58
it doesn't match any of
the routes defined in the router.
4:03
If your app is served from a subdirectory
like this, you can set a base URL for
4:07
your routes, so that the root path
always renders the desired component.
4:11
I've posted an example of how you can
do that in the teacher's note with
4:16
this video.
4:20
Now when I click the navigation links,
the URL paths match the routes, so that
4:20
the app looks and works as expected, even
without the main subdirectory in the URL.
4:25
And there's another big
issue with the router.
4:32
Watch what happens when I refresh the app.
4:34
I get a 404 page.
4:37
This has to do with how GitHub Pages
handles client side routing.
4:38
You see, GitHub Pages does not support
routers that use the HTML5 pushState
4:42
History API under the hood, like React
Router uses to manage your routes and
4:47
keep your UI in sync with the URL.
4:52
So when there is a fresh page load for
a URL like courses/javascript,
4:54
the server by default will look for
a file to load under that same path.
4:58
The GitHub Pages server returns a 404,
5:03
because it cannot find
courses/javascript in the build.
5:06
That's all being managed behind
the scenes by React Router.
5:09
If you're not using a router,
then you don't need to worry about this.
5:13
When you are using a router in the app
you're deploying to GitHub Pages, there
5:16
are a couple of solutions you can use to
avoid getting 404s on page refreshes.
5:20
You could switch from using
the History API to routing with hashes.
5:26
In Director router, you can switch
to hash history using HashRouter,
5:30
which uses the hash portion of the URL
to keep your UI in sync with the URL.
5:34
This also means that it's going
to display a hash in your URLs.
5:39
As you can see when you use HashRouter,
5:43
you're able to refresh the app at any URL,
and it's not going to give you a 404.
5:45
It's also going to serve the app
from the main subdirectory and
5:50
display it in the URLs.
5:52
There's also a trick you can use to
instruct GitHub Pages to handle 404s by
5:55
redirecting to your index.html page,
using a special redirect parameter.
5:59
Now, this method is pretty tricky and
involves a few complicated workarounds.
6:04
I've posted a link to this technique
in the teacher's notes with this video.
6:09
We also have an entire workshop dedicated
to hosting websites on GitHub Pages.
6:12
So if you wanna learn more about
hosting projects with GitHub Pages,
6:17
including using your own domain name,
6:20
I've posted the link to the workshop
in the teacher's notes with this video.
6:22
You need to sign up for Treehouse in order to download course files.
Sign up