diff --git a/README.md b/README.md index 8d90a2b5..3fe33dc9 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Deploying a React App* to GitHub Pages +# Deploying a React App\* to GitHub Pages \* created using `create-react-app` @@ -8,7 +8,7 @@ In this tutorial, I'll show you how I deployed a React app—which I created usi You can visit the deployed app, at [https://gitname.github.io/react-gh-pages/](https://gitname.github.io/react-gh-pages/). -This repository contains the files related to the app. The `master` branch contains the app's source code (the code the app's developers edit), and the `gh-pages` branch contains a *built* version of the app (i.e. the code that GitHub Pages serves to the app's visitors). +This repository contains the files related to the app. The `master` branch contains the app's source code (the code the app's developers edit), and the `gh-pages` branch contains a _built_ version of the app (i.e. the code that GitHub Pages serves to the app's visitors). The remainder of this document contains a tutorial on creating a React app (using `create-react-app`) and deploying that app to GitHub Pages. @@ -23,12 +23,13 @@ The remainder of this document contains a tutorial on creating a React app (usin v6.10.1 ``` -2. An adequate version of [`npm`](https://nodejs.org/) is installed. Here's the adequate version I use: +2. An adequate version of [`npm`](https://nodejs.org/) is installed. Here's the adequate version I use: ```sh $ npm --version 3.10.10 ``` + 3. An adequate version of [`create-react-app`](https://github.com/facebookincubator/create-react-app) is installed. Here's the adequate version I use: ```sh @@ -40,10 +41,10 @@ The remainder of this document contains a tutorial on creating a React app (usin 4. (**Optional**) An adequate version of [`sed`](http://www.gnu.org/software/sed/) is installed. Here's the adequate version I use: - ```sh - $ sed --version - sed (GNU sed) 4.4 - ``` + ```sh + $ sed --version + sed (GNU sed) 4.4 + ``` 5. A [GitHub](https://www.github.com) account. :octocat: @@ -51,20 +52,20 @@ The remainder of this document contains a tutorial on creating a React app (usin ## Procedure -1. **Create an *empty* repository on GitHub.** (2 minutes) +1. **Create an _empty_ repository on GitHub.** (2 minutes) - * For this tutorial, I'll create a repository named `react-gh-pages`. - * By *empty*, I mean *without* a `README.md` file, a `.gitignore` file, a `LICENSE` file, or any other files. + - For this tutorial, I'll create a repository named `react-gh-pages`. + - By _empty_, I mean _without_ a `README.md` file, a `.gitignore` file, a `LICENSE` file, or any other files. 2. **Create a new React app on your computer.** (5 minutes) ```sh $ create-react-app react-gh-pages ``` - - * This is the app you will deploy to GitHub Pages in step 7. - * I opted to give the app the same name as my GitHub repository (i.e. `react-gh-pages`). However, you can name them differently from one another (e.g. you can name your app `app-123` and your GitHub Repository `repo-456`). - * This will create a new folder named `react-gh-pages` (or whatever you named your app) on your computer. + + - This is the app you will deploy to GitHub Pages in step 7. + - I opted to give the app the same name as my GitHub repository (i.e. `react-gh-pages`). However, you can name them differently from one another (e.g. you can name your app `app-123` and your GitHub Repository `repo-456`). + - This will create a new folder named `react-gh-pages` (or whatever you named your app) on your computer. 3. **Install the `gh-pages` package as a "dev-dependency" of the app.** (1 minute) @@ -72,36 +73,38 @@ The remainder of this document contains a tutorial on creating a React app (usin $ cd react-gh-pages $ npm install gh-pages --save-dev ``` - - * The commands shown in the following steps can all be issued from within the app's folder. + + - The commands shown in the following steps can all be issued from within the app's folder. 4. **Add some properties to the app's `package.json` file.** (3 minutes) - * At the top level, add a `homepage` property. Define its value to be the string `http://{username}.github.io/{repo-name}`, where `{username}` is your GitHub username, and `{repo-name}` is the name of the GitHub repository you created in step 1. Since my GitHub username is `gitname` and the name of my GitHub repository is `react-gh-pages`, I added the following property: - + - At the top level, add a `homepage` property. Define its value to be the string `http://{username}.github.io/{repo-name}`, where `{username}` is your GitHub username, and `{repo-name}` is the name of the GitHub repository you created in step 1. Since my GitHub username is `gitname` and the name of my GitHub repository is `react-gh-pages`, I added the following property: + ```js //... "homepage": "http://gitname.github.io/react-gh-pages" ``` - - * In the existing `scripts` property, add a `predeploy` property and a `deploy` property, each having the values shown below: + + - In the existing `scripts` property, add a `predeploy` property and a `deploy` property, each having the values shown below: ```js "scripts": { //... - "predeploy": "npm run build", + "rmcache": "rm -rf node_modules/gh-pages/.cache", + "predeploy": "npm run rmcache & npm run build", "deploy": "gh-pages -d build" } ``` - - * **Shortcut:** Instead of adding those properties using a text editor; if I have `sed` installed on my system, I can add the properties by issuing the following shell commands: - + + - **Shortcut:** Instead of adding those properties using a text editor; if I have `sed` installed on my system, I can add the properties by issuing the following shell commands: + ```sh - $ sed -i '5i\ "homepage": "http://gitname.github.io/react-gh-pages",' ./package.json - $ sed -i '15i\ "predeploy": "npm run build",' ./package.json - $ sed -i '16i\ "deploy": "gh-pages -d build",' ./package.json + $ sed -i '5i\ "homepage": "http://gitname.github.io/react-gh-pages",' ./package.json + $ sed -i '15i\ "rmcache": "rm -rf node_modules/gh-pages/.cache",' ./package.json + $ sed -i '16i\ "predeploy": "npm run rmcache & npm run build",' ./package.json + $ sed -i '17i\ "deploy": "gh-pages -d build",' ./package.json ``` - + 5. **Create a git repository in the app's folder.** (1 minute) ``` @@ -114,19 +117,19 @@ The remainder of this document contains a tutorial on creating a React app (usin ``` $ git remote add origin https://github.com/gitname/react-gh-pages.git ``` - - * This will make it so the `gh-pages` package knows where you want it to deploy your app in step 7. - * It will also make it so git knows where you want it to push your source code (i.e. the commits on your `master` branch) in step 8. -7. **Generate a *production build* of your app, and deploy it to GitHub Pages.** (2 minutes) + - This will make it so the `gh-pages` package knows where you want it to deploy your app in step 7. + - It will also make it so git knows where you want it to push your source code (i.e. the commits on your `master` branch) in step 8. + +7. **Generate a _production build_ of your app, and deploy it to GitHub Pages.** (2 minutes) ``` $ npm run deploy ``` - - * That's it! Your app is now accessible at the URL you specified in step 4. - * In my case, my app is now accessible at: https://gitname.github.io/react-gh-pages/ - * I recommend exploring the GitHub repository at this point. When I explored it, I noticed that, although a `master` branch did not exist, a `gh-pages` branch did exist. I noticed the latter contained the *built* app code, as opposed to the app's source code. + + - That's it! Your app is now accessible at the URL you specified in step 4. + - In my case, my app is now accessible at: https://gitname.github.io/react-gh-pages/ + - I recommend exploring the GitHub repository at this point. When I explored it, I noticed that, although a `master` branch did not exist, a `gh-pages` branch did exist. I noticed the latter contained the _built_ app code, as opposed to the app's source code. 8. **Optionally, commit your source code to the "master" branch and push your commit to GitHub.** (1 minute) @@ -136,8 +139,8 @@ The remainder of this document contains a tutorial on creating a React app (usin $ git push origin master ``` - * I recommend exploring the GitHub repository once again at this point. When I did that, I noticed that a `master` branch now existed, and it contained the app's source code. - * So, the `master` branch held the source code, and the `gh-pages` branch held the *built* app code. + - I recommend exploring the GitHub repository once again at this point. When I did that, I noticed that a `master` branch now existed, and it contained the app's source code. + - So, the `master` branch held the source code, and the `gh-pages` branch held the _built_ app code. # References @@ -145,6 +148,6 @@ The remainder of this document contains a tutorial on creating a React app (usin # Notes -* I created this React app using [`create-react-app`](https://github.com/facebookincubator/create-react-app). By default, apps created using `create-react-app` have a README.md file that looks like [this](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md). Indeed, the README.md file you're now reading originally looked like that. I have since changed it to look the way it looks today. -* Special thanks to GitHub, Inc., for providing us with the GitHub Pages hosting functionality at no extra charge. -* And now, time to turn the default `create-react-app` app into something unique! +- I created this React app using [`create-react-app`](https://github.com/facebookincubator/create-react-app). By default, apps created using `create-react-app` have a README.md file that looks like [this](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md). Indeed, the README.md file you're now reading originally looked like that. I have since changed it to look the way it looks today. +- Special thanks to GitHub, Inc., for providing us with the GitHub Pages hosting functionality at no extra charge. +- And now, time to turn the default `create-react-app` app into something unique! diff --git a/package.json b/package.json index f74fe811..8adc7d37 100644 --- a/package.json +++ b/package.json @@ -1,22 +1,24 @@ { - "name": "react-gh-pages", - "version": "0.1.0", - "private": true, - "homepage": "http://gitname.github.io/react-gh-pages", - "dependencies": { - "react": "^15.5.4", - "react-dom": "^15.5.4" - }, - "devDependencies": { - "gh-pages": "^1.0.0", - "react-scripts": "1.0.7" - }, - "scripts": { - "start": "react-scripts start", - "build": "react-scripts build", - "test": "react-scripts test --env=jsdom", - "eject": "react-scripts eject", - "predeploy": "npm run build", - "deploy": "gh-pages -d build" - } + "name": "react-gh-pages", + "version": "0.1.0", + "private": true, + "homepage": "http://gitname.github.io/react-gh-pages", + "dependencies": { + "react": "^15.5.4", + "react-dom": "^15.5.4" + }, + "devDependencies": { + "gh-pages": "^1.0.0", + "react-scripts": "1.0.7" + }, + "scripts": { + "start": "react-scripts start", + "build": "react-scripts build", + "test": "react-scripts test --env=jsdom", + "eject": "react-scripts eject", + "rmcache": "rm -rf node_modules/gh-pages/.cache", + "predeploy": "npm run rmcache & npm run build", + "deploy": "gh-pages -d build" + } } +