After following this documentation Deploying a React App* to Github Pages specifically and then having to seek other documentation such as: 8 Steps to publishing your portfolio on GitHub, Create Your Developer Landing Page with GitHub Pages, Deploying React Applications to Github Pages, How to Deploy React App to Github Pages, Publish Your Web Portfolio For Free with Github Pages - In 5 Minutes and about 20 other tabs of documentation that if I kept open for the duration of the 2 days it took to solve my issue my laptop would be functioning slower than a snail, my portfolio site would not work/show up on Github.
The main issue with all documentation is that, as someone who was a beginner to pushing my react-app onto Github, none of it was catered to me. It assumed I knew everything. And as this 48 hours of 40+ tabs showed me, I have a lot more to learn (which is great!) and that the documentation I needed didn't exist.
I asked on twitter for some help after trying to solve it on my own after spending a handful of hours reading endless documentation that had me looking like I was trying to invent a literal lightbulb. Brian Mock (@wavebeem over on twitter!) happened to come across my tweet asking for help and in the end we managed to get my portfolio up and running and I learned how to edit it on both GitHub Platform and locally. Quite literally, if he hadn't offered to help I would probably still be trying to figure out how to get it to work because the documentation I needed didn't exist.
So, in the event that anyone else finds themselves in the same scenario as I did, here's the documentation of how I got my react-app portfolio onto github and how we got my portfolio to actually appear on the link.
What are we trying to do: Get the portfolio on the landing page - so it looks like this saharafathelbab.github.io and be able to make changes when needed.
Step 1: Create Your Repository on Github
Your repository will be named the same as your exact url. When you create your repository, click Open in Desktop.
Step 2: Open Terminal
You will need to get to where your project is from here as in type in the path to get to your file.
cd = Change Directory
It allows you to get to the directory where your project currently is in - essentially typing the path to get to your project.
So if your create-react-app is in your home directory as was the case with me you would just type:
cd [your react app name here] <- just to note there is a space between cd and your react-app-name
If your react-app is in your documents:
cd documents
cd [your react app name here]
Once you type in your react app name, your command line should read:
[your react app name] your-username-for-your-computer-itself $
At this point I was following Deploying a React App* to Github Pages so as per their documentation, your next step will be to install gh-pages as a dev-dependency of your app:
npm install gh-pages --save-dev
You will be writing this right where you are in your terminal so here's what mine looked like following up from the above screenshot of me getting to my folder:
After you do this you may get a few warnings you may not - but you should not be getting any errors at all.
Step 3: Open your react-app in your code editor
Granted, I'm pretty sure you never closed it. You will be going to your package.json file, and be adding a few lines.
In the first { } section you will be adding
"homepage": "http://[your-github-name].github.io/your-repository" above "name": "your-project-name" which is there.
so format:
"homepage": "http://[your-github-name].github.io/your-repository",
"name": "your-project-name",
If this is your portfolio, and you named your repository the same as your exact url without any forward slashing it will look like this format:
"homepage": "http://[your-github-name].github.io",
"name": "your-project-name",
 |
| here's what mine looked like! |
PLEASE REMEMBER AFTER TO PUT A COMMA AFTER YOU WRITE YOUR HOMEPAGE THING, I DIDN'T DO THIS AND WAS STUCK FOR AN HOUR NOT REALIZING I FORGOT TO ADD A COMMA AFTER
You will also need to go into "scripts" section of the package.json and add
"predeploy":"npm run build",
"deploy": "gh-pages -d build"
So it will look like this:
Step 4: You will now create a git repository in your current project folder
The command is:
git init
When I ran that exact command, I was met with an error that looked like this:
I came across a StackOverFlow Post with this same exact error. The next step you need to do is open a new window of terminal, do not X out the one you have up!! Just open a new window of terminal. On mac, you have to tap the terminal icon in your doc area with two fingers and you'll see something like this come up:
Click New Window.
You will then run the command:
xcode-select --install
this line installs the x-code Command Line tools, you do not need X-Code itself, just the command Line tools to fix the error. After you type in the command, you will get pop up asking for your permission to install the Command Line tools and also see a prompt appear after that pop up in the terminal.
git init
You should be seeing something similar to this in your command line:
Step 5: You will now add the Github repository (the one you created way back in step 1) as a remote in your local (your literal machine/laptop) git
This allows the gh-pages to know where the app will be pushed onto.
The command you would be typing is:
git remote add origin https://github.com/your-username/your-repository.git
For my scenario, I was adding it to my Github landing page saharafathelbab.github.io and this is what my command looked like:
Step 6: The built app code gets to be deployed to your github
You will then run the command:
npm run deploy
You will be prompted to put your github username and password in terminal.
If you look at your Github repository you'll notice that a master branch doesn't exist but gh-pages does. The gh-pages is what we just deployed over.
Your Build-App code is similar to your 'public' folder contents in your create-react-app project.
But we actually need our Master branch, so the tutorial doesn't stop here.
Step 7: You will then commit your source code to the master branch and push it onto Github.
As I mentioned before your master branch doesn't even look like it exists on your Github. So we've got to bring it to life.
You will now run the following commands:
git add .
git commit -m " insert message here along the lines of what we're doing, in this instance we are creating a react app"
git push origin master
So let's break down what each of these commands do:
- git add .
Yes that is a period at the end there. You need that, it's git add SPACE period. This selects all files in your current directory and puts them in the staging area. If it helps, think of it like this scenario:
You have a dozen packages you're delivering to this one house, and when you get to the house, you take the packages out of the truck and add all of them to the patio area i.e. the staging area
- git commit -m "creating my react app"
Keeping up with the story above, you ring the door bell and someone answers the door. They need to sign their name on a device before you can hand them their packages they ordered.
the -m means message and in quotations is the message relating to what you're planning to push onto GitHub.
-git push origin master
The person signs their name and finally you can give them their packages to take in their home.
Now that you have the message of what you're committing, you can push your source code to master branch.
The "message" that you're typing shows up like this on Github:
Step 8: Right now your source code is in the master branch and the gh-pages branch has the built app code. We need to switch that around and rename it so the content of gh-pages is in a branch called master.
gh-pages branch -> master branch
latest branch (our new branch) -> set as the default branch
Here's the full process via Brian Mock's screenshot of if you want to rename branch b1 to branch b2
That's a lot to take in, but we're going to do it one step at a time.
8.1 We need to open a new terminal window
At this point, we no longer need the one with all of our previous work. So you can open a new terminal window.
8.2. In terminal, get to your create-react-app on GitHub
The commands to do that are similar to beginning steps except now we're going to our GitHub folder on our computer.
For me, to get to my repository on my computer the path is Documents -> GitHub -> My Repository name
Converting that into commands:
cd documents
cd Github
cd your-repository-name
 |
| these are the exact commands I did - remember: my github repository name is saharafathelbab.github.io |
8.3 The first switch we will be doing is master content -> goes to a new branch name
8.3.1 We need to first checkout out Master branch - kind of like checking out something at the supermarket
The command you type is:
git checkout master
8.3.2 We need to move the master branch to a new name
git branch -m NEW-NAME-OF-BRACH-HERE
To translate what you're doing in git: You are currently on the master branch, and with the command above, everything from the master branch is being renamed to your new branch you are creating!
I personally named my new branch 'latest'.
So my command looked like:
git branch -m latest
So my command looked like:
git branch -m latest
So, now your local GitHub repository has this newly named branch called latest, but your remote one (Github Platform) needs to catch up.
8.3.3 Now we push the newly created branch onto GitHub Platform
The command you use is
git push -u origin latest
The u is short for --set-upstream.
So now we are pushing our source code to our newly named branch, latest.
8.3.4 We need to delete the remote branch 'master'.
We do need the branch name master for our next step but we essentially need a clean-slate-master-branch i.e. a new one!
The command you use is:
git push origin :master
This deletes your remote branch Master so it's not chilling around - we already have our new-branch-name with all the info! - and we can then reuse the name master for a branch.
8.3.5 We need to delete the local version of master
Right now the branch name 'master' is still floating around - kind of like you know when you delete a document and it goes to trash but then you have to delete it from the trash? Yeah, so this is like that!
To delete the local version of master, run this command:
git branch -d master
8.4 gh-pages content -> goes to master branch
We need to first checkout out gh-pages branch - so we're back to checking things out of our git supermarket again
The command you type is:
git checkout gh-pages
8.4.1 We need to move the gh-pages branch to a new branch name master
The command is:
git branch -m master
So, as with the other branch, now your local GitHub repository has this newly named master branch, but your remote one (Github Platform) needs to catch up.
8.4.2 Now we push the newly created master branch onto GitHub Platform
The command you use is:
git push -u origin master
Unlike last time where we deleted both remote and local version of our old master branch, we DO NOT NEED to delete gh-pages.
8.5 New branch name -> Set as the default branch
Now let's go to our GitHub platform!
Go to your repository and click Settings:
And TADA - Your Portfolio/Project is now LIVE!
I would also like to mention again that I really wouldn't have figured out how to get my portfolio up and running if it wasn't for Brian Mock (@wavebeem over on twitter!) so if you're in need of an Engineer to follow on there, head over and give him a follow!
He also helped me figure out how to edit my react app as well, so I'll be writing that documentation to go up next week if you're also lost on that like I was!
I've never really written tech documentation per se, so I hope I explained everything properly and with that I'll see you in the next part of the documentation!
This is great!
ReplyDelete