From 0517444275075174a7a568b76b79808e4d56262b Mon Sep 17 00:00:00 2001 From: Dan Abramov Date: Sun, 20 Nov 2016 20:12:43 +0000 Subject: [PATCH] Better GH Pages guide --- packages/react-scripts/template/README.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/packages/react-scripts/template/README.md b/packages/react-scripts/template/README.md index 8fd69a5bc0..14d0e30a58 100644 --- a/packages/react-scripts/template/README.md +++ b/packages/react-scripts/template/README.md @@ -936,7 +936,9 @@ This will let Create React App correctly infer the root path to use in the gener >Note: this feature is available with `react-scripts@0.2.0` and higher. -**THE BELOW STEP IS IMPORTANT!**
+#### Step 1: Add `homepage` to `package.json` + +**The below step is important!**
**If your skip it, your app will not deploy correctly.** Open your `package.json` and add a `homepage` field: @@ -947,7 +949,7 @@ Open your `package.json` and add a `homepage` field: Create React App uses the `homepage` field to determine the root URL in the built HTML file. -**Have you added the `homepage` field? Then let's move on.** +#### Step 2: Install `gh-pages` and add `deploy` to `scripts` in `package.json` Now, whenever you run `npm run build`, you will see a cheat sheet with instructions on how to deploy to GitHub Pages. @@ -969,17 +971,28 @@ Add the following script in your `package.json`: (Note: the lack of whitespace is intentional.) +#### Step 3: Deploy the site by running `npm run deploy` + Then run: ```sh npm run deploy ``` -**If you see 404 errors for JS and CSS, re-read the note at the beginning of this section saying "THE BELOW STEP IS IMPORTANT".** +#### Step 4: Ensure your project's settings use `gh-pages` + +Finally, make sure **GitHub Pages** option in your GitHub project settings is set to use the `gh-pages` branch: + +gh-pages branch setting + +#### Step 5: Optionally, configure the domain You can configure a custom domain with GitHub Pages by adding a `CNAME` file to the `public/` folder. -Note that GitHub Pages doesn't support routers that use the HTML5 `pushState` history API under the hood (for example, React Router using `browserHistory`). This is because when there is a fresh page load for a url like `http://user.github.io/todomvc/todos/42`, where `/todos/42` is a frontend route, the GitHub Pages server returns 404 because it knows nothing of `/todos/42`. If you want to add a router to a project hosted on GitHub Pages, here are a couple of solutions: +#### Notes on client-side routing + +GitHub Pages doesn't support routers that use the HTML5 `pushState` history API under the hood (for example, React Router using `browserHistory`). This is because when there is a fresh page load for a url like `http://user.github.io/todomvc/todos/42`, where `/todos/42` is a frontend route, the GitHub Pages server returns 404 because it knows nothing of `/todos/42`. If you want to add a router to a project hosted on GitHub Pages, here are a couple of solutions: + * You could switch from using HTML5 history API to routing with hashes. If you use React Router, you can switch to `hashHistory` for this effect, but the URL will be longer and more verbose (for example, `http://user.github.io/todomvc/#/todos/42?_k=yknaj`). [Read more](https://github.com/reactjs/react-router/blob/master/docs/guides/Histories.md#histories) about different history implementations in React Router. * Alternatively, you can use a trick to teach GitHub Pages to handle 404 by redirecting to your `index.html` page with a special redirect parameter. You would need to add a `404.html` file with the redirection code to the `build` folder before deploying your project, and you’ll need to add code handling the redirect parameter to `index.html`. You can find a detailed explanation of this technique [in this guide](https://github.com/rafrex/spa-github-pages).