by Jake Wiesler
Surge VS GitHub Pages: How to deploy a create-react-app project
As a developer, there are several ways you can show off your skills to peers and prospective employers. Open source contributions are great. Blogging is great. But at some point you’ll want to get projects up on the web, where people can actually use them.
Too many times have I started something locally and never seen it through. You may have done the same. One reason this is so common is because of all the extra work that goes into deployment.
Wouldn’t it be nice to have a central hub where all of your projects live without worrying about hosting and server configuration? This post will walk you through two popular deployment tools that require a minimum amount of effort.
Before you get started, let me tell you about my new best friend,
create-react-app. If you've been thinking of learning React — but are taken back by the amount of time it requires to get a project up and running — this command line interface (CLI) tool is your saving grace. It will take care of most of the boilerplate you need to start a project.
To install it and create your first project, go into your terminal and run these commands:
npm install -g create-react-app
create-react-app <your project name>
cd <your project name>
Out of the box
create-react-app comes with a few handy scripts that allow you to develop your project locally and deploy it afterwards. They can be found in the
package.json file at the root of your project directory.
npm start to run your project locally while you develop it. Then use
npm run build to prepare your project for deployment.
Surge.sh and GitHub Pages
Let’s fast forward a bit. You’ve built a basic app and are ready to deploy it to the web.
Both of these platforms are powerful in their own right. Which one you use comes down to your situation. My goal is to give you a better understanding as to why these tools exist, and what you can do with them.
Also note that even though this post is all about publishing projects created with the
create-react-app CLI, Surge and GitHub Pages will work with even the most basic of projects. You may be able to skip some of these steps if you aren’t using React itself.
Surge is a really awesome piece of software that I recently discovered from a thread on Reddit. At its core, Surge is a CLI that allows you to deploy your projects for free. And quickly, too. What makes Surge really stand out is its simplicity.
Let’s walk through a simple example using
First, install the
surge package globally:
npm install -g surge
Now that Surge has been installed on your machine, you need to prepare your project for deployment. I mentioned above that
create-react-app has a script in
build . This script essentially prepares the application for production by bundling and optimizing all of the code.
npm run build in your project’s root:
npm run build
You should notice that a new folder has been created in the root of your project directory called
build . This folder contains the production-ready application.
Excellent, you’re almost finished. All that’s left is to run the
surge command in your project’s root:
If this is your first time running
surge you'll be prompted to create an account. Add an email and password, then hit enter. You’ll then see output similar this:
To deploy your project, Surge only needs two things from you:
- The path to the project
- The domain to host it on
You’ll notice that the project path field in the terminal defaults to the root directory. Surge assumes that the whichever directory you’re running the
surge command in is the directory you wish to deploy. In your case, you need to point Surge to the
build directory created when you ran
npm run build .
If your project path is
path/to/my-project, edit this to
path/to/my-project/build. Once you’ve made this change, press enter to confirm.
After entering the project path, Surge will suggest a random domain to use. You can delete it and add your own domain if you wish. It just needs to have the
.surge.sh extension at the end. The tool also allows for custom domains, which is really awesome.
Accept the suggested domain, or add your own (custom or random with correct surge extension), then hit enter.
That’s all she wrote! Navigate to the domain in your browser and you should see your project up and running.
Note that if your application is using client-side-routing, Surge recommends you rename the
index.html file in your
build directory to
200.html before running the
surge command. You can find out more information in the Surge documentation.
GitHub Pages makes it easy to turn GitHub repositories into full fledged static websites. Many organizations use this service to host their documentation and project demos, but you can use it for whatever you’d like.
Note that in order for this to work, your must first push the code to a repository on GitHub. If this sounds foreign to you, check out further documentation here.
If you’ve ever run
npm run build using
create-react-app before, then you may have noticed output that looks like this:
create-react-app comes with detailed documentation to help users publish their work using all sorts of tools. Here you can see real time terminal output instructing us on how to do so via GitHub Pages. Let’s try it out.
package.json by adding a new field named
If your GitHub username is
george-lucas, and your project's GitHub repository is
SithJS, the value of the
homepage field should be
npm run build again after the change:
Did you notice the new output above? The
create-react-app CLI is walking us through the entire process. Pretty snazzy.
Next you need to install the
gh-pages plugin. This will allow us to publish to the
gh-pages branch on GitHub straight from within the terminal:
npm install --save-dev gh-pages
gh-pages is a special branch that GitHub Pages uses to publish projects. The beautiful thing about it is that the branch lives in the same repository as your project’s code, but doesn’t affect the project itself.
Note that if you already have a
gh-pages branch in your project's repository, it will update the branch accordingly. If the branch doesn't exist, it will create it on the fly.
Add a new script to the
scripts field inside
package.json. Let’s call the script
"deploy" : "npm run build&&gh-pages -d build"
And finally let’s run it:
npm run deploy
npm run deploy will first build your project via
npm run build. Then it will publish it to a
gh-pages branch on GitHub via
gh-pages -d build.
We’re almost done. Head to your project’s repository settings on GitHub. In the GitHub Pages section, confirm that your project is set to use the
You can now navigate to the URL you entered in the
homepage field of your
package.json file, where you’ll see your project has been deployed!
Note that — like with Surge — GitHub Pages also has trouble with client-side routing.
create-react-app lists a few solutions in the documentation for GitHub Pages integration.
In all honesty, you can’t go wrong with either of these options. They’re both great. Let’s recap some key features of each:
- Minimal configuration to deploy a project
- Makes no assumptions about technology used
- Seamless integration with build tools such as Grunt and Gulp
- Can be used as a development dependency when building your own tools
- Keeps project code and webpage(s) housed in a single repository
- Centralizes all projects underneath your <username>.github.io domain
- Deploy from the command line or from your repository settings on GitHub
- Works great with static site generators like Jekyll
Personally, I chose GitHub Pages for my most recent project because I already use GitHub on a daily basis and I like to keep everything centralized. Maybe it’s my OCD talking, but I love having individual GitHub repositories for projects that I can deploy as a subdomain of
If you’re simply creating a test project, or you want to show a demo to a client, using Surge’s super-fast CLI to generate a webpage is hard to pass up. You can generate the domain quickly and tear it down afterwards.
At the end of the day, the best tool for the job is the one that makes you productive. The information I’ve provided should give you a good understanding of where each shines. Audit your project needs and choose which is right for you.