Add production build section to docs (#5900)

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`
 

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.
 

docusaurus/docs/deployment.md

@@ -4,7 +4,7 @@ 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.<hash>.js` are served with the contents of the `/static/js/main.<hash>.js` file.
+`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.<hash>.js` are served with the contents of the `/static/js/main.<hash>.js` file. For more information see the [production build](production-build.md) section.
 
 ## Static Server
 

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.

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.<br>
 
-> [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.
 

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"
     },

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"]
   }
 }