From df022360ee042537c4d1e711f9f5a68b394f4023 Mon Sep 17 00:00:00 2001 From: Joe Haddad <timer150@gmail.com> Date: Thu, 18 May 2017 23:58:37 -0400 Subject: [PATCH] Enable 1.0 docs (#2220) * 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 --- README.md | 6 +- packages/react-scripts/template/README.md | 108 ++++++++++++++++------ 2 files changed, 81 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index e9658d8585c..892987c91e9 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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. diff --git a/packages/react-scripts/template/README.md b/packages/react-scripts/template/README.md index 50bbf7b694a..a55f5876fe8 100644 --- a/packages/react-scripts/template/README.md +++ b/packages/react-scripts/template/README.md @@ -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) @@ -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) @@ -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 `react-scripts@0.2.0` and higher. +>Note: this feature is available with `react-scripts@0.2.0` 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. @@ -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` @@ -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`?** @@ -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 `react-scripts@1.0.0` 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. @@ -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 `react-scripts@1.0.0` 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 `react-scripts@0.4.0` and higher. @@ -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) @@ -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 @@ -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. @@ -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 @@ -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 @@ -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. @@ -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.