Merge branch 'facebook'

Author: Jeremy Moore

.gitignore

@@ -11,3 +11,4 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 /.changelog
+.npm/

CHANGELOG.md

@@ -142,7 +142,9 @@ By default git would use `CRLF` line endings which would cause the scripts to fa
 9. Wait for a long time, and it will get published. Don’t worry that it’s stuck. In the end the publish script will prompt for versions before publishing the packages.
 10. After publishing, create a GitHub Release with the same text as the changelog entry. See previous Releases for inspiration.
 
-Make sure to test the released version! If you want to be extra careful, you can publish a prerelease by running `npm run publish -- --tag next` instead of `npm run publish`.
+Make sure to test the released version! If you want to be extra careful, you can publish a prerelease by running `npm run publish -- --npm-tag=next` instead of `npm run publish`.
+
+Optionally, you can cut a prerelease instead by running `npm run publish -- --canary=next --exact --cd-version patch --npm-tag=next`.
 
 ---
 

CONTRIBUTING.md

@@ -34,7 +34,7 @@ Just create a project, and you’re good to go.
 
 ## Creating an App
 
-**You’ll need to have Node 8.9.0 or later on your local development machine** (but it’s not required on the server). You can use [nvm](https://github.com/creationix/nvm#installation) (macOS/Linux) or [nvm-windows](https://github.com/coreybutler/nvm-windows#node-version-manager-nvm-for-windows) to easily switch Node versions between different projects.
+**You’ll need to have Node 8.10.0 or later on your local development machine** (but it’s not required on the server). You can use [nvm](https://github.com/creationix/nvm#installation) (macOS/Linux) or [nvm-windows](https://github.com/coreybutler/nvm-windows#node-version-manager-nvm-for-windows) to easily switch Node versions between different projects.
 
 To create a new app, you may choose one of the following methods:
 

README.md

@@ -8,7 +8,7 @@ sidebar_label: Adding CSS Modules
 
 This project supports [CSS Modules](https://github.com/css-modules/css-modules) alongside regular stylesheets using the `[name].module.css` file naming convention. CSS Modules allows the scoping of CSS by automatically creating a unique classname of the format `[filename]\_[classname]\_\_[hash]`.
 
-> **Tip:** Should you want to preprocess a stylesheet with Sass then make sure to [follow the installation instructions](/docs/adding-a-sass-stylesheet) and then change the stylesheet file extension as follows: `[name].module.scss` or `[name].module.sass`.
+> **Tip:** Should you want to preprocess a stylesheet with Sass then make sure to [follow the installation instructions](adding-a-sass-stylesheet.md) and then change the stylesheet file extension as follows: `[name].module.scss` or `[name].module.sass`.
 
 CSS Modules let you use the same CSS class name in different files without worrying about naming clashes. Learn more about CSS Modules [here](https://css-tricks.com/css-modules-part-1-need/).
 

docusaurus/docs/adding-a-css-modules-stylesheet.md

@@ -19,4 +19,4 @@ yarn add react-router-dom
 
 To try it, delete all the code in `src/App.js` and replace it with any of the examples on its website. The [Basic Example](https://reacttraining.com/react-router/web/example/basic) is a good place to get started.
 
-Note that [you may need to configure your production server to support client-side routing](/docs/deployments#serving-apps-with-client-side-routing) before deploying your app.
+Note that [you may need to configure your production server to support client-side routing](deployment.md#serving-apps-with-client-side-routing) before deploying your app.

docusaurus/docs/adding-a-router.md

@@ -30,7 +30,7 @@ This will allow you to do imports like
 @import '~nprogress/nprogress'; // importing a css file from the nprogress node module
 ```
 
-> **Tip:** You can opt into using this feature with [CSS modules](/docs/adding-a-css-modules-stylesheet) too!
+> **Tip:** You can opt into using this feature with [CSS modules](adding-a-css-modules-stylesheet.md) too!
 
 > **Note:** You must prefix imports from `node_modules` with `~` as displayed above.
 

docusaurus/docs/adding-a-sass-stylesheet.md

@@ -3,13 +3,14 @@ id: adding-custom-environment-variables
 title: Adding Custom Environment Variables
 sidebar_label: Environment Variables
 ---
+
 > Note: this feature is available with `[email protected]` and higher.
 
 Your project can consume variables declared in your environment as if they were declared locally in your JS files. By
 default you will have `NODE_ENV` defined for you, and any other environment variables starting with
 `REACT_APP_`.
 
-**The environment variables are embedded during the build time**. Since Create React App produces a static HTML/CSS/JS bundle, it can’t possibly read them at runtime. To read them at runtime, you would need to load HTML into memory on the server and replace placeholders in runtime, just like [described here](/docs/injecting-data-from-the-server-into-the-page). Alternatively you can rebuild the app on the server anytime you change them.
+**The environment variables are embedded during the build time**. Since Create React App produces a static HTML/CSS/JS bundle, it can’t possibly read them at runtime. To read them at runtime, you would need to load HTML into memory on the server and replace placeholders in runtime, just like [described here](title-and-meta-tags.md#injecting-data-from-the-server-into-the-page). Alternatively you can rebuild the app on the server anytime you change them.
 
 > Note: You must create custom environment variables beginning with `REACT_APP_`. Any other variables except `NODE_ENV` will be ignored to avoid accidentally [exposing a private key on the machine that could have the same name](https://github.com/facebook/create-react-app/issues/865#issuecomment-252199527). Changing any environment variables will require you to restart the development server if it is running.
 
@@ -77,7 +78,7 @@ You can also access the environment variables starting with `REACT_APP_` in the
 Note that the caveats from the above section apply:
 
 - Apart from a few built-in variables (`NODE_ENV` and `PUBLIC_URL`), variable names must start with `REACT_APP_` to work.
-- The environment variables are injected at build time. If you need to inject them at runtime, [follow this approach instead](/docs/generating-dynamic-meta-tags-on-the-server).
+- The environment variables are injected at build time. If you need to inject them at runtime, [follow this approach instead](title-and-meta-tags.md#generating-dynamic-meta-tags-on-the-server).
 
 ## Adding Temporary Environment Variables In Your Shell
 

docusaurus/docs/adding-custom-environment-variables.md

@@ -3,19 +3,29 @@ id: adding-typescript
 title: Adding TypeScript
 ---
 
-TypeScript is a typed superset of JavaScript that compiles to plain JavaScript.
+> Note: this feature is available with `[email protected]` and higher.
 
-Recent versions of [TypeScript](https://www.typescriptlang.org/) work with Create React App projects out of the box thanks to Babel 7. Note that Babel 7 TypeScript does not allow some features of TypeScript such as constant enum and namespaces.
+[TypeScript](https://www.typescriptlang.org/) is a typed superset of JavaScript that compiles to plain JavaScript.
 
-To add TypeScript to a Create React App project, follow these steps:
+To add [TypeScript](https://www.typescriptlang.org/) to a Create React App project, first install it:
 
-1. Run `npm install --save typescript @types/react @types/react-dom @types/jest` (or `yarn add typescript @types/react @types/react-dom @types/jest`).
-2. Rename the `.js` files you want to convert: use `.tsx` if they use JSX or `.ts` if not (e.g. `git mv src/index.js src/index.tsx`).
-3. Create a [`tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) at the root project directory with `{}` in it. Alternatively, rename `index.js` to `index.tsx`.
-4. Restart your development server (if applicable). This will set sensible defaults and the required values in your [`tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
+```bash
+$ npm install --save typescript @types/node @types/react @types/react-dom @types/jest
+$ # or
+$ yarn add typescript @types/node @types/react @types/react-dom @types/jest
+```
 
-Type errors will show up in the same console as the build one.
+Next, rename any file to be a TypeScript file (e.g. `src/index.js` to `src/index.tsx`) and **restart your development server**!
 
-We recommend using [VSCode](https://code.visualstudio.com/) for a better integrated experience.
+Type errors will show up in the same console as the build one.
 
 To learn more about TypeScript, check out [its documentation](https://www.typescriptlang.org/).
+
+> **Note:** You are not required to make a [`tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html), one will be made for you.
+> You are allowed to edit the generated TypeScript configuration.
+
+> **Note:** If you are currently using [create-react-app-typescript](https://github.com/wmonk/create-react-app-typescript/), see [this blog post](https://vincenttunru.com/migrate-create-react-app-typescript-to-create-react-app/) for instructions on how to migrate to Create React App.
+
+> **Note:** We recommend using [VSCode](https://code.visualstudio.com/) for a better integrated experience.
+
+> **Note:** Constant enums and namespaces are not supported.

docusaurus/docs/adding-typescript.md

@@ -3,15 +3,15 @@ id: advanced-configuration
 title: Advanced Configuration
 ---
 
-You can adjust various development and production settings by setting environment variables in your shell or with [.env](/docs/adding-development-environment-variables-in-env).
+You can adjust various development and production settings by setting environment variables in your shell or with [.env](adding-custom-environment-variables.md#adding-development-environment-variables-in-env).
 
 | Variable             | Development | Production | Usage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | :------------------- | :---------: | :--------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | BROWSER              |   ✅ Used   | 🚫 Ignored | By default, Create React App will open the default system browser, favoring Chrome on macOS. Specify a [browser](https://github.com/sindresorhus/opn#app) to override this behavior, or set it to `none` to disable it completely. If you need to customize the way the browser is launched, you can specify a node script instead. Any arguments passed to `npm start` will also be passed to this script, and the url where your app is served will be the last argument. Your script's file name must have the `.js` extension.                                                                                                                                       |
 | HOST                 |   ✅ Used   | 🚫 Ignored | By default, the development web server binds to `localhost`. You may use this variable to specify a different host.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | PORT                 |   ✅ Used   | 🚫 Ignored | By default, the development web server will attempt to listen on port 3000 or prompt you to attempt the next available port. You may use this variable to specify a different port.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | HTTPS                |   ✅ Used   | 🚫 Ignored | When set to `true`, Create React App will run the development server in `https` mode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| PUBLIC_URL           | 🚫 Ignored  |  ✅ Used   | Create React App assumes your application is hosted at the serving web server's root or a subpath as specified in [`package.json` (`homepage`)](/docs/deployment#building-for-relative-paths). Normally, Create React App ignores the hostname. You may use this variable to force assets to be referenced verbatim to the url you provide (hostname included). This may be particularly useful when using a CDN to host your application.                                                                                                                                                                                                                               |
+| PUBLIC_URL           | 🚫 Ignored  |  ✅ Used   | Create React App assumes your application is hosted at the serving web server's root or a subpath as specified in [`package.json` (`homepage`)](deployment#building-for-relative-paths). Normally, Create React App ignores the hostname. You may use this variable to force assets to be referenced verbatim to the url you provide (hostname included.md). This may be particularly useful when using a CDN to host your application.                                                                                                                                                                                                                                  |
 | CI                   |   ✅ Used   |  ✅ Used   | When set to `true`, Create React App treats warnings as failures in the build. It also makes the test runner non-watching. Most CIs set this flag by default.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | REACT_EDITOR         |   ✅ Used   | 🚫 Ignored | When an app crashes in development, you will see an error overlay with clickable stack trace. When you click on it, Create React App will try to determine the editor you are using based on currently running processes, and open the relevant source file. You can [send a pull request to detect your editor of choice](https://github.com/facebook/create-react-app/issues/2636). Setting this environment variable overrides the automatic detection. If you do it, make sure your systems [PATH](<https://en.wikipedia.org/wiki/PATH_(variable)>) environment variable points to your editor’s bin folder. You can also set it to `none` to disable it completely. |
 | CHOKIDAR_USEPOLLING  |   ✅ Used   | 🚫 Ignored | When set to `true`, the watcher runs in polling mode, as necessary inside a VM. Use this option if `npm start` isn't detecting changes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

docusaurus/docs/advanced-configuration.md

@@ -3,4 +3,4 @@ id: alternatives-to-ejecting
 title: Alternatives to Ejecting
 ---
 
-[Ejecting](/docs/available-scripts#npm-run-eject) lets you customize anything, but from that point on you have to maintain the configuration and scripts yourself. This can be daunting if you have many similar projects. In such cases instead of ejecting we recommend to _fork_ `react-scripts` and any other packages you need. [This article](https://auth0.com/blog/how-to-configure-create-react-app/) dives into how to do it in depth. You can find more discussion in [this issue](https://github.com/facebook/create-react-app/issues/682).
+[Ejecting](available-scripts.md#npm-run-eject) lets you customize anything, but from that point on you have to maintain the configuration and scripts yourself. This can be daunting if you have many similar projects. In such cases instead of ejecting we recommend to _fork_ `react-scripts` and any other packages you need. [This article](https://auth0.com/blog/how-to-configure-create-react-app/) dives into how to do it in depth. You can find more discussion in [this issue](https://github.com/facebook/create-react-app/issues/682.md).

docusaurus/docs/alternatives-to-ejecting.md

@@ -14,15 +14,15 @@ The page will reload if you make edits. You will also see any lint errors in the
 
 ## `npm test`
 
-Launches the test runner in the interactive watch mode. See the section about [running tests](/docs/running-tests) for more information.
+Launches the test runner in the interactive watch mode. See the section about [running tests](running-tests.md) for more information.
 
 ## `npm run build`
 
 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!
 
-See the section about [deployment](/docs/deployment) for more information.
+See the section about [deployment](deployment.md) for more information.
 
 ## `npm run eject`