From af7051fc3f952e6cfd135fdcee60b1120b1f36df Mon Sep 17 00:00:00 2001 From: Dan Abramov Date: Wed, 28 Jun 2017 14:40:52 +0100 Subject: [PATCH 1/7] Minor code style edits to user guide --- packages/react-scripts/template/README.md | 145 +++++++++++++++------- 1 file changed, 98 insertions(+), 47 deletions(-) diff --git a/packages/react-scripts/template/README.md b/packages/react-scripts/template/README.md index 24821e3fcf2..c1b6bdaba33 100644 --- a/packages/react-scripts/template/README.md +++ b/packages/react-scripts/template/README.md @@ -275,14 +275,14 @@ Prettier is an opinionated JavaScript formatter. With Prettier you can format th To format our code whenever we make a commit in git, we need to install the following dependencies: -``` -npm install --save-dev husky lint-staged prettier +```sh +npm install --save husky lint-staged prettier ``` -or if you use Yarn: +Alternatively you may use `yarn`: -``` -yarn add --dev husky lint-staged prettier +```sh +yarn add husky lint-staged prettier ``` * `husky` makes it easy to use githooks as if they are npm scripts. @@ -293,15 +293,11 @@ Now we can make sure every file is formatted correctly by adding a few lines to Add the following line to `scripts` section: -```js -{ - // ... +```diff "scripts": { - // ... - "precommit": "lint-staged" - }, - // ... -} ++ "precommit": "lint-staged", + "start": "react-scripts start", + "build": "react-scripts build", ``` Next we add a 'lint-staged' field to the `package.json`, for example: @@ -336,13 +332,13 @@ If you use a custom server for your app in production and want to modify the tit The generated project includes React and ReactDOM as dependencies. It also includes a set of scripts used by Create React App as a development dependency. You may install other dependencies (for example, React Router) with `npm`: -``` +```sh npm install --save ``` -Alternatively you may also use `yarn`: +Alternatively you may use `yarn`: -``` +```sh yarn add ``` @@ -519,9 +515,16 @@ Following this rule often makes CSS preprocessors less useful, as features like First, let’s install the command-line interface for Sass: +```sh +npm install --save node-sass-chokidar ``` -npm install node-sass-chokidar --save-dev + +Alternatively you may use `yarn`: + +```sh +yarn add node-sass-chokidar ``` + Then in `package.json`, add the following lines to `scripts`: ```diff @@ -557,8 +560,14 @@ At this point you might want to remove all CSS files from the source control, an As a final step, you may find it convenient to run `watch-css` automatically with `npm start`, and run `build-css` as a part of `npm run build`. You can use the `&&` operator to execute two scripts sequentially. However, there is no cross-platform way to run two scripts in parallel, so we will install a package for this: +```sh +npm install --save npm-run-all ``` -npm install --save-dev npm-run-all + +Alternatively you may use `yarn`: + +```sh +yarn add npm-run-all ``` Then we can change `start` and `build` scripts to include the CSS preprocessor commands: @@ -716,9 +725,14 @@ You don’t have to use [React Bootstrap](https://react-bootstrap.github.io) tog Install React Bootstrap and Bootstrap from npm. React Bootstrap does not include Bootstrap CSS so this needs to be installed as well: +```sh +npm install --save react-bootstrap bootstrap@3 ``` -npm install react-bootstrap --save -npm install bootstrap@3 --save + +Alternatively you may use `yarn`: + +```sh +yarn add react-bootstrap bootstrap@3 ``` Import Bootstrap CSS and optionally Bootstrap theme CSS in the beginning of your ```src/index.js``` file: @@ -757,7 +771,7 @@ Recent versions of [Flow](http://flowtype.org/) work with Create React App proje To add Flow to a Create React App project, follow these steps: -1. Run `npm install --save-dev flow-bin` (or `yarn add --dev flow-bin`). +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://flowtype.org/docs/advanced-configuration.html) in the root directory. 4. Add `// @flow` to any files you want to type check (for example, to `src/App.js`). @@ -1226,12 +1240,20 @@ 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. -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/). You can write a smoke test with it too: +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 +npm install --save enzyme react-test-renderer +``` + +Alternatively you may use `yarn`: ```sh -npm install --save-dev enzyme react-test-renderer +yarn add enzyme react-test-renderer ``` +You can write a smoke test with it too: + ```js import React from 'react'; import { shallow } from 'enzyme'; @@ -1273,15 +1295,21 @@ expect(wrapper).toContainReact(welcome) To setup jest-enzyme with Create React App, follow the instructions for [initializing your test environment](#initializing-test-environment) to import `jest-enzyme`. ```sh -npm install --save-dev jest-enzyme +npm install --save jest-enzyme +``` + +Alternatively you may use `yarn`: + +```sh +yarn add jest-enzyme ``` +Import it in `src/setupTests.js` to make its matchers available globally: + ```js -// src/setupTests.js import 'jest-enzyme'; ``` - ### 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). @@ -1392,14 +1420,22 @@ The build command will check for linter warnings and fail if any are found. By default, the `package.json` of the generated project looks like this: ```js - // ... "scripts": { - // ... + "start": "react-scripts start", + "build": "react-scripts build", "test": "react-scripts test --env=jsdom" - } ``` -If you know that none of your tests depend on [jsdom](https://github.com/tmpvar/jsdom), you can safely remove `--env=jsdom`, and your tests will run faster.
+If you know that none of your tests depend on [jsdom](https://github.com/tmpvar/jsdom), you can safely remove `--env=jsdom`, and your tests will run faster: + +```diff + "scripts": { + "start": "react-scripts start", + "build": "react-scripts build", +- "test": "react-scripts test --env=jsdom" ++ "test": "react-scripts test" +``` + To help you make up your mind, here is a list of APIs that **need jsdom**: * Any browser globals like `window` and `document` @@ -1473,18 +1509,22 @@ Styleguidist combines of a style guide, where all your components are presented First, install Styleguidist: ```sh -npm install --save-dev react-styleguidist +npm install --save react-styleguidist ``` -Then, add these scripts to your `package.json`: +Alternatively you may use `yarn`: ```sh -{ - "scripts": { - "styleguide": "styleguidist server", - "styleguide:build": "styleguidist build" - } -} +yarn add react-styleguidist +``` + +Then, add these scripts to your `package.json`: + +```diff + "scripts": { ++ "styleguide": "styleguidist server", ++ "styleguide:build": "styleguidist build" + "start": "react-scripts start", ``` Then, run the following command inside your app’s directory: @@ -1608,8 +1648,14 @@ bloat is coming from. To add Source map explorer to a Create React App project, follow these steps: +```sh +npm install --save source-map-explorer ``` -npm install source-map-explorer --save-dev + +Alternatively you may use `yarn`: + +```sh +yarn add source-map-explorer ``` Then in `package.json`, add the following line to `scripts` @@ -1617,10 +1663,10 @@ On Windows you will have to type the full file path out. ```diff "scripts": { ++ "analyze": "source-map-explorer build/static/js/main.*", "start": "react-scripts start", "build": "react-scripts build", "test": "react-scripts test --env=jsdom", -+ "analyze": "source-map-explorer build/static/js/main.* " ``` Then to analyze the bundle run the production build then run the analyze @@ -1827,18 +1873,23 @@ Now, whenever you run `npm run build`, you will see a cheat sheet with instructi To publish it at [https://myusername.github.io/my-app](https://myusername.github.io/my-app), run: ```sh -npm install --save-dev gh-pages +npm install --save gh-pages +``` + +Alternatively you may use `yarn`: + +```sh +yarn add gh-pages ``` Add the following scripts in your `package.json`: -```js - // ... +```diff "scripts": { - // ... - "predeploy": "npm run build", - "deploy": "gh-pages -d build" - } ++ "predeploy": "npm run build", ++ "deploy": "gh-pages -d build", + "start": "react-scripts start", + "build": "react-scripts build", ``` The `predeploy` script will run automatically before `deploy` is run. From 9a4962274209a75ade8aa975c5617c683432ad26 Mon Sep 17 00:00:00 2001 From: Dan Abramov Date: Wed, 28 Jun 2017 14:43:53 +0100 Subject: [PATCH 2/7] Update README.md --- packages/react-scripts/template/README.md | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/packages/react-scripts/template/README.md b/packages/react-scripts/template/README.md index c1b6bdaba33..883927fca21 100644 --- a/packages/react-scripts/template/README.md +++ b/packages/react-scripts/template/README.md @@ -302,15 +302,22 @@ Add the following line to `scripts` section: Next we add a 'lint-staged' field to the `package.json`, for example: -```js +```diff { // ... - "lint-staged": { - "src/**/*.{js,jsx}": [ - "prettier --single-quote --write", - "git add" - ] - } + "dependencies": { + // ... + }, ++ "lint-staged": { ++ "src/**/*.{js,jsx}": [ ++ "prettier --single-quote --write", ++ "git add" ++ ] ++ }, + "scripts": { + // ... + }, + // ... } ``` From f713dac3ba9c0ef7e9b3a98bd9c30e2ac7a838d3 Mon Sep 17 00:00:00 2001 From: Dan Abramov Date: Wed, 28 Jun 2017 14:45:09 +0100 Subject: [PATCH 3/7] Update README.md --- packages/react-scripts/template/README.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/packages/react-scripts/template/README.md b/packages/react-scripts/template/README.md index 883927fca21..81e9d30b78d 100644 --- a/packages/react-scripts/template/README.md +++ b/packages/react-scripts/template/README.md @@ -303,8 +303,6 @@ Add the following line to `scripts` section: Next we add a 'lint-staged' field to the `package.json`, for example: ```diff -{ - // ... "dependencies": { // ... }, @@ -315,10 +313,6 @@ Next we add a 'lint-staged' field to the `package.json`, for example: + ] + }, "scripts": { - // ... - }, - // ... -} ``` Now, whenever you make a commit, Prettier will format the changed files automatically. You can also run `./node_modules/.bin/prettier --single-quote --write "src/**/*.{js,jsx}"` to format your entire project for the first time. From 598041f784776559f66a91f50c7a60164cbde13a Mon Sep 17 00:00:00 2001 From: Dan Abramov Date: Wed, 28 Jun 2017 14:46:16 +0100 Subject: [PATCH 4/7] Update README.md --- packages/react-scripts/template/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/react-scripts/template/README.md b/packages/react-scripts/template/README.md index 81e9d30b78d..104fd93a2c3 100644 --- a/packages/react-scripts/template/README.md +++ b/packages/react-scripts/template/README.md @@ -334,15 +334,17 @@ If you use a custom server for your app in production and want to modify the tit The generated project includes React and ReactDOM as dependencies. It also includes a set of scripts used by Create React App as a development dependency. You may install other dependencies (for example, React Router) with `npm`: ```sh -npm install --save +npm install --save react-router ``` Alternatively you may use `yarn`: ```sh -yarn add +yarn add react-router ``` +This works for any library, not just `react-router`. + ## Importing a Component This project setup supports ES6 modules thanks to Babel.
From c38b721d5e682f10a3ac251b21bdd5aefda6c34a Mon Sep 17 00:00:00 2001 From: Dan Abramov Date: Wed, 28 Jun 2017 14:48:10 +0100 Subject: [PATCH 5/7] Update README.md --- packages/react-scripts/template/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/react-scripts/template/README.md b/packages/react-scripts/template/README.md index 104fd93a2c3..cf21e619725 100644 --- a/packages/react-scripts/template/README.md +++ b/packages/react-scripts/template/README.md @@ -1295,7 +1295,7 @@ Additionally, you might find [jest-enzyme](https://github.com/blainekasten/enzym expect(wrapper).toContainReact(welcome) ``` -To setup jest-enzyme with Create React App, follow the instructions for [initializing your test environment](#initializing-test-environment) to import `jest-enzyme`. +To enable this, install `jest-enzyme`: ```sh npm install --save jest-enzyme @@ -1307,7 +1307,7 @@ Alternatively you may use `yarn`: yarn add jest-enzyme ``` -Import it in `src/setupTests.js` to make its matchers available globally: +Import it in [`src/setupTests.js`](#initializing-test-environment) to make its matchers available in every test: ```js import 'jest-enzyme'; From 061f139d8d8883af44c4c354b7a12a6e0ce68c88 Mon Sep 17 00:00:00 2001 From: Dan Abramov Date: Wed, 28 Jun 2017 14:49:50 +0100 Subject: [PATCH 6/7] Update README.md --- packages/react-scripts/template/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/react-scripts/template/README.md b/packages/react-scripts/template/README.md index cf21e619725..ef802e37e9d 100644 --- a/packages/react-scripts/template/README.md +++ b/packages/react-scripts/template/README.md @@ -1526,7 +1526,7 @@ Then, add these scripts to your `package.json`: ```diff "scripts": { + "styleguide": "styleguidist server", -+ "styleguide:build": "styleguidist build" ++ "styleguide:build": "styleguidist build", "start": "react-scripts start", ``` From 214722a103196060973fa7b925477cb05d46494c Mon Sep 17 00:00:00 2001 From: Dan Abramov Date: Wed, 28 Jun 2017 15:04:41 +0100 Subject: [PATCH 7/7] Update README.md --- packages/react-scripts/template/README.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/packages/react-scripts/template/README.md b/packages/react-scripts/template/README.md index ef802e37e9d..aa2ab434062 100644 --- a/packages/react-scripts/template/README.md +++ b/packages/react-scripts/template/README.md @@ -1661,8 +1661,7 @@ Alternatively you may use `yarn`: yarn add source-map-explorer ``` -Then in `package.json`, add the following line to `scripts` -On Windows you will have to type the full file path out. +Then in `package.json`, add the following line to `scripts`: ```diff "scripts": { @@ -1672,6 +1671,16 @@ On Windows you will have to type the full file path out. "test": "react-scripts test --env=jsdom", ``` +>**Note:** +> +>This doesn't quite work on Windows because it doesn't automatically expand `*` in the filepath. For now, the workaround is to look at the full hashed filename in `build/static/js` (e.g. `main.89b7e95a.js`) and copy it into `package.json` when you're running the analyzer. For example: +> +>```diff +>+ "analyze": "source-map-explorer build/static/js/main.89b7e95a.js", +>``` +> +>Unfortunately it will be different after every build. You can express support for fixing this on Windows [in this issue](https://github.com/danvk/source-map-explorer/issues/52). + Then to analyze the bundle run the production build then run the analyze script.