diff --git a/packages/react-scripts/template/README.md b/packages/react-scripts/template/README.md index 6df4d43d7f6..8c31e5242aa 100644 --- a/packages/react-scripts/template/README.md +++ b/packages/react-scripts/template/README.md @@ -13,11 +13,13 @@ You can find the most recent version of this guide [here](https://github.com/fac - [npm test](#npm-test) - [npm run build](#npm-run-build) - [npm run eject](#npm-run-eject) +- [Useful Hooks](#useful-hooks) + - [Formatting Code Automatically](#formatting-code-automatically) + - [Running Tests Against Staged Files](#running-tests-against-staged-files) - [Supported Language Features and Polyfills](#supported-language-features-and-polyfills) - [Syntax Highlighting in the Editor](#syntax-highlighting-in-the-editor) - [Displaying Lint Output in the Editor](#displaying-lint-output-in-the-editor) - [Debugging in the Editor](#debugging-in-the-editor) -- [Formatting Code Automatically](#formatting-code-automatically) - [Changing the Page ``](#changing-the-page-title) - [Installing a Dependency](#installing-a-dependency) - [Importing a Component](#importing-a-component) @@ -53,13 +55,13 @@ You can find the most recent version of this guide [here](https://github.com/fac - [Running Tests](#running-tests) - [Filename Conventions](#filename-conventions) - [Command Line Interface](#command-line-interface) - - [Version Control Integration](#version-control-integration) - [Writing Tests](#writing-tests) - [Testing Components](#testing-components) - [Using Third Party Assertion Libraries](#using-third-party-assertion-libraries) - [Initializing Test Environment](#initializing-test-environment) - [Focusing and Excluding Tests](#focusing-and-excluding-tests) - [Coverage Reporting](#coverage-reporting) + - [Version Control Integration](#version-control-integration) - [Continuous Integration](#continuous-integration) - [Disabling jsdom](#disabling-jsdom) - [Snapshot Testing](#snapshot-testing) @@ -189,6 +191,100 @@ Instead, it will copy all the configuration files and the transitive dependencie You don’t have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it. +## Useful Hooks + +Git Hooks are event-based scripts that get executed before or after certain events, such as: commit, push, receive, etc. + +There are many benefits you can get by adding/integrating Hooks to a repository. For example: make sure changes you made passed the tests before committing, make sure commit message follow the conventions, format code automatically before committing, and so on. + +To learn more about Git Hooks, read [the official documentation](https://git-scm.com/docs/githooks). + +### Formatting Code Automatically + +Prettier is an opinionated code formatter with support for JavaScript, CSS and JSON. With Prettier you can format the code you write automatically to ensure a code style within your project. See the [Prettier's GitHub page](https://github.com/prettier/prettier) for more information, and look at this [page to see it in action](https://prettier.github.io/prettier/). + +To format our code whenever we make a commit in git, we need to install the following dependencies: + +```sh +npm install --save husky lint-staged prettier +``` + +Alternatively you may use `yarn`: + +```sh +yarn add husky lint-staged prettier +``` + +* `husky` makes it easy to use githooks as if they are npm scripts. +* `lint-staged` allows us to run scripts on staged files in git. See this [blog post about lint-staged to learn more about it](https://medium.com/@okonetchnikov/make-linting-great-again-f3890e1ad6b8). +* `prettier` is the JavaScript formatter we will run before commits. + +Now we can make sure every file is formatted correctly by adding a few lines to the `package.json` in the project root. + +Add the following line to `scripts` section: + +```diff + "scripts": { ++ "precommit": "lint-staged", + "start": "react-scripts start", + "build": "react-scripts build", +``` + +Next we add a 'lint-staged' field to the `package.json`, for example: + +```diff + "dependencies": { + // ... + }, ++ "lint-staged": { ++ "src/**/*.{js,jsx,json,css}": [ ++ "prettier --single-quote --write", ++ "git add" ++ ] ++ }, + "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. + +Next you might want to integrate Prettier in your favorite editor. Read the section on [Editor Integration](https://github.com/prettier/prettier#editor-integration) on the Prettier GitHub page. + +### Running Tests Against Staged Files + +You can run tests against "staged" files before each Git commit by integrating the test script in pre-commit hook. + +First, install [husky](https://github.com/typicode/husky) & [lint-staged](https://github.com/okonet/lint-staged): + +```sh +npm install --save-dev husky lint-staged +``` + +Because we don't need the tests to run in watch mode, we need to set `CI` environment variable to `true`. As described in section [Continuous Integration](#continuous-integration). + +To make sure it's cross-platform, let's install [cross-env](https://github.com/kentcdodds/cross-env): + +```sh +npm install --save-dev cross-env +``` + +Then add this config to `package.json`: + +``` +"scripts": { + ... + "precommit": "lint-staged", + "test:staged": "cross-env CI=true react-scripts test --env=jsdom --findRelatedTests" +}, +"lint-staged": { + "src/**/*.js": [ + "test:staged", + "git add" + ] +} +``` + +This way, instead of running all tests, passing `--findRelatedTests` flag in test script will save our times a lot because Jest will run only the minimal amount of tests related to changes in your staging area. + ## Supported Language Features and Polyfills This project supports a superset of the latest JavaScript standard.<br> @@ -238,7 +334,7 @@ Now your editor should report the linting warnings. Note that even if you edit your `.eslintrc` file further, these changes will **only affect the editor integration**. They won’t affect the terminal and in-browser lint output. This is because Create React App intentionally provides a minimal set of rules that find common mistakes. -If you want to enforce a coding style for your project, consider using [Prettier](https://github.com/jlongster/prettier) instead of ESLint style rules. +If you want to enforce a coding style for your project, consider using [Prettier](#formatting-code-automatically) instead of ESLint style rules. ## Debugging in the Editor @@ -269,56 +365,6 @@ Then add the block below to your `launch.json` file and put it inside the `.vsco Start your app by running `npm start`, and start debugging in VS Code by pressing `F5` or by clicking the green debug icon. You can now write code, set breakpoints, make changes to the code, and debug your newly modified code—all from your editor. -## Formatting Code Automatically - -Prettier is an opinionated code formatter with support for JavaScript, CSS and JSON. With Prettier you can format the code you write automatically to ensure a code style within your project. See the [Prettier's GitHub page](https://github.com/prettier/prettier) for more information, and look at this [page to see it in action](https://prettier.github.io/prettier/). - -To format our code whenever we make a commit in git, we need to install the following dependencies: - -```sh -npm install --save husky lint-staged prettier -``` - -Alternatively you may use `yarn`: - -```sh -yarn add husky lint-staged prettier -``` - -* `husky` makes it easy to use githooks as if they are npm scripts. -* `lint-staged` allows us to run scripts on staged files in git. See this [blog post about lint-staged to learn more about it](https://medium.com/@okonetchnikov/make-linting-great-again-f3890e1ad6b8). -* `prettier` is the JavaScript formatter we will run before commits. - -Now we can make sure every file is formatted correctly by adding a few lines to the `package.json` in the project root. - -Add the following line to `scripts` section: - -```diff - "scripts": { -+ "precommit": "lint-staged", - "start": "react-scripts start", - "build": "react-scripts build", -``` - -Next we add a 'lint-staged' field to the `package.json`, for example: - -```diff - "dependencies": { - // ... - }, -+ "lint-staged": { -+ "src/**/*.{js,jsx,json,css}": [ -+ "prettier --single-quote --write", -+ "git add" -+ ] -+ }, - "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. - -Next you might want to integrate Prettier in your favorite editor. Read the section on [Editor Integration](https://github.com/prettier/prettier#editor-integration) on the Prettier GitHub page. - ## Changing the Page `<title>` You can find the source HTML file in the `public` folder of the generated project. You may edit the `<title>` tag in it to change the title from “React App” to anything else. @@ -1196,14 +1242,6 @@ The watcher includes an interactive command-line interface with the ability to r ![Jest watch mode](http://facebook.github.io/jest/img/blog/15-watch.gif) -### Version Control Integration - -By default, when you run `npm test`, Jest will only run the tests related to files changed since the last commit. This is an optimization designed to make your tests run fast regardless of how many tests you have. However it assumes that you don’t often commit the code that doesn’t pass the tests. - -Jest will always explicitly mention that it only ran tests related to the files changed since the last commit. You can also press `a` in the watch mode to force Jest to run all tests. - -Jest will always run all tests on a [continuous integration](#continuous-integration) server or if the project is not inside a Git or Mercurial repository. - ### Writing Tests To create tests, add `it()` (or `test()`) blocks with the name of the test and its code. You may optionally wrap them in `describe()` blocks for logical grouping but this is neither required nor recommended. @@ -1358,6 +1396,14 @@ Run `npm test -- --coverage` (note extra `--` in the middle) to include a covera Note that tests run much slower with coverage so it is recommended to run it separately from your normal workflow. +### Version Control Integration + +By default, when you run `npm test`, Jest will only run the tests related to files changed since the last commit. This is an optimization designed to make your tests run fast regardless of how many tests you have. However it assumes that you don’t often commit the code that doesn’t pass the tests. + +Jest will always explicitly mention that it only ran tests related to the files changed since the last commit. You can also press `a` in the watch mode to force Jest to run all tests. + +Jest will always run all tests on a [continuous integration](#continuous-integration) server or if the project is not inside a Git or Mercurial repository. + ### Continuous Integration By default `npm test` runs the watcher with interactive CLI. However, you can force it to run tests once and finish the process by setting an environment variable called `CI`. @@ -1374,6 +1420,7 @@ Popular CI servers already set the environment variable `CI` by default but you ``` language: node_js node_js: + - 4 - 6 cache: directories: