Skip to content

Commit

Permalink
Enable 1.0 docs (facebook#2220)
Browse files Browse the repository at this point in the history 
* Uncomment merged PRs

* Switch to br

* Update some webpack links

* Add a little about section for PWA

* oops

* fast on subsequent visits

* Add manual proxy config instructions

* hint package.json

* Change to js for comments

* Tune wording
  • Loading branch information
@Timer @romaindso
Timer authored and romaindso committed Jul 10, 2017
1 parent b93b230 commit df02236
Show file tree
Hide file tree
Showing 2 changed files with 81 additions and 33 deletions.
6 changes: 1 addition & 5 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -100,10 +100,8 @@ Builds the app for production to the `build` folder.<br>
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.<br>
Your app is ready to be deployed!
<!--TODO: uncoment and maybe revise
A [service worker](https://developers.google.com/web/fundamentals/getting-started/primers/service-workers) using an [offline-first caching strategy](https://developers.google.com/web/fundamentals/instant-and-offline/offline-cookbook/#cache-falling-back-to-network) is automatically generated.<br>
Your ([progressive web](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#making-a-progressive-web-app)) app is ready to be deployed!-->
Your ([progressive web](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#making-a-progressive-web-app)) app is ready to be deployed

## User Guide

Expand Down Expand Up @@ -165,9 +163,7 @@ Please refer to the [User Guide](https://github.com/facebookincubator/create-rea
* Import CSS and image files directly from JavaScript.
* Autoprefixed CSS, so you don’t need `-webkit` or other prefixes.
* A `build` script to bundle JS, CSS, and images for production, with sourcemaps.
<!--TODO: uncomment
* An offline-first [service worker](https://developers.google.com/web/fundamentals/getting-started/primers/service-workers) and a [web app manifest](https://developers.google.com/web/fundamentals/engage-and-retain/web-app-manifest/), meeting all the [Progressive Web App](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#making-a-progressive-web-app) criteria.
-->

**The feature set is intentionally limited**. It doesn’t support advanced features such as server rendering or CSS modules. The tool is also **non-configurable** because it is hard to provide a cohesive experience and easy updates across a set of tools when the user can tweak anything.

Expand Down
108 changes: 80 additions & 28 deletions packages/react-scripts/template/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ You can find the most recent version of this guide [here](https://github.com/fac
- [Node](#node)
- [Ruby on Rails](#ruby-on-rails)
- [Proxying API Requests in Development](#proxying-api-requests-in-development)
- [Configuring the Proxy Manually](#configuring-the-proxy-manually)
- [Using HTTPS in Development](#using-https-in-development)
- [Generating Dynamic `<meta>` Tags on the Server](#generating-dynamic-meta-tags-on-the-server)
- [Pre-Rendering into Static HTML Files](#pre-rendering-into-static-html-files)
Expand All @@ -61,10 +62,8 @@ You can find the most recent version of this guide [here](https://github.com/fac
- [Editor Integration](#editor-integration)
- [Developing Components in Isolation](#developing-components-in-isolation)
- [Making a Progressive Web App](#making-a-progressive-web-app)
<!-- todo: uncomment
- [Offline-First Considerations](#offline-first-considerations)
- [Progressive Web App Metadata](#progressive-web-app-metadata)
-->
- [Deployment](#deployment)
- [Static Server](#static-server)
- [Other Solutions](#other-solutions)
Expand Down Expand Up @@ -212,7 +211,7 @@ To configure the syntax highlighting in your favorite text editor, head to the [

## Displaying Lint Output in the Editor

>Note: this feature is available with `[email protected]` and higher.
>Note: this feature is available with `[email protected]` and higher.<br>
>It also only works with npm 3 or higher.
Some editors, including Sublime Text, Atom, and Visual Studio Code, provide plugins for ESLint.
Expand Down Expand Up @@ -331,7 +330,7 @@ Learn more about ES6 modules:

## Adding a Stylesheet

This project setup uses [Webpack](https://webpack.github.io/) 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**:
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`

Expand Down Expand Up @@ -446,7 +445,7 @@ Then we can change `start` and `build` scripts to include the CSS preprocessor c
}
```

Now running `npm start` and `npm run build` also builds Sass files.
Now running `npm start` and `npm run build` also builds Sass files.

**Why `node-sass-chokidar`?**

Expand Down Expand Up @@ -744,24 +743,23 @@ To define permanent environment variables, create a file called `.env` in the ro
REACT_APP_SECRET_CODE=abcdef
```

<!--
TODO: uncomment (and tweak) the doc for 0.10
What .env* files are used?
`.env` files **should be** checked into source control (with the exclusion of `.env*.local`).

What other `.env` files are can be used?

>Note: this feature is available with `[email protected]` and higher.
* `.env` - Default
* `.env.development`, `.env.test`, `.env.production` - Environment-specific settings.
* `.env.local` - Local overrides. This file is loaded for all environments except test.
* `.env.development.local`, `.env.test.local`, `.env.production.local` - Local overrides of environment-specific settings.

Files priority (file is skipped if does not exist):
File priority, from left to right:

* npm test - `.env.test.local`, `env.test`, `.env.local`, `.env`
* npm run build - `.env.production.local`, `env.production`, `.env.local`, `.env`
* npm start - `.env.development.local`, `env.development`, `.env.local`, `.env`

Priority from left to right.
-->

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.

Expand Down Expand Up @@ -833,9 +831,68 @@ Keep in mind that `proxy` only has effect in development (with `npm start`), and
The `proxy` option supports HTTP, HTTPS and WebSocket connections.<br>
If the `proxy` option is **not** flexible enough for you, alternatively you can:

* [Configure the proxy yourself](#configuring-the-proxy-manually)
* Enable CORS on your server ([here’s how to do it for Express](http://enable-cors.org/server_expressjs.html)).
* Use [environment variables](#adding-custom-environment-variables) to inject the right server host and port into your app.

### Configuring the Proxy Manually

>Note: this feature is available with `[email protected]` and higher.
If the `proxy` option is **not** flexible enough for you, you can specify an object in the following form (in `package.json`).<br>
You may also specify any configuration value [`http-proxy-middleware`](https://github.com/chimurai/http-proxy-middleware#options) or [`http-proxy`](https://github.com/nodejitsu/node-http-proxy#options) supports.
```js
{
// ...
"proxy": {
"/api": {
"target": "<url>",
"ws": true
// ...
}
}
// ...
}
```

All requests matching this path will be proxies, no exceptions. This includes requests for `text/html`, which the standard `proxy` option does not proxy.

If you need to specify multiple proxies, you may do so by specifying additional entries.
You may also narrow down matches using `*` and/or `**`, to match the path exactly or any subpath.
```js
{
// ...
"proxy": {
// Matches any request starting with /api
"/api": {
"target": "<url_1>",
"ws": true
// ...
},
// Matches any request starting with /foo
"/foo": {
"target": "<url_2>",
"ssl": true,
"pathRewrite": {
"^/foo": "/foo/beta"
}
// ...
},
// Matches /bar/abc.html but not /bar/sub/def.html
"/bar/*.html": {
"target": "<url_3>",
// ...
},
// Matches /bar/abc.html and /bar/sub/def.html
"/baz/**/*.html": {
"target": "<url_4>"
// ...
}
}
// ...
}
```

## Using HTTPS in Development

>Note: this feature is available with `[email protected]` and higher.
Expand Down Expand Up @@ -1218,15 +1275,17 @@ Learn more about React Storybook:

## Making a Progressive Web App

You can turn your React app into a [Progressive Web App](https://developers.google.com/web/progressive-web-apps/) by following the steps in [this repository](https://github.com/jeffposnick/create-react-pwa).

<!--
TODO: uncomment
By default, the production build is a fully functional, offline-first
[Progressive Web App](https://developers.google.com/web/progressive-web-apps/).

Progressive Web Apps are faster and more reliable than traditional web pages, and provide an engaging mobile experience:

* All static site assets are cached so that your page loads fast on subsequent visits, regardless of network connectivity (such as 2G or 3G). Updates are downloaded in the background.
* Your app will work regardless of network state, even if offline. This means your users will be able to use your app at 10,000 feet and on the Subway.
* On mobile devices, your app can be added directly to the user's home screen, app icon and all. You can also re-engage users using web **push notifications**. This eliminates the need for the app store.

The [`sw-precache-webpack-plugin`](https://github.com/goldhand/sw-precache-webpack-plugin)
is integrated into [`webpack.config.prod.js`](../config/webpack.config.prod.js),
is integrated into production configuration,
and it will take care of generating a service worker file that will automatically
precache all of your local assets and keep them up to date as you deploy updates.
The service worker will use a [cache-first strategy](https://developers.google.com/web/fundamentals/instant-and-offline/offline-cookbook/#cache-falling-back-to-network)
Expand Down Expand Up @@ -1265,9 +1324,8 @@ changes you've made locally.
1. If you *need* to test your offline-first service worker locally, build
the application (using `npm run build`) and run a simple http server from your
build directory. After running the build script, `create-react-app` will give
instructions for one way to test your production build locally using
`pushstate-server` and the [deployment instructions](#deployment) have
instructions for using the python `SimpleHTTPServer`. *Be sure to always use an
instructions for one way to test your production build locally and the [deployment instructions](#deployment) have
instructions for using other methods. *Be sure to always use an
incognito window to avoid complications with your browser cache.*

1. If possible,configure your production environment to serve the generated
Expand Down Expand Up @@ -1315,8 +1373,6 @@ icons, names, and branding colors to use when the web app is displayed.
provides more context about what each field means, and how your customizations
will affect your users' experience.

-->

## Deployment

`npm run build` creates a `build` directory with a production build of your app. Set up your favourite 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.
Expand Down Expand Up @@ -1392,9 +1448,6 @@ It will get copied to the `build` folder when you run `npm run build`.

Now requests to `/todos/42` will be handled correctly both in development and in production.

<!--
TODO: uncomment for 1.0
On a production build, and in a browser that supports [service workers](https://developers.google.com/web/fundamentals/getting-started/primers/service-workers),
the service worker will automatically handle all navigation requests, like for
`/todos/42`, by serving the cached copy of your `index.html`. This
Expand All @@ -1403,7 +1456,6 @@ service worker navigation routing can be configured or disabled by
[`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).
-->

### Building for Relative Paths

Expand Down Expand Up @@ -1675,7 +1727,7 @@ You can adjust various development and production settings by setting environmen
Variable | Development | Production | Usage
:--- | :---: | :---: | :---
BROWSER | :white_check_mark: | :x: | 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. <!-- TODO: enable with 0.10: 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. -->
BROWSER | :white_check_mark: | :x: | 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 | :white_check_mark: | :x: | By default, the development web server binds to `localhost`. You may use this variable to specify a different host.
PORT | :white_check_mark: | :x: | 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 | :white_check_mark: | :x: | When set to `true`, Create React App will run the development server in `https` mode.
Expand All @@ -1691,7 +1743,7 @@ If this doesn’t happen, try one of the following workarounds:
* If your project is in a Dropbox folder, try moving it out.
* If the watcher doesn’t see a file called `index.js` and you’re referencing it by the folder name, you [need to restart the watcher](https://github.com/facebookincubator/create-react-app/issues/1164) due to a Webpack bug.
* Some editors like Vim and IntelliJ have a “safe write” feature that currently breaks the watcher. You will need to disable it. Follow the instructions in [“Working with editors supporting safe write”](https://webpack.github.io/docs/webpack-dev-server.html#working-with-editors-ides-supporting-safe-write).
* Some editors like Vim and IntelliJ have a “safe write” feature that currently breaks the watcher. You will need to disable it. Follow the instructions in [“Adjusting Your Text Editor”](https://webpack.js.org/guides/development/#adjusting-your-text-editor).
* If your project path contains parentheses, try moving the project to a path without them. This is caused by a [Webpack watcher bug](https://github.com/webpack/watchpack/issues/42).
* On Linux and macOS, you might need to [tweak system settings](https://webpack.github.io/docs/troubleshooting.html#not-enough-watchers) to allow more watchers.
* If the project runs inside a virtual machine such as (a Vagrant provisioned) VirtualBox, create an `.env` file in your project directory if it doesn’t exist, and add `CHOKIDAR_USEPOLLING=true` to it. This ensures that the next time you run `npm start`, the watcher uses the polling mode, as necessary inside a VM.
Expand Down

0 comments on commit df02236

Please sign in to comment.