Port documentation updates

gaearon · gaearon · commit a840d566835e · 2018-10-19T19:30:18.000-04:00
diff --git a/docusaurus/docs/adding-a-sass-stylesheet.md b/docusaurus/docs/adding-a-sass-stylesheet.md
@@ -33,3 +33,11 @@ This will allow you to do imports like
 > **Tip:** You can opt into using this feature with [CSS modules](/docs/adding-a-css-modules-stylesheet) too!
 
 > **Note:** You must prefix imports from `node_modules` with `~` as displayed above.
+
+> **Note:** If you're using Flow, add the following to your `.flowconfig` so it'll recognize the `.sass` or `.scss` imports.
+>
+> ```
+> [options]
+> module.file_ext=.sass
+> module.file_ext=.scss
+> ```
diff --git a/docusaurus/docs/advanced-configuration.md b/docusaurus/docs/advanced-configuration.md
diff --git a/docusaurus/docs/folder-structure.md b/docusaurus/docs/folder-structure.md
@@ -34,3 +34,5 @@ You may create subdirectories inside `src`. For faster rebuilds, only files insi
 Only files inside `public` can be used from `public/index.html`. Read instructions below for using assets from JavaScript and HTML.
 
 You can, however, create more top-level directories. They will not be included in the production build so you can use them for things like documentation.
+
+If you have Git installed and your project is not part of a larger repository, then a new repository will be initialized resulting in an additional top-level `.git` directory.
diff --git a/docusaurus/docs/making-a-progressive-web-app.md b/docusaurus/docs/making-a-progressive-web-app.md
@@ -10,7 +10,7 @@ the build process will generate a service worker file, but it will not be
 registered, so it will not take control of your production web app.
 
 In order to opt-in to the offline-first behavior, developers should look for the
-following in their [`src/index.js`](src/index.js) file:
+following in their [`src/index.js`](https://github.com/facebook/create-react-app/blob/master/packages/react-scripts/template/src/index.js) file:
 
 ```js
 // If you want your app to work offline and load faster, you can change
@@ -47,16 +47,32 @@ or unreliable network.
 If you do decide to opt-in to service worker registration, please take the
 following into account:
 
+1. After the initial caching is done, the [service worker lifecycle](https://developers.google.com/web/fundamentals/primers/service-workers/lifecycle)
+   controls when updated content ends up being shown to users. In order to guard against
+   [race conditions with lazy-loaded content](https://github.com/facebook/create-react-app/issues/3613#issuecomment-353467430),
+   the default behavior is to conservatively keep the updated service worker in the "[waiting](https://developers.google.com/web/fundamentals/primers/service-workers/lifecycle#waiting)"
+   state. This means that users will end up seeing older content until they close (reloading is not
+   enough) their existing, open tabs. See [this blog post](https://jeffy.info/2018/10/10/sw-in-c-r-a.html)
+   for more details about this behavior.
+
+1. Users aren't always familiar with offline-first web apps. It can be useful to
+   [let the user know](https://developers.google.com/web/fundamentals/instant-and-offline/offline-ux#inform_the_user_when_the_app_is_ready_for_offline_consumption)
+   when the service worker has finished populating your caches (showing a "This web
+   app works offline!" message) and also let them know when the service worker has
+   fetched the latest updates that will be available the next time they load the
+   page (showing a "New content is available once existing tabs are closed." message). Showing
+   this messages is currently left as an exercise to the developer, but as a
+   starting point, you can make use of the logic included in [`src/serviceWorker.js`](https://github.com/facebook/create-react-app/blob/master/packages/react-scripts/template/src/serviceWorker.js), which
+   demonstrates which service worker lifecycle events to listen for to detect each
+   scenario, and which as a default, just logs appropriate messages to the
+   JavaScript console.
+
 1. Service workers [require HTTPS](https://developers.google.com/web/fundamentals/getting-started/primers/service-workers#you_need_https),
    although to facilitate local testing, that policy
    [does not apply to `localhost`](http://stackoverflow.com/questions/34160509/options-for-testing-service-workers-via-http/34161385#34161385).
    If your production web server does not support HTTPS, then the service worker
    registration will fail, but the rest of your web app will remain functional.
 
-1. Service workers are [not supported](https://jakearchibald.github.io/isserviceworkerready/#moar)
-   in older web browsers. Service worker registration [won't be attempted](src/registerServiceWorker.js)
-   on browsers that lack support.
-
 1. The service worker is only enabled in the [production environment](/docs/deployment),
    e.g. the output of `npm run build`. It's recommended that you do not enable an
    offline-first service worker in a development environment, as it can lead to
@@ -70,18 +86,6 @@ following into account:
    instructions for using other methods. _Be sure to always use an
    incognito window to avoid complications with your browser cache._
 
-1. Users aren't always familiar with offline-first web apps. It can be useful to
-   [let the user know](https://developers.google.com/web/fundamentals/instant-and-offline/offline-ux#inform_the_user_when_the_app_is_ready_for_offline_consumption)
-   when the service worker has finished populating your caches (showing a "This web
-   app works offline!" message) and also let them know when the service worker has
-   fetched the latest updates that will be available the next time they load the
-   page (showing a "New content is available; please refresh." message). Showing
-   this messages is currently left as an exercise to the developer, but as a
-   starting point, you can make use of the logic included in [`src/registerServiceWorker.js`](src/registerServiceWorker.js), which
-   demonstrates which service worker lifecycle events to listen for to detect each
-   scenario, and which as a default, just logs appropriate messages to the
-   JavaScript console.
-
 1. By default, the generated service worker file will not intercept or cache any
    cross-origin traffic, like HTTP [API requests](/docs/integrating-with-an-api-backend),
    images, or embeds loaded from a different domain.
diff --git a/docusaurus/docs/post-processing-css.md b/docusaurus/docs/post-processing-css.md
@@ -7,7 +7,7 @@ This project setup minifies your CSS and adds vendor prefixes to it automaticall
 
 Support for new CSS features like the [`all` property](https://developer.mozilla.org/en-US/docs/Web/CSS/all), [`break` properties](https://www.w3.org/TR/css-break-3/#breaking-controls), [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables), and [media query ranges](https://www.w3.org/TR/mediaqueries-4/#range-context) are automatically polyfilled to add support for older browsers.
 
-You can customize your target support browsers by adjusting the `browserslist` key in `package.json` accoring to the [Browserslist specification](https://github.com/browserslist/browserslist#readme).
+You can customize your target support browsers by adjusting the `browserslist` key in `package.json` according to the [Browserslist specification](https://github.com/browserslist/browserslist#readme).
 
 For example, this:
 
diff --git a/docusaurus/docs/running-tests.md b/docusaurus/docs/running-tests.md
@@ -82,6 +82,8 @@ This test mounts a component and makes sure that it didn’t throw during render
 
 When you encounter bugs caused by changing components, you will gain a deeper insight into which parts of them are worth testing in your application. This might be a good time to introduce more specific tests asserting specific expected output or behavior.
 
+### Option 1: Shallow Rendering
+
 If you’d like to test components in isolation from the child components they render, we recommend using [`shallow()` rendering API](http://airbnb.io/enzyme/docs/api/shallow.html) from [Enzyme](http://airbnb.io/enzyme/). To install it, run:
 
 ```sh
@@ -167,6 +169,47 @@ Import it in [`src/setupTests.js`](#initializing-test-environment) to make its m
 import 'jest-enzyme';
 ```
 
+### Option 2: React Testing Library
+
+As an alternative or companion to `enzyme`, you may consider using `react-testing-library`. [`react-testing-library`](https://github.com/kentcdodds/react-testing-library) is a library for testing React components in a way that resembles the way the components are used by end users. It is well suited for unit, integration, and end-to-end testing of React components and applications. It works more directly with DOM nodes, and therefore it's recommended to use with [`jest-dom`](https://github.com/gnapse/jest-dom) for improved assertions.
+
+To install `react-testing-library` and `jest-dom`, you can run:
+
+```sh
+npm install --save react-testing-library jest-dom
+```
+
+Alternatively you may use `yarn`:
+
+```sh
+yarn add react-testing-library jest-dom
+```
+
+Similar to `enzyme` you can create a `src/setupTests.js` file to avoid boilerplate in your test files:
+
+```js
+// react-testing-library renders your components to document.body,
+// this will ensure they're removed after each test.
+import 'react-testing-library/cleanup-after-each';
+// this adds jest-dom's custom assertions
+import 'jest-dom/extend-expect';
+```
+
+Here's an example of using `react-testing-library` and `jest-dom` for testing that the `<App />` component renders "Welcome to React".
+
+```js
+import React from 'react';
+import { render } from 'react-testing-library';
+import App from './App';
+
+it('renders welcome message', () => {
+  const { getByText } = render(<App />);
+  expect(getByText('Welcome to React')).toBeInTheDocument();
+});
+```
+
+Learn more about the utilities provided by `react-testing-library` to facilitate testing asynchronous interactions as well as selecting form elements from [the `react-testing-library` documentation](https://github.com/kentcdodds/react-testing-library) and [examples](https://codesandbox.io/s/github/kentcdodds/react-testing-library-examples).
+
 ## Using Third Party Assertion Libraries
 
 We recommend that you use `expect()` for assertions and `jest.fn()` for spies. If you are having issues with them please [file those against Jest](https://github.com/facebook/jest/issues/new), and we’ll fix them. We intend to keep making them better for React, supporting, for example, [pretty-printing React elements as JSX](https://github.com/facebook/jest/pull/1566).
@@ -309,11 +352,11 @@ set CI=true&&npm run build
 #### Windows (Powershell)
 
 ```Powershell
-($env:CI = $true) -and (npm test)
+($env:CI = "true") -and (npm test)
 ```
 
 ```Powershell
-($env:CI = $true) -and (npm run build)
+($env:CI = "true") -and (npm run build)
 ```
 
 #### Linux, macOS (Bash)
diff --git a/docusaurus/docs/using-https-in-development.md b/docusaurus/docs/using-https-in-development.md
@@ -21,7 +21,7 @@ set HTTPS=true&&npm start
 ### Windows (Powershell)
 
 ```Powershell
-($env:HTTPS = $true) -and (npm start)
+($env:HTTPS = "true") -and (npm start)
 ```
 
 ### Linux, macOS (Bash)
diff --git a/docusaurus/website/i18n/en.json b/docusaurus/website/i18n/en.json
@@ -3,7 +3,7 @@
   "localized-strings": {
     "next": "Next",
     "previous": "Previous",
-    "tagline": "Create React apps with no build configuration.",
+    "tagline": "Set up a modern web app by running one command.",
     "docs": {
       "adding-a-css-modules-stylesheet": {
         "title": "Adding A CSS Modules Stylesheet",
