diff --git a/docusaurus/docs/available-scripts.md b/docusaurus/docs/available-scripts.md index a6a32751926..f7adadb0853 100644 --- a/docusaurus/docs/available-scripts.md +++ b/docusaurus/docs/available-scripts.md @@ -20,9 +20,9 @@ Launches the test runner in the interactive watch mode. See the section about [r Builds the app for production to the `build` folder. It correctly bundles React in production mode and optimizes the build for the best performance. -The build is minified and the filenames include the hashes. Your app is ready to be deployed! +The build is minified and the filenames include the hashes. See the [production build](production-build.md) section for more information. -See the section about [deployment](deployment.md) for more information. +Your app is ready to be deployed! See the section about [deployment](deployment.md) for more information about deploying your application to popular hosting providers. ## `npm run eject` diff --git a/docusaurus/docs/code-splitting.md b/docusaurus/docs/code-splitting.md index b288785b574..8cfcee4700f 100644 --- a/docusaurus/docs/code-splitting.md +++ b/docusaurus/docs/code-splitting.md @@ -45,7 +45,7 @@ class App extends Component { export default App; ``` -This will make `moduleA.js` and all its unique dependencies as a separate chunk that only loads after the user clicks the 'Load' button. +This will make `moduleA.js` and all its unique dependencies as a separate chunk that only loads after the user clicks the 'Load' button. For more information on the chunks that are created, see the [production build](production-build.md) section. You can also use it with `async` / `await` syntax if you prefer it. diff --git a/docusaurus/docs/deployment.md b/docusaurus/docs/deployment.md index a49ffc24219..d25f18244fe 100644 --- a/docusaurus/docs/deployment.md +++ b/docusaurus/docs/deployment.md @@ -1,461 +1,461 @@ ---- -id: deployment -title: Deployment -sidebar_label: Deployment ---- - -`npm run build` creates a `build` directory with a production build of your app. Set up your favorite HTTP server so that a visitor to your site is served `index.html`, and requests to static paths like `/static/js/main..js` are served with the contents of the `/static/js/main..js` file. - -## Static Server - -For environments using [Node](https://nodejs.org/), the easiest way to handle this would be to install [serve](https://github.com/zeit/serve) and let it handle the rest: - -```sh -npm install -g serve -serve -s build -``` - -The last command shown above will serve your static site on the port **5000**. Like many of [serve](https://github.com/zeit/serve)’s internal settings, the port can be adjusted using the `-p` or `--port` flags. - -Run this command to get a full list of the options available: - -```sh -serve -h -``` - -## Other Solutions - -You don’t necessarily need a static server in order to run a Create React App project in production. It works just as fine integrated into an existing dynamic one. - -Here’s a programmatic example using [Node](https://nodejs.org/) and [Express](http://expressjs.com/): - -```javascript -const express = require('express'); -const path = require('path'); -const app = express(); - -app.use(express.static(path.join(__dirname, 'build'))); - -app.get('/', function(req, res) { - res.sendFile(path.join(__dirname, 'build', 'index.html')); -}); - -app.listen(9000); -``` - -The choice of your server software isn’t important either. Since Create React App is completely platform-agnostic, there’s no need to explicitly use Node. - -The `build` folder with static assets is the only output produced by Create React App. - -However this is not quite enough if you use client-side routing. Read the next section if you want to support URLs like `/todos/42` in your single-page app. - -## Serving Apps with Client-Side Routing - -If you use routers that use the HTML5 [`pushState` history API](https://developer.mozilla.org/en-US/docs/Web/API/History_API#Adding_and_modifying_history_entries) under the hood (for example, [React Router](https://github.com/ReactTraining/react-router) with `browserHistory`), many static file servers will fail. For example, if you used React Router with a route for `/todos/42`, the development server will respond to `localhost:3000/todos/42` properly, but an Express serving a production build as above will not. - -This is because when there is a fresh page load for a `/todos/42`, the server looks for the file `build/todos/42` and does not find it. The server needs to be configured to respond to a request to `/todos/42` by serving `index.html`. For example, we can amend our Express example above to serve `index.html` for any unknown paths: - -```diff - app.use(express.static(path.join(__dirname, 'build'))); - --app.get('/', function (req, res) { -+app.get('/*', function (req, res) { - res.sendFile(path.join(__dirname, 'build', 'index.html')); - }); -``` - -If you’re using [Apache HTTP Server](https://httpd.apache.org/), you need to create a `.htaccess` file in the `public` folder that looks like this: - -``` - Options -MultiViews - RewriteEngine On - RewriteCond %{REQUEST_FILENAME} !-f - RewriteRule ^ index.html [QSA,L] -``` - -It will get copied to the `build` folder when you run `npm run build`. - -If you’re using [Apache Tomcat](http://tomcat.apache.org/), you need to follow [this Stack Overflow answer](https://stackoverflow.com/a/41249464/4878474). - -Now requests to `/todos/42` will be handled correctly both in development and in production. - -On a production build, and when you've [opted-in](making-a-progressive-web-app.md#why-opt-in), -a [service worker](https://developers.google.com/web/fundamentals/primers/service-workers/) will automatically handle all navigation requests, like for -`/todos/42`, by serving the cached copy of your `index.html`. This -service worker navigation routing can be configured or disabled by -[`eject`ing](available-scripts.md#npm-run-eject) and then modifying the -[`navigateFallback`](https://github.com/GoogleChrome/sw-precache#navigatefallback-string) -and [`navigateFallbackWhitelist`](https://github.com/GoogleChrome/sw-precache#navigatefallbackwhitelist-arrayregexp) -options of the `SWPreachePlugin` [configuration](../config/webpack.config.prod.js). - -When users install your app to the homescreen of their device the default configuration will make a shortcut to `/index.html`. This may not work for client-side routers which expect the app to be served from `/`. Edit the web app manifest at [`public/manifest.json`](public/manifest.json) and change `start_url` to match the required URL scheme, for example: - -```js - "start_url": ".", -``` - -## Building for Relative Paths - -By default, Create React App produces a build assuming your app is hosted at the server root.
-To override this, specify the `homepage` in your `package.json`, for example: - -```js - "homepage": "http://mywebsite.com/relativepath", -``` - -This will let Create React App correctly infer the root path to use in the generated HTML file. - -**Note**: If you are using `react-router@^4`, you can root ``s using the `basename` prop on any ``.
-More information [here](https://reacttraining.com/react-router/web/api/BrowserRouter/basename-string).
-
-For example: - -```js - - // renders -``` - -### Serving the Same Build from Different Paths - -> Note: this feature is available with `react-scripts@0.9.0` and higher. - -If you are not using the HTML5 `pushState` history API or not using client-side routing at all, it is unnecessary to specify the URL from which your app will be served. Instead, you can put this in your `package.json`: - -```js - "homepage": ".", -``` - -This will make sure that all the asset paths are relative to `index.html`. You will then be able to move your app from `http://mywebsite.com` to `http://mywebsite.com/relativepath` or even `http://mywebsite.com/relative/path` without having to rebuild it. - -## Customizing Environment Variables for Arbitrary Build Environments - -You can create an arbitrary build environment by creating a custom `.env` file and loading it using [env-cmd](https://www.npmjs.com/package/env-cmd). - -For example, to create a build environment for a staging environment: - -1. Create a file called `.env.staging` -1. Set environment variables as you would any other `.env` file (e.g. `REACT_APP_API_URL=http://api-staging.example.com`) -1. Install [env-cmd](https://www.npmjs.com/package/env-cmd) - ```sh - $ npm install env-cmd --save - $ # or - $ yarn add env-cmd - ``` -1. Add a new script to your `package.json`, building with your new environment: - ```json - { - "scripts": { - "build:staging": "env-cmd .env.staging npm run build" - } - } - ``` - -Now you can run `npm run build:staging` to build with the staging environment config. -You can specify other environments in the same way. - -Variables in `.env.production` will be used as fallback because `NODE_ENV` will always be set to `production` for a build. - -## [Azure](https://azure.microsoft.com/) - -See [this](https://medium.com/@to_pe/deploying-create-react-app-on-microsoft-azure-c0f6686a4321) blog post on how to deploy your React app to Microsoft Azure. - -See [this](https://medium.com/@strid/host-create-react-app-on-azure-986bc40d5bf2#.pycfnafbg) blog post or [this](https://github.com/ulrikaugustsson/azure-appservice-static) repo for a way to use automatic deployment to Azure App Service. - -## [Firebase](https://firebase.google.com/) - -Install the Firebase CLI if you haven’t already by running `npm install -g firebase-tools`. Sign up for a [Firebase account](https://console.firebase.google.com/) and create a new project. Run `firebase login` and login with your previous created Firebase account. - -Then run the `firebase init` command from your project’s root. You need to choose the **Hosting: Configure and deploy Firebase Hosting sites** and choose the Firebase project you created in the previous step. You will need to agree with `database.rules.json` being created, choose `build` as the public directory, and also agree to **Configure as a single-page app** by replying with `y`. - -```sh - === Project Setup - - First, let's associate this project directory with a Firebase project. - You can create multiple project aliases by running firebase use --add, - but for now we'll just set up a default project. - - ? What Firebase project do you want to associate as default? Example app (example-app-fd690) - - === Database Setup - - Firebase Realtime Database Rules allow you to define how your data should be - structured and when your data can be read from and written to. - - ? What file should be used for Database Rules? database.rules.json - ✔ Database Rules for example-app-fd690 have been downloaded to database.rules.json. - Future modifications to database.rules.json will update Database Rules when you run - firebase deploy. - - === Hosting Setup - - Your public directory is the folder (relative to your project directory) that - will contain Hosting assets to uploaded with firebase deploy. If you - have a build process for your assets, use your build's output directory. - - ? What do you want to use as your public directory? build - ? Configure as a single-page app (rewrite all urls to /index.html)? Yes - ✔ Wrote build/index.html - - i Writing configuration info to firebase.json... - i Writing project information to .firebaserc... - - ✔ Firebase initialization complete! -``` - -IMPORTANT: you need to set proper HTTP caching headers for `service-worker.js` file in `firebase.json` file or you will not be able to see changes after first deployment ([issue #2440](https://github.com/facebook/create-react-app/issues/2440)). It should be added inside `"hosting"` key like next: - -``` -{ - "hosting": { - ... - "headers": [ - {"source": "/service-worker.js", "headers": [{"key": "Cache-Control", "value": "no-cache"}]} - ] - ... -``` - -Now, after you create a production build with `npm run build`, you can deploy it by running `firebase deploy`. - -```sh - === Deploying to 'example-app-fd690'... - - i deploying database, hosting - ✔ database: rules ready to deploy. - i hosting: preparing build directory for upload... - Uploading: [============================== ] 75%✔ hosting: build folder uploaded successfully - ✔ hosting: 8 files uploaded successfully - i starting release process (may take several minutes)... - - ✔ Deploy complete! - - Project Console: https://console.firebase.google.com/project/example-app-fd690/overview - Hosting URL: https://example-app-fd690.firebaseapp.com -``` - -For more information see [Firebase Hosting](https://firebase.google.com/docs/hosting). - -## [GitHub Pages](https://pages.github.com/) - -> Note: this feature is available with `react-scripts@0.2.0` and higher. - -### Step 1: Add `homepage` to `package.json` - -**The step below is important!**
-**If you skip it, your app will not deploy correctly.** - -Open your `package.json` and add a `homepage` field for your project: - -```json - "homepage": "https://myusername.github.io/my-app", -``` - -or for a GitHub user page: - -```json - "homepage": "https://myusername.github.io", -``` - -or for a custom domain page: - -```json - "homepage": "https://mywebsite.com", -``` - -Create React App uses the `homepage` field to determine the root URL in the built HTML file. - -### 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. - -To publish it at [https://myusername.github.io/my-app](https://myusername.github.io/my-app), run: - -```sh -npm install --save gh-pages -``` - -Alternatively you may use `yarn`: - -```sh -yarn add gh-pages -``` - -Add the following scripts in your `package.json`: - -```diff - "scripts": { -+ "predeploy": "npm run build", -+ "deploy": "gh-pages -d build", - "start": "react-scripts start", - "build": "react-scripts build", -``` - -The `predeploy` script will run automatically before `deploy` is run. - -If you are deploying to a GitHub user page instead of a project page you'll need to make two -additional modifications: - -1. First, change your repository's source branch to be any branch other than **master**. -1. Additionally, tweak your `package.json` scripts to push deployments to **master**: - -```diff - "scripts": { - "predeploy": "npm run build", -- "deploy": "gh-pages -d build", -+ "deploy": "gh-pages -b master -d build", -``` - -### Step 3: Deploy the site by running `npm run deploy` - -Then run: - -```sh -npm run deploy -``` - -### 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. - -Your CNAME file should look like this: - -``` -mywebsite.com -``` - -### 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://reacttraining.com/react-router/web/api/Router) 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). - -### Troubleshooting - -#### "/dev/tty: No such a device or address" - -If, when deploying, you get `/dev/tty: No such a device or address` or a similar error, try the following: - -1. Create a new [Personal Access Token](https://github.com/settings/tokens) -2. `git remote set-url origin https://:@github.com//` . -3. Try `npm run deploy` again - -#### "Cannot read property 'email' of null" - -If, when deploying, you get `Cannot read property 'email' of null`, try the following: - -1. `git config --global user.name ''` -2. `git config --global user.email ''` -3. Try `npm run deploy` again - -## [Heroku](https://www.heroku.com/) - -Use the [Heroku Buildpack for Create React App](https://github.com/mars/create-react-app-buildpack).
-You can find instructions in [Deploying React with Zero Configuration](https://blog.heroku.com/deploying-react-with-zero-configuration). - -### Resolving Heroku Deployment Errors - -Sometimes `npm run build` works locally but fails during deploy via Heroku. Following are the most common cases. - -#### "Module not found: Error: Cannot resolve 'file' or 'directory'" - -If you get something like this: - -``` -remote: Failed to create a production build. Reason: -remote: Module not found: Error: Cannot resolve 'file' or 'directory' -MyDirectory in /tmp/build_1234/src -``` - -It means you need to ensure that the lettercase of the file or directory you `import` matches the one you see on your filesystem or on GitHub. - -This is important because Linux (the operating system used by Heroku) is case sensitive. So `MyDirectory` and `mydirectory` are two distinct directories and thus, even though the project builds locally, the difference in case breaks the `import` statements on Heroku remotes. - -#### "Could not find a required file." - -If you exclude or ignore necessary files from the package you will see a error similar this one: - -``` -remote: Could not find a required file. -remote: Name: `index.html` -remote: Searched in: /tmp/build_a2875fc163b209225122d68916f1d4df/public -remote: -remote: npm ERR! Linux 3.13.0-105-generic -remote: npm ERR! argv "/tmp/build_a2875fc163b209225122d68916f1d4df/.heroku/node/bin/node" "/tmp/build_a2875fc163b209225122d68916f1d4df/.heroku/node/bin/npm" "run" "build" -``` - -In this case, ensure that the file is there with the proper lettercase and that’s not ignored on your local `.gitignore` or `~/.gitignore_global`. - -## [Netlify](https://www.netlify.com/) - -**To do a manual deploy to Netlify’s CDN:** - -```sh -npm install netlify-cli -g -netlify deploy -``` - -Choose `build` as the path to deploy. - -**To setup continuous delivery:** - -With this setup Netlify will build and deploy when you push to git or open a pull request: - -1. [Start a new netlify project](https://app.netlify.com/signup) -2. Pick your Git hosting service and select your repository -3. Click `Build your site` - -**Support for client-side routing:** - -To support `pushState`, make sure to create a `public/_redirects` file with the following rewrite rules: - -``` -/* /index.html 200 -``` - -When you build the project, Create React App will place the `public` folder contents into the build output. - -## [Now](https://zeit.co/now) - -Now offers a zero-configuration single-command deployment. You can use `now` to deploy your app for free. - -1. Install the `now` command-line tool either via the recommended [desktop tool](https://zeit.co/download) or via node with `npm install -g now`. - -2. Build your app by running `npm run build`. - -3. Move into the build directory by running `cd build`. - -4. Run `now --name your-project-name` from within the build directory. You will see a **now.sh** URL in your output like this: - - ``` - > Ready! https://your-project-name-tpspyhtdtk.now.sh (copied to clipboard) - ``` - - Paste that URL into your browser when the build is complete, and you will see your deployed app. - -Details are available in [this article.](https://zeit.co/blog/unlimited-static) - -## [S3](https://aws.amazon.com/s3) and [CloudFront](https://aws.amazon.com/cloudfront/) - -See this [blog post](https://medium.com/@omgwtfmarc/deploying-create-react-app-to-s3-or-cloudfront-48dae4ce0af) on how to deploy your React app to Amazon Web Services S3 and CloudFront. - -## [Surge](https://surge.sh/) - -Install the Surge CLI if you haven’t already by running `npm install -g surge`. Run the `surge` command and log in you or create a new account. - -When asked about the project path, make sure to specify the `build` folder, for example: - -```sh - project path: /path/to/project/build -``` - -Note that in order to support routers that use HTML5 `pushState` API, you may want to rename the `index.html` in your build folder to `200.html` before deploying to Surge. This [ensures that every URL falls back to that file](https://surge.sh/help/adding-a-200-page-for-client-side-routing). - -## Publishing Components To npm - -Create React App doesn't provide any built-in functionality to publish a component to npm. If you're ready to extract a component from your project so other people can use it, we recommend moving it to a separate directory outside of your project and then using a tool like [nwb](https://github.com/insin/nwb#react-components-and-libraries) to prepare it for publishing. +--- +id: deployment +title: Deployment +sidebar_label: Deployment +--- + +`npm run build` creates a `build` directory with a production build of your app. Set up your favorite HTTP server so that a visitor to your site is served `index.html`, and requests to static paths like `/static/js/main..js` are served with the contents of the `/static/js/main..js` file. For more information see the [production build](production-build.md) section. + +## Static Server + +For environments using [Node](https://nodejs.org/), the easiest way to handle this would be to install [serve](https://github.com/zeit/serve) and let it handle the rest: + +```sh +npm install -g serve +serve -s build +``` + +The last command shown above will serve your static site on the port **5000**. Like many of [serve](https://github.com/zeit/serve)’s internal settings, the port can be adjusted using the `-p` or `--port` flags. + +Run this command to get a full list of the options available: + +```sh +serve -h +``` + +## Other Solutions + +You don’t necessarily need a static server in order to run a Create React App project in production. It works just as fine integrated into an existing dynamic one. + +Here’s a programmatic example using [Node](https://nodejs.org/) and [Express](http://expressjs.com/): + +```javascript +const express = require('express'); +const path = require('path'); +const app = express(); + +app.use(express.static(path.join(__dirname, 'build'))); + +app.get('/', function(req, res) { + res.sendFile(path.join(__dirname, 'build', 'index.html')); +}); + +app.listen(9000); +``` + +The choice of your server software isn’t important either. Since Create React App is completely platform-agnostic, there’s no need to explicitly use Node. + +The `build` folder with static assets is the only output produced by Create React App. + +However this is not quite enough if you use client-side routing. Read the next section if you want to support URLs like `/todos/42` in your single-page app. + +## Serving Apps with Client-Side Routing + +If you use routers that use the HTML5 [`pushState` history API](https://developer.mozilla.org/en-US/docs/Web/API/History_API#Adding_and_modifying_history_entries) under the hood (for example, [React Router](https://github.com/ReactTraining/react-router) with `browserHistory`), many static file servers will fail. For example, if you used React Router with a route for `/todos/42`, the development server will respond to `localhost:3000/todos/42` properly, but an Express serving a production build as above will not. + +This is because when there is a fresh page load for a `/todos/42`, the server looks for the file `build/todos/42` and does not find it. The server needs to be configured to respond to a request to `/todos/42` by serving `index.html`. For example, we can amend our Express example above to serve `index.html` for any unknown paths: + +```diff + app.use(express.static(path.join(__dirname, 'build'))); + +-app.get('/', function (req, res) { ++app.get('/*', function (req, res) { + res.sendFile(path.join(__dirname, 'build', 'index.html')); + }); +``` + +If you’re using [Apache HTTP Server](https://httpd.apache.org/), you need to create a `.htaccess` file in the `public` folder that looks like this: + +``` + Options -MultiViews + RewriteEngine On + RewriteCond %{REQUEST_FILENAME} !-f + RewriteRule ^ index.html [QSA,L] +``` + +It will get copied to the `build` folder when you run `npm run build`. + +If you’re using [Apache Tomcat](http://tomcat.apache.org/), you need to follow [this Stack Overflow answer](https://stackoverflow.com/a/41249464/4878474). + +Now requests to `/todos/42` will be handled correctly both in development and in production. + +On a production build, and when you've [opted-in](making-a-progressive-web-app.md#why-opt-in), +a [service worker](https://developers.google.com/web/fundamentals/primers/service-workers/) will automatically handle all navigation requests, like for +`/todos/42`, by serving the cached copy of your `index.html`. This +service worker navigation routing can be configured or disabled by +[`eject`ing](available-scripts.md#npm-run-eject) and then modifying the +[`navigateFallback`](https://github.com/GoogleChrome/sw-precache#navigatefallback-string) +and [`navigateFallbackWhitelist`](https://github.com/GoogleChrome/sw-precache#navigatefallbackwhitelist-arrayregexp) +options of the `SWPreachePlugin` [configuration](../config/webpack.config.prod.js). + +When users install your app to the homescreen of their device the default configuration will make a shortcut to `/index.html`. This may not work for client-side routers which expect the app to be served from `/`. Edit the web app manifest at [`public/manifest.json`](public/manifest.json) and change `start_url` to match the required URL scheme, for example: + +```js + "start_url": ".", +``` + +## Building for Relative Paths + +By default, Create React App produces a build assuming your app is hosted at the server root.
+To override this, specify the `homepage` in your `package.json`, for example: + +```js + "homepage": "http://mywebsite.com/relativepath", +``` + +This will let Create React App correctly infer the root path to use in the generated HTML file. + +**Note**: If you are using `react-router@^4`, you can root ``s using the `basename` prop on any ``.
+More information [here](https://reacttraining.com/react-router/web/api/BrowserRouter/basename-string).
+
+For example: + +```js + + // renders +``` + +### Serving the Same Build from Different Paths + +> Note: this feature is available with `react-scripts@0.9.0` and higher. + +If you are not using the HTML5 `pushState` history API or not using client-side routing at all, it is unnecessary to specify the URL from which your app will be served. Instead, you can put this in your `package.json`: + +```js + "homepage": ".", +``` + +This will make sure that all the asset paths are relative to `index.html`. You will then be able to move your app from `http://mywebsite.com` to `http://mywebsite.com/relativepath` or even `http://mywebsite.com/relative/path` without having to rebuild it. + +## Customizing Environment Variables for Arbitrary Build Environments + +You can create an arbitrary build environment by creating a custom `.env` file and loading it using [env-cmd](https://www.npmjs.com/package/env-cmd). + +For example, to create a build environment for a staging environment: + +1. Create a file called `.env.staging` +1. Set environment variables as you would any other `.env` file (e.g. `REACT_APP_API_URL=http://api-staging.example.com`) +1. Install [env-cmd](https://www.npmjs.com/package/env-cmd) + ```sh + $ npm install env-cmd --save + $ # or + $ yarn add env-cmd + ``` +1. Add a new script to your `package.json`, building with your new environment: + ```json + { + "scripts": { + "build:staging": "env-cmd .env.staging npm run build" + } + } + ``` + +Now you can run `npm run build:staging` to build with the staging environment config. +You can specify other environments in the same way. + +Variables in `.env.production` will be used as fallback because `NODE_ENV` will always be set to `production` for a build. + +## [Azure](https://azure.microsoft.com/) + +See [this](https://medium.com/@to_pe/deploying-create-react-app-on-microsoft-azure-c0f6686a4321) blog post on how to deploy your React app to Microsoft Azure. + +See [this](https://medium.com/@strid/host-create-react-app-on-azure-986bc40d5bf2#.pycfnafbg) blog post or [this](https://github.com/ulrikaugustsson/azure-appservice-static) repo for a way to use automatic deployment to Azure App Service. + +## [Firebase](https://firebase.google.com/) + +Install the Firebase CLI if you haven’t already by running `npm install -g firebase-tools`. Sign up for a [Firebase account](https://console.firebase.google.com/) and create a new project. Run `firebase login` and login with your previous created Firebase account. + +Then run the `firebase init` command from your project’s root. You need to choose the **Hosting: Configure and deploy Firebase Hosting sites** and choose the Firebase project you created in the previous step. You will need to agree with `database.rules.json` being created, choose `build` as the public directory, and also agree to **Configure as a single-page app** by replying with `y`. + +```sh + === Project Setup + + First, let's associate this project directory with a Firebase project. + You can create multiple project aliases by running firebase use --add, + but for now we'll just set up a default project. + + ? What Firebase project do you want to associate as default? Example app (example-app-fd690) + + === Database Setup + + Firebase Realtime Database Rules allow you to define how your data should be + structured and when your data can be read from and written to. + + ? What file should be used for Database Rules? database.rules.json + ✔ Database Rules for example-app-fd690 have been downloaded to database.rules.json. + Future modifications to database.rules.json will update Database Rules when you run + firebase deploy. + + === Hosting Setup + + Your public directory is the folder (relative to your project directory) that + will contain Hosting assets to uploaded with firebase deploy. If you + have a build process for your assets, use your build's output directory. + + ? What do you want to use as your public directory? build + ? Configure as a single-page app (rewrite all urls to /index.html)? Yes + ✔ Wrote build/index.html + + i Writing configuration info to firebase.json... + i Writing project information to .firebaserc... + + ✔ Firebase initialization complete! +``` + +IMPORTANT: you need to set proper HTTP caching headers for `service-worker.js` file in `firebase.json` file or you will not be able to see changes after first deployment ([issue #2440](https://github.com/facebook/create-react-app/issues/2440)). It should be added inside `"hosting"` key like next: + +``` +{ + "hosting": { + ... + "headers": [ + {"source": "/service-worker.js", "headers": [{"key": "Cache-Control", "value": "no-cache"}]} + ] + ... +``` + +Now, after you create a production build with `npm run build`, you can deploy it by running `firebase deploy`. + +```sh + === Deploying to 'example-app-fd690'... + + i deploying database, hosting + ✔ database: rules ready to deploy. + i hosting: preparing build directory for upload... + Uploading: [============================== ] 75%✔ hosting: build folder uploaded successfully + ✔ hosting: 8 files uploaded successfully + i starting release process (may take several minutes)... + + ✔ Deploy complete! + + Project Console: https://console.firebase.google.com/project/example-app-fd690/overview + Hosting URL: https://example-app-fd690.firebaseapp.com +``` + +For more information see [Firebase Hosting](https://firebase.google.com/docs/hosting). + +## [GitHub Pages](https://pages.github.com/) + +> Note: this feature is available with `react-scripts@0.2.0` and higher. + +### Step 1: Add `homepage` to `package.json` + +**The step below is important!**
+**If you skip it, your app will not deploy correctly.** + +Open your `package.json` and add a `homepage` field for your project: + +```json + "homepage": "https://myusername.github.io/my-app", +``` + +or for a GitHub user page: + +```json + "homepage": "https://myusername.github.io", +``` + +or for a custom domain page: + +```json + "homepage": "https://mywebsite.com", +``` + +Create React App uses the `homepage` field to determine the root URL in the built HTML file. + +### 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. + +To publish it at [https://myusername.github.io/my-app](https://myusername.github.io/my-app), run: + +```sh +npm install --save gh-pages +``` + +Alternatively you may use `yarn`: + +```sh +yarn add gh-pages +``` + +Add the following scripts in your `package.json`: + +```diff + "scripts": { ++ "predeploy": "npm run build", ++ "deploy": "gh-pages -d build", + "start": "react-scripts start", + "build": "react-scripts build", +``` + +The `predeploy` script will run automatically before `deploy` is run. + +If you are deploying to a GitHub user page instead of a project page you'll need to make two +additional modifications: + +1. First, change your repository's source branch to be any branch other than **master**. +1. Additionally, tweak your `package.json` scripts to push deployments to **master**: + +```diff + "scripts": { + "predeploy": "npm run build", +- "deploy": "gh-pages -d build", ++ "deploy": "gh-pages -b master -d build", +``` + +### Step 3: Deploy the site by running `npm run deploy` + +Then run: + +```sh +npm run deploy +``` + +### 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. + +Your CNAME file should look like this: + +``` +mywebsite.com +``` + +### 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://reacttraining.com/react-router/web/api/Router) 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). + +### Troubleshooting + +#### "/dev/tty: No such a device or address" + +If, when deploying, you get `/dev/tty: No such a device or address` or a similar error, try the following: + +1. Create a new [Personal Access Token](https://github.com/settings/tokens) +2. `git remote set-url origin https://:@github.com//` . +3. Try `npm run deploy` again + +#### "Cannot read property 'email' of null" + +If, when deploying, you get `Cannot read property 'email' of null`, try the following: + +1. `git config --global user.name ''` +2. `git config --global user.email ''` +3. Try `npm run deploy` again + +## [Heroku](https://www.heroku.com/) + +Use the [Heroku Buildpack for Create React App](https://github.com/mars/create-react-app-buildpack).
+You can find instructions in [Deploying React with Zero Configuration](https://blog.heroku.com/deploying-react-with-zero-configuration). + +### Resolving Heroku Deployment Errors + +Sometimes `npm run build` works locally but fails during deploy via Heroku. Following are the most common cases. + +#### "Module not found: Error: Cannot resolve 'file' or 'directory'" + +If you get something like this: + +``` +remote: Failed to create a production build. Reason: +remote: Module not found: Error: Cannot resolve 'file' or 'directory' +MyDirectory in /tmp/build_1234/src +``` + +It means you need to ensure that the lettercase of the file or directory you `import` matches the one you see on your filesystem or on GitHub. + +This is important because Linux (the operating system used by Heroku) is case sensitive. So `MyDirectory` and `mydirectory` are two distinct directories and thus, even though the project builds locally, the difference in case breaks the `import` statements on Heroku remotes. + +#### "Could not find a required file." + +If you exclude or ignore necessary files from the package you will see a error similar this one: + +``` +remote: Could not find a required file. +remote: Name: `index.html` +remote: Searched in: /tmp/build_a2875fc163b209225122d68916f1d4df/public +remote: +remote: npm ERR! Linux 3.13.0-105-generic +remote: npm ERR! argv "/tmp/build_a2875fc163b209225122d68916f1d4df/.heroku/node/bin/node" "/tmp/build_a2875fc163b209225122d68916f1d4df/.heroku/node/bin/npm" "run" "build" +``` + +In this case, ensure that the file is there with the proper lettercase and that’s not ignored on your local `.gitignore` or `~/.gitignore_global`. + +## [Netlify](https://www.netlify.com/) + +**To do a manual deploy to Netlify’s CDN:** + +```sh +npm install netlify-cli -g +netlify deploy +``` + +Choose `build` as the path to deploy. + +**To setup continuous delivery:** + +With this setup Netlify will build and deploy when you push to git or open a pull request: + +1. [Start a new netlify project](https://app.netlify.com/signup) +2. Pick your Git hosting service and select your repository +3. Click `Build your site` + +**Support for client-side routing:** + +To support `pushState`, make sure to create a `public/_redirects` file with the following rewrite rules: + +``` +/* /index.html 200 +``` + +When you build the project, Create React App will place the `public` folder contents into the build output. + +## [Now](https://zeit.co/now) + +Now offers a zero-configuration single-command deployment. You can use `now` to deploy your app for free. + +1. Install the `now` command-line tool either via the recommended [desktop tool](https://zeit.co/download) or via node with `npm install -g now`. + +2. Build your app by running `npm run build`. + +3. Move into the build directory by running `cd build`. + +4. Run `now --name your-project-name` from within the build directory. You will see a **now.sh** URL in your output like this: + + ``` + > Ready! https://your-project-name-tpspyhtdtk.now.sh (copied to clipboard) + ``` + + Paste that URL into your browser when the build is complete, and you will see your deployed app. + +Details are available in [this article.](https://zeit.co/blog/unlimited-static) + +## [S3](https://aws.amazon.com/s3) and [CloudFront](https://aws.amazon.com/cloudfront/) + +See this [blog post](https://medium.com/@omgwtfmarc/deploying-create-react-app-to-s3-or-cloudfront-48dae4ce0af) on how to deploy your React app to Amazon Web Services S3 and CloudFront. + +## [Surge](https://surge.sh/) + +Install the Surge CLI if you haven’t already by running `npm install -g surge`. Run the `surge` command and log in you or create a new account. + +When asked about the project path, make sure to specify the `build` folder, for example: + +```sh + project path: /path/to/project/build +``` + +Note that in order to support routers that use HTML5 `pushState` API, you may want to rename the `index.html` in your build folder to `200.html` before deploying to Surge. This [ensures that every URL falls back to that file](https://surge.sh/help/adding-a-200-page-for-client-side-routing). + +## Publishing Components To npm + +Create React App doesn't provide any built-in functionality to publish a component to npm. If you're ready to extract a component from your project so other people can use it, we recommend moving it to a separate directory outside of your project and then using a tool like [nwb](https://github.com/insin/nwb#react-components-and-libraries) to prepare it for publishing. diff --git a/docusaurus/docs/production-build.md b/docusaurus/docs/production-build.md new file mode 100644 index 00000000000..f57e5a9b959 --- /dev/null +++ b/docusaurus/docs/production-build.md @@ -0,0 +1,30 @@ +--- +id: production-build +title: Creating a Production Build +--- + +`npm run build` creates a `build` directory with a production build of your app. Inside the `build/static` directory will be your JavaScript and CSS files. Each filename inside of `build/static` will contain a unique hash of the file contents. This hash in the file name enables [long term caching techniques](#static-file-caching). + +When running a production build of freshly created Create React App application, there are 3 `.js` files (called _chunks_) that are generated and placed in the `build/static/js` directory: + +`main.[hash].chunk.js` + +- This is your _application_ code. `App.js`, etc. + +`1.[hash].chunk.js` + +- This is your _vendor_ code, which includes modules you've imported from within `node_modules`. One of the potential advantages with splitting your _vendor_ and _application_ code is to enable [long term caching techniques](#static-file-caching) to improve application loading performance. Since _vendor_ code tends to change less often than the actual _application_ code, the browser will be able to cache them separately, and won't re-download them each time the app code changes. + +`runtime~main.[hash].js` + +- This is a small chunk of [webpack runtime](https://webpack.js.org/configuration/optimization/#optimization-runtimechunk) logic which is used to load and run your application. The contents of this will be embedded in your `build/index.html` file by default to save an additional network request. You can opt out of this by specifying `INLINE_RUNTIME_CHUNK=false` as documented in our [advanced configuration](advanced-configuration.md), which will load this chunk instead of embedding it in your `index.html`. + +If you're using [code splitting](code-splitting.md) to split up your application, this will create additional chunks in the `build/static` folder as well. + +## Static File Caching + +Each file inside of the `build/static` directory will have a unique hash appended to the filename that is generated based on the contents of the file, which allows you to use [aggressive caching techniques](https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/http-caching#invalidating_and_updating_cached_responses) to avoid the browser re-downloading your assets if the file contents haven't changed. If the contents of a file changes in a subsequent build, the filename hash that is generated will be different. + +To deliver the best performance to your users, it's best practice to specify a `Cache-Control` header for `index.html`, as well as the files within `build/static`. This header allows you to control the length of time that the browser as well as CDNs will cache your static assets. If you aren't familiar with what `Cache-Control` does, see [this article](https://jakearchibald.com/2016/caching-best-practices/) for a great introduction. + +Using `Cache-Control: max-age=31536000` for your `build/static` assets, and `Cache-Control: no-cache` for everything else is a safe and effective starting point that ensures your user's browser will always check for an updated `index.html` file, and will cache all of the `build/static` files for one year. Note that you can use the one year expiration on `build/static` safely because the file contents hash is embedded into the filename. diff --git a/docusaurus/docs/running-tests.md b/docusaurus/docs/running-tests.md index a5dbdbb2580..6daaffb73aa 100644 --- a/docusaurus/docs/running-tests.md +++ b/docusaurus/docs/running-tests.md @@ -5,7 +5,7 @@ title: Running Tests > Note: this feature is available with `react-scripts@0.3.0` and higher.
-> [Read the migration guide to learn how to enable it in older projects!](https://github.com/facebook/create-react-app/blob/master/CHANGELOG.md#migrating-from-023-to-030) +> [Read the migration guide to learn how to enable it in older projects!](https://github.com/facebook/create-react-app/blob/master/CHANGELOG-0.x.md#migrating-from-023-to-030) Create React App uses [Jest](https://facebook.github.io/jest/) as its test runner. To prepare for this integration, we did a [major revamp](https://facebook.github.io/jest/blog/2016/09/01/jest-15.html) of Jest so if you heard bad things about it years ago, give it another try. diff --git a/docusaurus/website/i18n/en.json b/docusaurus/website/i18n/en.json index 5df3cc56344..eec0d268f56 100644 --- a/docusaurus/website/i18n/en.json +++ b/docusaurus/website/i18n/en.json @@ -104,6 +104,9 @@ "title": "Pre-Rendering into Static HTML Files", "sidebar_label": "Pre-Rendering Static HTML" }, + "production-build": { + "title": "Creating a Production Build" + }, "proxying-api-requests-in-development": { "title": "Proxying API Requests in Development", "sidebar_label": "Proxying in Development" @@ -142,7 +145,7 @@ } }, "links": { - "Getting Started": "Getting Started", + "Docs": "Docs", "Help": "Help", "GitHub": "GitHub" }, diff --git a/docusaurus/website/sidebars.json b/docusaurus/website/sidebars.json index 219c14e82ab..bde33240766 100644 --- a/docusaurus/website/sidebars.json +++ b/docusaurus/website/sidebars.json @@ -1,8 +1,6 @@ { "docs": { - "Welcome": [ - "documentation-intro" - ], + "Welcome": ["documentation-intro"], "Getting Started": [ "getting-started", "folder-structure", @@ -35,7 +33,8 @@ "adding-relay", "adding-a-router", "adding-custom-environment-variables", - "making-a-progressive-web-app" + "making-a-progressive-web-app", + "production-build" ], "Testing": ["running-tests", "debugging-tests"], "Back-End Integration": [ @@ -51,8 +50,6 @@ "advanced-configuration", "alternatives-to-ejecting" ], - "Support": [ - "troubleshooting" - ] + "Support": ["troubleshooting"] } }