Merge pull request #5347 from selbekk/port-user-guide-over

Port user guide over

Author: selbekk

docusaurus/docs/README.md

@@ -0,0 +1,54 @@
+---
+id: adding-a-css-modules-stylesheet
+title: Adding a CSS Modules Stylesheet
+---
+
+> Note: this feature is available with `[email protected]` and higher.
+
+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`.
+
+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/).
+
+## `Button.module.css`
+
+```css
+.error {
+  background-color: red;
+}
+```
+
+## `another-stylesheet.css`
+
+```css
+.error {
+  color: red;
+}
+```
+
+## `Button.js`
+
+```js
+import React, { Component } from 'react';
+import styles from './Button.module.css'; // Import css modules stylesheet as styles
+import './another-stylesheet.css'; // Import regular stylesheet
+
+class Button extends Component {
+  render() {
+    // reference as a js object
+    return <button className={styles.error}>Error Button</button>;
+  }
+}
+```
+
+## Result
+
+No clashes from other `.error` class names
+
+```html
+<!-- This button has red background but not red text -->
+<button class="Button_error_ax7yz"></div>
+```
+
+**This is an optional feature.** Regular `<link>` stylesheets and CSS files are fully supported. CSS Modules are turned on for files ending with the `.module.css` extension.

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

@@ -0,0 +1,22 @@
+---
+id: adding-a-router
+title: Adding a Router
+---
+
+Create React App doesn't prescribe a specific routing solution, but [React Router](https://reacttraining.com/react-router/web/) is the most popular one.
+
+To add it, run:
+
+```sh
+npm install --save react-router-dom
+```
+
+Alternatively you may use `yarn`:
+
+```sh
+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.

docusaurus/docs/adding-a-router.md

@@ -0,0 +1,34 @@
+---
+id: adding-a-sass-stylesheet
+title: Adding a Sass Stylesheet
+---
+
+> Note: this feature is available with `[email protected]` and higher.
+
+Generally, we recommend that you don’t reuse the same CSS classes across different components. For example, instead of using a `.Button` CSS class in `<AcceptButton>` and `<RejectButton>` components, we recommend creating a `<Button>` component with its own `.Button` styles, that both `<AcceptButton>` and `<RejectButton>` can render (but [not inherit](https://facebook.github.io/react/docs/composition-vs-inheritance.html)).
+
+Following this rule often makes CSS preprocessors less useful, as features like mixins and nesting are replaced by component composition. You can, however, integrate a CSS preprocessor if you find it valuable.
+
+To use Sass, first install `node-sass`:
+
+```bash
+$ npm install node-sass --save
+$ # or
+$ yarn add node-sass
+```
+
+Now you can rename `src/App.css` to `src/App.scss` and update `src/App.js` to import `src/App.scss`.
+This file and any other file will be automatically compiled if imported with the extension `.scss` or `.sass`.
+
+To share variables between Sass files, you can use Sass imports. For example, `src/App.scss` and other component style files could include `@import "./shared.scss";` with variable definitions.
+
+This will allow you to do imports like
+
+```scss
+@import 'styles/_colors.scss'; // assuming a styles directory under src/
+@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!
+
+> **Note:** You must prefix imports from `node_modules` with `~` as displayed above.

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

@@ -0,0 +1,34 @@
+---
+id: adding-a-stylesheet
+title: Adding a Stylesheet
+---
+
+This project setup uses [Webpack](https://webpack.js.org/) for handling all assets. Webpack offers a custom way of “extending” the concept of `import` beyond JavaScript. To express that a JavaScript file depends on a CSS file, you need to **import the CSS from the JavaScript file**:
+
+## `Button.css`
+
+```css
+.Button {
+  padding: 20px;
+}
+```
+
+## `Button.js`
+
+```js
+import React, { Component } from 'react';
+import './Button.css'; // Tell Webpack that Button.js uses these styles
+
+class Button extends Component {
+  render() {
+    // You can use them as regular CSS styles
+    return <div className="Button" />;
+  }
+}
+```
+
+**This is not required for React** but many people find this feature convenient. You can read about the benefits of this approach [here](https://medium.com/seek-blog/block-element-modifying-your-javascript-components-d7f99fcab52b). However you should be aware that this makes your code less portable to other build tools and environments than Webpack.
+
+In development, expressing dependencies this way allows your styles to be reloaded on the fly as you edit them. In production, all CSS files will be concatenated into a single minified `.css` file in the build output.
+
+If you are concerned about using Webpack-specific semantics, you can put all your CSS right into `src/index.css`. It would still be imported from `src/index.js`, but you could always remove that import if you later migrate to a different build tool.

docusaurus/docs/adding-a-stylesheet.md

@@ -0,0 +1,59 @@
+---
+id: adding-bootstrap
+title: Adding Bootstrap
+---
+
+You don’t have to use [reactstrap](https://reactstrap.github.io/) together with React but it is a popular library for integrating Bootstrap with React apps. If you need it, you can integrate it with Create React App by following these steps:
+
+Install reactstrap and Bootstrap from npm. reactstrap does not include Bootstrap CSS so this needs to be installed as well:
+
+```sh
+npm install --save reactstrap bootstrap@4
+```
+
+Alternatively you may use `yarn`:
+
+```sh
+yarn add bootstrap@4 reactstrap
+```
+
+Import Bootstrap CSS and optionally Bootstrap theme CSS in the beginning of your `src/index.js` file:
+
+```js
+import 'bootstrap/dist/css/bootstrap.css';
+// Put any other imports below so that CSS from your
+// components takes precedence over default styles.
+```
+
+Import required reactstrap components within `src/App.js` file or your custom component files:
+
+```js
+import { Button } from 'reactstrap';
+```
+
+Now you are ready to use the imported reactstrap components within your component hierarchy defined in the render method. Here is an example [`App.js`](https://gist.githubusercontent.com/zx6658/d9f128cd57ca69e583ea2b5fea074238/raw/a56701c142d0c622eb6c20a457fbc01d708cb485/App.js) redone using reactstrap.
+
+## Using a Custom Theme
+
+> Note: this feature is available with `[email protected]` and higher.
+
+Sometimes you might need to tweak the visual styles of Bootstrap (or equivalent package).<br>
+As of `[email protected]` you can import `.scss` files. This makes it possible to use a package's built-in Sass variables for global style preferences.
+
+To customize Bootstrap, create a file called `src/custom.scss` (or similar) and import the Bootstrap source stylesheet. Add any overrides _before_ the imported file(s). You can reference [Bootstrap's documentation](http://getbootstrap.com/docs/4.1/getting-started/theming/#css-variables) for the names of the available variables.
+
+```scss
+// Override default variables before the import
+$body-bg: #000;
+
+// Import Bootstrap and its default variables
+@import '~bootstrap/scss/bootstrap.scss';
+```
+
+> **Note:** You must prefix imports from `node_modules` with `~` as displayed above.
+
+Finally, import the newly created `.scss` file instead of the default Bootstrap `.css` in the beginning of your `src/index.js` file, for example:
+
+```javascript
+import './custom.scss';
+```

docusaurus/docs/adding-bootstrap.md

@@ -0,0 +1,161 @@
+---
+id: adding-custom-environment-variables
+title: Adding Custom 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.
+
+> 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.
+
+These environment variables will be defined for you on `process.env`. For example, having an environment
+variable named `REACT_APP_SECRET_CODE` will be exposed in your JS as `process.env.REACT_APP_SECRET_CODE`.
+
+There is also a special built-in environment variable called `NODE_ENV`. You can read it from `process.env.NODE_ENV`. When you run `npm start`, it is always equal to `'development'`, when you run `npm test` it is always equal to `'test'`, and when you run `npm run build` to make a production bundle, it is always equal to `'production'`. **You cannot override `NODE_ENV` manually.** This prevents developers from accidentally deploying a slow development build to production.
+
+These environment variables can be useful for displaying information conditionally based on where the project is
+deployed or consuming sensitive data that lives outside of version control.
+
+First, you need to have environment variables defined. For example, let’s say you wanted to consume a secret defined
+in the environment inside a `<form>`:
+
+```jsx
+render() {
+  return (
+    <div>
+      <small>You are running this application in <b>{process.env.NODE_ENV}</b> mode.</small>
+      <form>
+        <input type="hidden" defaultValue={process.env.REACT_APP_SECRET_CODE} />
+      </form>
+    </div>
+  );
+}
+```
+
+During the build, `process.env.REACT_APP_SECRET_CODE` will be replaced with the current value of the `REACT_APP_SECRET_CODE` environment variable. Remember that the `NODE_ENV` variable will be set for you automatically.
+
+When you load the app in the browser and inspect the `<input>`, you will see its value set to `abcdef`, and the bold text will show the environment provided when using `npm start`:
+
+```html
+<div>
+  <small>You are running this application in <b>development</b> mode.</small>
+  <form>
+    <input type="hidden" value="abcdef" />
+  </form>
+</div>
+```
+
+The above form is looking for a variable called `REACT_APP_SECRET_CODE` from the environment. In order to consume this
+value, we need to have it defined in the environment. This can be done using two ways: either in your shell or in
+a `.env` file. Both of these ways are described in the next few sections.
+
+Having access to the `NODE_ENV` is also useful for performing actions conditionally:
+
+```js
+if (process.env.NODE_ENV !== 'production') {
+  analytics.disable();
+}
+```
+
+When you compile the app with `npm run build`, the minification step will strip out this condition, and the resulting bundle will be smaller.
+
+## Referencing Environment Variables in the HTML
+
+> Note: this feature is available with `[email protected]` and higher.
+
+You can also access the environment variables starting with `REACT_APP_` in the `public/index.html`. For example:
+
+```html
+<title>%REACT_APP_WEBSITE_NAME%</title>
+```
+
+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).
+
+## Adding Temporary Environment Variables In Your Shell
+
+Defining environment variables can vary between OSes. It’s also important to know that this manner is temporary for the
+life of the shell session.
+
+### Windows (cmd.exe)
+
+```cmd
+set "REACT_APP_SECRET_CODE=abcdef" && npm start
+```
+
+(Note: Quotes around the variable assignment are required to avoid a trailing whitespace.)
+
+### Windows (Powershell)
+
+```Powershell
+($env:REACT_APP_SECRET_CODE = "abcdef") -and (npm start)
+```
+
+### Linux, macOS (Bash)
+
+```bash
+REACT_APP_SECRET_CODE=abcdef npm start
+```
+
+## Adding Development Environment Variables In `.env`
+
+> Note: this feature is available with `[email protected]` and higher.
+
+To define permanent environment variables, create a file called `.env` in the root of your project:
+
+```
+REACT_APP_SECRET_CODE=abcdef
+```
+
+> 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.
+
+`.env` files **should be** checked into source control (with the exclusion of `.env*.local`).
+
+### What other `.env` files can be used?
+
+> Note: this feature is **available with `[email protected]` and higher**.
+
+- `.env`: Default.
+- `.env.local`: Local overrides. **This file is loaded for all environments except test.**
+- `.env.development`, `.env.test`, `.env.production`: Environment-specific settings.
+- `.env.development.local`, `.env.test.local`, `.env.production.local`: Local overrides of environment-specific settings.
+
+Files on the left have more priority than files on the right:
+
+- `npm start`: `.env.development.local`, `.env.development`, `.env.local`, `.env`
+- `npm run build`: `.env.production.local`, `.env.production`, `.env.local`, `.env`
+- `npm test`: `.env.test.local`, `.env.test`, `.env` (note `.env.local` is missing)
+
+These variables will act as the defaults if the machine does not explicitly set them.<br>
+Please refer to the [dotenv documentation](https://github.com/motdotla/dotenv) for more details.
+
+> Note: If you are defining environment variables for development, your CI and/or hosting platform will most likely need
+> these defined as well. Consult their documentation how to do this. For example, see the documentation for [Travis CI](https://docs.travis-ci.com/user/environment-variables/) or [Heroku](https://devcenter.heroku.com/articles/config-vars).
+
+### Expanding Environment Variables In `.env`
+
+> Note: this feature is available with `[email protected]` and higher.
+
+Expand variables already on your machine for use in your `.env` file (using [dotenv-expand](https://github.com/motdotla/dotenv-expand)).
+
+For example, to get the environment variable `npm_package_version`:
+
+```
+REACT_APP_VERSION=$npm_package_version
+# also works:
+# REACT_APP_VERSION=${npm_package_version}
+```
+
+Or expand variables local to the current `.env` file:
+
+```
+DOMAIN=www.example.com
+REACT_APP_FOO=$DOMAIN/foo
+REACT_APP_BAR=$DOMAIN/bar
+```

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

@@ -0,0 +1,21 @@
+---
+id: adding-flow
+title: Adding Flow
+---
+
+Flow is a static type checker that helps you write code with fewer bugs. Check out this [introduction to using static types in JavaScript](https://medium.com/@preethikasireddy/why-use-static-types-in-javascript-part-1-8382da1e0adb) if you are new to this concept.
+
+Recent versions of [Flow](https://flow.org/) work with Create React App projects out of the box.
+
+To add Flow to a Create React App project, follow these steps:
+
+1. Run `npm install --save flow-bin` (or `yarn add flow-bin`).
+2. Add `"flow": "flow"` to the `scripts` section of your `package.json`.
+3. Run `npm run flow init` (or `yarn flow init`) to create a [`.flowconfig` file](https://flow.org/en/docs/config/) in the root directory.
+4. Add `// @flow` to any files you want to type check (for example, to `src/App.js`).
+
+Now you can run `npm run flow` (or `yarn flow`) to check the files for type errors.
+You can optionally use an IDE like [Nuclide](https://nuclide.io/docs/languages/flow/) for a better integrated experience.
+In the future we plan to integrate it into Create React App even more closely.
+
+To learn more about Flow, check out [its documentation](https://flow.org/).