From b01213c8cd87128895cb50b95bf68979be518d0f Mon Sep 17 00:00:00 2001 From: Ian Sutherland Date: Sun, 20 Oct 2019 19:41:11 -0600 Subject: [PATCH 1/4] Add Alex to lint documentation --- .github/workflows/lint.yml | 14 ++++++++++++++ package.json | 3 +++ 2 files changed, 17 insertions(+) create mode 100644 .github/workflows/lint.yml diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 00000000000..cb206fbe7a2 --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,14 @@ +name: Lint + +on: [push] + +jobs: + lint: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v1 + - name: Install + run: yarn --no-progress --non-interactive --no-lockfile + - name: Alex + run: yarn alex diff --git a/package.json b/package.json index 4a1bcfe526c..36f19872299 100644 --- a/package.json +++ b/package.json @@ -14,11 +14,13 @@ "start": "cd packages/react-scripts && node bin/react-scripts.js start", "screencast": "node ./tasks/screencast.js", "screencast:error": "svg-term --cast jyu19xGl88FQ3poMY8Hbmfw8y --out screencast-error.svg --window --at 12000 --no-cursor", + "alex": "alex", "test": "cd packages/react-scripts && node bin/react-scripts.js test", "format": "prettier --trailing-comma es5 --single-quote --write 'packages/*/*.js' 'packages/*/!(node_modules)/**/*.js'", "compile:lockfile": "node tasks/compile-lockfile.js" }, "devDependencies": { + "alex": "^8.0.0", "eslint": "^6.1.0", "execa": "1.0.0", "fs-extra": "^7.0.1", @@ -45,6 +47,7 @@ }, "lint-staged": { "*.{js,md,css,html}": [ + "alex", "prettier --trailing-comma es5 --single-quote --write", "git add" ], From bb3070b7f174adfd5c02250e22f1a8f80100b0d2 Mon Sep 17 00:00:00 2001 From: Ian Sutherland Date: Mon, 21 Oct 2019 19:56:18 -0600 Subject: [PATCH 2/4] Attempt to trigger GitHub Action --- .github/workflows/lint.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index cb206fbe7a2..a2e7567d1e1 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -5,7 +5,6 @@ on: [push] jobs: lint: runs-on: ubuntu-latest - steps: - uses: actions/checkout@v1 - name: Install From 1b7b050ffdc00e1b167e0d2765f8a368aa531d06 Mon Sep 17 00:00:00 2001 From: Ian Sutherland Date: Mon, 21 Oct 2019 21:12:30 -0600 Subject: [PATCH 3/4] Configure Alex and update docs --- .alexignore | 4 ++++ .alexrc | 18 ++++++++++++++++++ CONTRIBUTING.md | 18 ++++++++++++------ README.md | 10 +++++----- .../adding-custom-environment-variables.md | 4 ++-- .../docs/adding-images-fonts-and-files.md | 4 ++-- docusaurus/docs/adding-relay.md | 2 +- docusaurus/docs/alternatives-to-ejecting.md | 2 +- docusaurus/docs/can-i-use-decorators.md | 2 +- docusaurus/docs/debugging-tests.md | 9 ++------- docusaurus/docs/deployment.md | 10 +++++----- .../docs/developing-components-in-isolation.md | 4 ++-- .../docs/fetching-data-with-ajax-requests.md | 2 +- docusaurus/docs/getting-started.md | 6 +++--- docusaurus/docs/installing-a-dependency.md | 2 +- .../docs/making-a-progressive-web-app.md | 4 ++-- docusaurus/docs/running-tests.md | 12 ++++++------ docusaurus/docs/setting-up-your-editor.md | 2 +- docusaurus/docs/supported-browsers-features.md | 2 +- docusaurus/docs/title-and-meta-tags.md | 12 +++++++----- docusaurus/docs/using-global-variables.md | 2 +- docusaurus/docs/using-the-public-folder.md | 4 ++-- package.json | 2 +- .../fixtures/kitchensink/README.md | 14 +++++++------- 24 files changed, 88 insertions(+), 63 deletions(-) create mode 100644 .alexignore create mode 100644 .alexrc diff --git a/.alexignore b/.alexignore new file mode 100644 index 00000000000..39d45cecd29 --- /dev/null +++ b/.alexignore @@ -0,0 +1,4 @@ +build + +CHANGELOG* +CODE_OF_CONDUCT.md \ No newline at end of file diff --git a/.alexrc b/.alexrc new file mode 100644 index 00000000000..8cda2010b9d --- /dev/null +++ b/.alexrc @@ -0,0 +1,18 @@ +{ + "allow": [ + "attacks", + "colors", + "conservative", + "crashes", + "executed", + "executes", + "execution", + "failed", + "hook", + "host-hostess", + "hostesses-hosts", + "invalid", + "remain", + "watchman-watchwoman" + ] +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8ee75d61935..6efe4450fb4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,8 @@ Loving Create React App and want to get involved? Thanks! There are plenty of ways you can help. + + Please take a moment to review this document in order to make the contribution process easy and effective for everyone involved. Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue or assessing patches and features. @@ -15,23 +17,27 @@ Here are a few examples of them in action. ### Convention + + Instead of letting the user specify the entry filename, we always assume it to be `src/index.js`. Rather than letting the user specify the output bundle name, we generate it, but make sure to include the content hash in it. Whenever possible, we want to leverage convention to make good choices for the user, especially in cases where it’s easy to misconfigure something. ### Heuristics Normally, `npm start` runs on port `3000`, and this is not explicitly configurable. However, some environments like cloud IDEs want the programs to run on a specific port to serve their output. We want to play well with different environments, so Create React App reads `PORT` environment variable and prefers it when it is specified. The trick is that we know cloud IDEs already specify it automatically, so there is no need for the user to do anything. Create React App relies on heuristics to do the right thing depending on environment. + + Another example of this is how `npm test` normally launches the watcher, but if the `CI` environment variable is set, it will run tests once. We know that popular CI environments set this variable, so the user doesn’t need to do anything. It just works. ### Interactivity -We prefer to add interactivity to the command line interface rather than add configuration flags. For example, `npm start` will attempt to run with port `3000` by default, but it may be busy. Many other tools just fail in this case and ask that you pass a different port, but Create React App will display a prompt asking if you’d like to run the app on the next available port. +We prefer to add interactivity to the command line interface rather than add configuration flags. For example, `npm start` will attempt to run with port `3000` by default, but it may be busy. Many other tools fail in this case and ask that you pass a different port, but Create React App will display a prompt asking if you’d like to run the app on the next available port. Another example of interactivity is `npm test` watcher interface. Instead of asking people to pass command line flags for switching between test runner modes or search patterns, we print a hint with keys that you can press during the test session to instruct watcher what to do. Jest supports both flags and interactive CLI but Create React App prefers long-running sessions to keep user immersed in the flow over short-running sessions with different flags. ### Breaking the Rules -No rules are perfect. Sometimes we may introduce flags or configuration if we believe the value is high enough to justify the mental cost. For example, we know that apps may be hosted paths different from the root, and we need to support this use case. However, we still try to fall back to heuristics when possible. In this example, we ask that you specify `homepage` in `package.json`, and infer the correct path based on it. We also nudge the user to fill out the `homepage` after the build, so the user becomes aware that the feature exists. +No rules are perfect. Sometimes we may introduce flags or configuration if we believe the value is high enough to justify the complexity. For example, we know that apps may be hosted paths different from the root, and we need to support this use case. However, we still try to fall back to heuristics when possible. In this example, we ask that you specify `homepage` in `package.json`, and infer the correct path based on it. We also nudge the user to fill out the `homepage` after the build, so the user becomes aware that the feature exists. ## Submitting a Pull Request @@ -76,7 +82,7 @@ This package is enabled by default for all `create-react-app` scaffolded applica #### [react-dev-utils](https://github.com/facebook/create-react-app/tree/master/packages/react-dev-utils) -This package contains utilities used for `react-scripts` and sister packages.
+This package contains utilities used for `react-scripts` and sibling packages.
Its main purpose is to conceal code which the user shouldn't be burdened with upon ejecting. #### [react-scripts](https://github.com/facebook/create-react-app/tree/master/packages/react-scripts) @@ -90,7 +96,7 @@ All functionality must be retained (and configuration given to the user) if they 2. Run `yarn` in the root `create-react-app` folder. -Once it is done, you can modify any file locally and run `yarn start`, `yarn test` or `yarn build` just like in a generated project. +Once it is done, you can modify any file locally and run `yarn start`, `yarn test` or `yarn build` like you can in a generated project. If you want to try out the end-to-end flow with the global CLI, you can do this too: @@ -113,7 +119,7 @@ More detailed information are in the dedicated [README](/packages/react-scripts/ #### Customizing E2E registry configuration -We use [verdaccio](https://github.com/verdaccio/verdaccio) to emulate packages publishing in a registry using a default configuration. You might modify the current behaviour just editing the file `task/verdaccio.yaml`. +We use [verdaccio](https://github.com/verdaccio/verdaccio) to emulate packages publishing in a registry using a default configuration. You might modify the current behaviour by editing the file `task/verdaccio.yaml`. For more information about the configuration check out the [Verdaccio documentation](https://verdaccio.org/docs/en/configuration). @@ -148,7 +154,7 @@ By default git would use `CRLF` line endings which would cause the scripts to fa - Maybe add some newlines here and there. Preview the result on GitHub to get a feel for it. Changelog generator output is a bit too terse for my taste, so try to make it visually pleasing and well grouped. 7. Make sure to include “Migrating from ...” instructions for the previous release. Often you can copy and paste them. -8. Run `npm run publish`. (It has to be `npm run publish` exactly, not just `npm publish` or `yarn publish`.) +8. Run `npm run publish`. (It has to be `npm run publish` exactly, not `npm publish` or `yarn publish`.) 9. Wait for a long time, and it will get published. Don’t worry that it’s stuck. In the end the publish script will prompt for versions before publishing the packages. 10. After publishing, create a GitHub Release with the same text as the changelog entry. See previous Releases for inspiration. diff --git a/README.md b/README.md index 9b957a2c580..6b40b6e210a 100644 --- a/README.md +++ b/README.md @@ -31,11 +31,11 @@ When you’re ready to deploy to production, create a minified bundle with `npm You **don’t** need to install or configure tools like Webpack or Babel.
They are preconfigured and hidden so that you can focus on the code. -Just create a project, and you’re good to go. +Create a project, and you’re good to go. ## Creating an App -**You’ll need to have Node 8.16.0 or Node 10.16.0 or later version on your local development machine** (but it’s not required on the server). You can use [nvm](https://github.com/creationix/nvm#installation) (macOS/Linux) or [nvm-windows](https://github.com/coreybutler/nvm-windows#node-version-manager-nvm-for-windows) to easily switch Node versions between different projects. +**You’ll need to have Node 8.16.0 or Node 10.16.0 or later version on your local development machine** (but it’s not required on the server). You can use [nvm](https://github.com/creationix/nvm#installation) (macOS/Linux) or [nvm-windows](https://github.com/coreybutler/nvm-windows#node-version-manager-nvm-for-windows) to switch Node versions between different projects. To create a new app, you may choose one of the following methods: @@ -86,7 +86,7 @@ my-app └── serviceWorker.js ``` -No configuration or complicated folder structures, just the files you need to build your app.
+No configuration or complicated folder structures, only the files you need to build your app.
Once the installation is done, you can open your project folder: ```sh @@ -133,7 +133,7 @@ Please refer to the [User Guide](https://facebook.github.io/create-react-app/doc ## Philosophy -- **One Dependency:** There is just one build dependency. It uses Webpack, Babel, ESLint, and other amazing projects, but provides a cohesive curated experience on top of them. +- **One Dependency:** There is only one build dependency. It uses Webpack, Babel, ESLint, and other amazing projects, but provides a cohesive curated experience on top of them. - **No Configuration Required:** You don't need to configure anything. A reasonably good configuration of both development and production builds is handled for you so you can focus on writing code. @@ -172,7 +172,7 @@ Here are a few common cases where you might want to try something else: - If you need to **publish a React component**, [nwb](https://github.com/insin/nwb) can [also do this](https://github.com/insin/nwb#react-components-and-libraries), as well as [Neutrino's react-components preset](https://neutrino.js.org/packages/react-components/). -- If you want to do **server rendering** with React and Node.js, check out [Next.js](https://github.com/zeit/next.js/) or [Razzle](https://github.com/jaredpalmer/razzle). Create React App is agnostic of the backend, and just produces static HTML/JS/CSS bundles. +- If you want to do **server rendering** with React and Node.js, check out [Next.js](https://github.com/zeit/next.js/) or [Razzle](https://github.com/jaredpalmer/razzle). Create React App is agnostic of the backend, and only produces static HTML/JS/CSS bundles. - If your website is **mostly static** (for example, a portfolio or a blog), consider using [Gatsby](https://www.gatsbyjs.org/) instead. Unlike Create React App, it pre-renders the website into HTML at the build time. diff --git a/docusaurus/docs/adding-custom-environment-variables.md b/docusaurus/docs/adding-custom-environment-variables.md index ae1b5d5c7a7..b604a10c810 100644 --- a/docusaurus/docs/adding-custom-environment-variables.md +++ b/docusaurus/docs/adding-custom-environment-variables.md @@ -12,13 +12,13 @@ Your project can consume variables declared in your environment as if they were > > Environment variables are embedded into the build, meaning anyone can view them by inspecting your app's files. -**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](title-and-meta-tags.md#injecting-data-from-the-server-into-the-page). Alternatively you can rebuild the app on the server anytime you change them. +**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, as [described here](title-and-meta-tags.md#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_NOT_SECRET_CODE` will be exposed in your JS as `process.env.REACT_APP_NOT_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. +There is also a 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. diff --git a/docusaurus/docs/adding-images-fonts-and-files.md b/docusaurus/docs/adding-images-fonts-and-files.md index 02a5377936c..3489670e705 100644 --- a/docusaurus/docs/adding-images-fonts-and-files.md +++ b/docusaurus/docs/adding-images-fonts-and-files.md @@ -35,7 +35,7 @@ This works in CSS too: } ``` -Webpack finds all relative module references in CSS (they start with `./`) and replaces them with the final paths from the compiled bundle. If you make a typo or accidentally delete an important file, you will see a compilation error, just like when you import a non-existent JavaScript module. The final filenames in the compiled bundle are generated by Webpack from content hashes. If the file content changes in the future, Webpack will give it a different name in production so you don’t need to worry about long-term caching of assets. +Webpack finds all relative module references in CSS (they start with `./`) and replaces them with the final paths from the compiled bundle. If you make a typo or accidentally delete an important file, you will see a compilation error, like when you import a non-existent JavaScript module. The final filenames in the compiled bundle are generated by Webpack from content hashes. If the file content changes in the future, Webpack will give it a different name in production so you don’t need to worry about long-term caching of assets. Please be advised that this is also a custom feature of Webpack. @@ -59,6 +59,6 @@ const App = () => ( ); ``` -This is handy if you don't want to load SVG as a separate file. Don't forget the curly braces in the import! The `ReactComponent` import name is special and tells Create React App that you want a React component that renders an SVG, rather than its filename. +This is handy if you don't want to load SVG as a separate file. Don't forget the curly braces in the import! The `ReactComponent` import name is significant and tells Create React App that you want a React component that renders an SVG, rather than its filename. > **Tip:** The imported SVG React Component accepts a `title` prop along with other props that a `svg` element accepts. Use this prop to add an accessible title to your svg component. diff --git a/docusaurus/docs/adding-relay.md b/docusaurus/docs/adding-relay.md index 66702619b49..022248b9f22 100644 --- a/docusaurus/docs/adding-relay.md +++ b/docusaurus/docs/adding-relay.md @@ -3,7 +3,7 @@ id: adding-relay title: Adding Relay --- -Relay is a framework for building data-driven React applications powered by GraphQL. The current release of Relay works with Create React App projects out of the box using Babel Macros. Simply set up your project as laid out in the [Relay documentation](https://facebook.github.io/relay/), then make sure you have a version of the babel plugin providing the macro. +Relay is a framework for building data-driven React applications powered by GraphQL. The current release of Relay works with Create React App projects out of the box using Babel Macros. Set up your project as shown in the [Relay documentation](https://facebook.github.io/relay/), then make sure you have a version of the babel plugin providing the macro. To add it, run: diff --git a/docusaurus/docs/alternatives-to-ejecting.md b/docusaurus/docs/alternatives-to-ejecting.md index 7a37673eb0c..a7255aa938f 100644 --- a/docusaurus/docs/alternatives-to-ejecting.md +++ b/docusaurus/docs/alternatives-to-ejecting.md @@ -3,4 +3,4 @@ id: alternatives-to-ejecting title: Alternatives to Ejecting --- -[Ejecting](available-scripts.md#npm-run-eject) lets you customize anything, but from that point on you have to maintain the configuration and scripts yourself. This can be daunting if you have many similar projects. In such cases instead of ejecting we recommend to _fork_ `react-scripts` and any other packages you need. [This article](https://auth0.com/blog/how-to-configure-create-react-app/) dives into how to do it in depth. You can find more discussion in [this issue](https://github.com/facebook/create-react-app/issues/682). +[Ejecting](available-scripts.md#npm-run-eject) lets you customize anything, but from that point on you have to maintain the configuration and scripts yourself. This can be daunting if you have many similar projects. In such cases instead of ejecting we recommend to _fork_ `react-scripts` and any other packages you need. [This article](https://auth0.com/blog/how-to-configure-create-react-app/) covers how to do it in depth. You can find more discussion in [this issue](https://github.com/facebook/create-react-app/issues/682). diff --git a/docusaurus/docs/can-i-use-decorators.md b/docusaurus/docs/can-i-use-decorators.md index d698b6f527a..474d5139d56 100644 --- a/docusaurus/docs/can-i-use-decorators.md +++ b/docusaurus/docs/can-i-use-decorators.md @@ -10,7 +10,7 @@ Create React App intentionally doesn’t support decorator syntax at the moment - It is an experimental proposal and is subject to change (in fact, it has already changed once, and will change again). - Most libraries currently support only the old version of the proposal — which will never be a standard. -However in many cases you can rewrite decorator-based code without decorators just as fine. +However in many cases you can rewrite decorator-based code without decorators and achieve the same result. Please refer to these two threads for reference: diff --git a/docusaurus/docs/debugging-tests.md b/docusaurus/docs/debugging-tests.md index d13edaa8ef6..398ff94696a 100644 --- a/docusaurus/docs/debugging-tests.md +++ b/docusaurus/docs/debugging-tests.md @@ -32,7 +32,7 @@ Open the following in Chrome about:inspect ``` -After opening that link, the Chrome Developer Tools will be displayed. Select `inspect` on your process and a breakpoint will be set at the first line of the react script (this is done simply to give you time to open the developer tools and to prevent Jest from executing before you have time to do so). Click the button that looks like a "play" button in the upper right hand side of the screen to continue execution. When Jest executes the test that contains the debugger statement, execution will pause and you can examine the current scope and call stack. +After opening that link, the Chrome Developer Tools will be displayed. Select `inspect` on your process and a breakpoint will be set at the first line of the react script (this is done to give you time to open the developer tools and to prevent Jest from executing before you have time to do so). Click the button that looks like a "play" button in the upper right hand side of the screen to continue execution. When Jest executes the test that contains the debugger statement, execution will pause and you can examine the current scope and call stack. > Note: the --runInBand cli option makes sure Jest runs test in the same process rather than spawning processes for individual tests. Normally Jest parallelizes test runs across processes but it is hard to debug many processes at the same time. @@ -51,12 +51,7 @@ Use the following [`launch.json`](https://code.visualstudio.com/docs/editor/debu "type": "node", "request": "launch", "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/react-scripts", - "args": [ - "test", - "--runInBand", - "--no-cache", - "--watchAll=false" - ], + "args": ["test", "--runInBand", "--no-cache", "--watchAll=false"], "cwd": "${workspaceRoot}", "protocol": "inspector", "console": "integratedTerminal", diff --git a/docusaurus/docs/deployment.md b/docusaurus/docs/deployment.md index 3a642a32cb0..dfb2e13d6aa 100644 --- a/docusaurus/docs/deployment.md +++ b/docusaurus/docs/deployment.md @@ -29,7 +29,7 @@ serve -h ## Other Solutions -You don’t necessarily need a static server in order to run a Create React App project in production. It works just as fine integrated into an existing dynamic one. +You don’t necessarily need a static server in order to run a Create React App project in production. It also works well when integrated into an existing server side app. Here’s a programmatic example using [Node](https://nodejs.org/) and [Express](https://expressjs.com/): @@ -163,7 +163,7 @@ Variables in `.env.production` will be used as fallback because `NODE_ENV` will ## [AWS Amplify](http://console.amplify.aws) -The AWS Amplify Console provides continuous deployment and hosting for modern web apps (single page apps and static site generators) with serverless backends. The Amplify Console offers globally available CDNs, easy custom domain setup, feature branch deployments, and password protection. +The AWS Amplify Console provides continuous deployment and hosting for modern web apps (single page apps and static site generators) with serverless backends. The Amplify Console offers globally available CDNs, custom domain setup, feature branch deployments, and password protection. 1. Login to the Amplify Console [here](https://console.aws.amazon.com/amplify/home). 1. Connect your Create React App repo and pick a branch. If you're looking for a Create React App+Amplify starter, try the [create-react-app-auth-amplify starter](https://github.com/swaminator/create-react-app-auth-amplify) that demonstrates setting up auth in 10 minutes with Create React App. @@ -189,7 +189,7 @@ Then run the `firebase init` command from your project’s root. You need to cho First, let's associate this project directory with a Firebase project. You can create multiple project aliases by running firebase use --add, - but for now we'll just set up a default project. + but for now we'll set up a default project. ? What Firebase project do you want to associate as default? Example app (example-app-fd690) @@ -350,7 +350,7 @@ mywebsite.com GitHub Pages doesn’t support routers that use the HTML5 `pushState` history API under the hood (for example, React Router using `browserHistory`). This is because when there is a fresh page load for a url like `http://user.github.io/todomvc/todos/42`, where `/todos/42` is a frontend route, the GitHub Pages server returns 404 because it knows nothing of `/todos/42`. If you want to add a router to a project hosted on GitHub Pages, here are a couple of solutions: - You could switch from using HTML5 history API to routing with hashes. If you use React Router, you can switch to `hashHistory` for this effect, but the URL will be longer and more verbose (for example, `http://user.github.io/todomvc/#/todos/42?_k=yknaj`). [Read more](https://reacttraining.com/react-router/web/api/Router) about different history implementations in React Router. -- Alternatively, you can use a trick to teach GitHub Pages to handle 404 by redirecting to your `index.html` page with a special redirect parameter. You would need to add a `404.html` file with the redirection code to the `build` folder before deploying your project, and you’ll need to add code handling the redirect parameter to `index.html`. You can find a detailed explanation of this technique [in this guide](https://github.com/rafrex/spa-github-pages). +- Alternatively, you can use a trick to teach GitHub Pages to handle 404s by redirecting to your `index.html` page with a custom redirect parameter. You would need to add a `404.html` file with the redirection code to the `build` folder before deploying your project, and you’ll need to add code handling the redirect parameter to `index.html`. You can find a detailed explanation of this technique [in this guide](https://github.com/rafrex/spa-github-pages). ### Troubleshooting @@ -472,7 +472,7 @@ Out of the box, you are preconfigured for client-side routing compatibility and Render offers free [static site](https://render.com/docs/static-sites) hosting with fully managed SSL, a global CDN and continuous auto deploys from GitHub. -Deploy your app in just a few minutes by following the [Create React App deployment guide](https://render.com/docs/deploy-create-react-app). +Deploy your app in only a few minutes by following the [Create React App deployment guide](https://render.com/docs/deploy-create-react-app). Use invite code `cra` to sign up or use [this link](https://render.com/i/cra). diff --git a/docusaurus/docs/developing-components-in-isolation.md b/docusaurus/docs/developing-components-in-isolation.md index 9286348d77e..90baae5a1de 100644 --- a/docusaurus/docs/developing-components-in-isolation.md +++ b/docusaurus/docs/developing-components-in-isolation.md @@ -4,7 +4,7 @@ title: Developing Components in Isolation --- Usually, in an app, you have a lot of UI components, and each of them has many different states. -For an example, a simple button component could have the following states: +For an example, a basic button component could have the following states: - In a regular state, with a text label. - In the disabled mode. @@ -12,7 +12,7 @@ For an example, a simple button component could have the following states: Usually, it’s hard to see these states without running a sample app or some examples. -Create React App doesn’t include any tools for this by default, but you can easily add [Storybook for React](https://storybook.js.org) ([source](https://github.com/storybooks/storybook)) or [React Styleguidist](https://react-styleguidist.js.org/) ([source](https://github.com/styleguidist/react-styleguidist)) to your project. **These are third-party tools that let you develop components and see all their states in isolation from your app**. +Create React App doesn’t include any tools for this by default, but you can add [Storybook for React](https://storybook.js.org) ([source](https://github.com/storybooks/storybook)) or [React Styleguidist](https://react-styleguidist.js.org/) ([source](https://github.com/styleguidist/react-styleguidist)) to your project. **These are third-party tools that let you develop components and see all their states in isolation from your app**. ![Storybook for React Demo](https://i.imgur.com/7CIAWpB.gif) diff --git a/docusaurus/docs/fetching-data-with-ajax-requests.md b/docusaurus/docs/fetching-data-with-ajax-requests.md index 8dff9f8ce58..22f37e09a06 100644 --- a/docusaurus/docs/fetching-data-with-ajax-requests.md +++ b/docusaurus/docs/fetching-data-with-ajax-requests.md @@ -6,7 +6,7 @@ sidebar_label: Fetching Data React doesn't prescribe a specific approach to data fetching, but people commonly use either a library like [axios](https://github.com/axios/axios) or the [`fetch()` API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) provided by the browser. -The global `fetch` function allows you to easily make AJAX requests. It takes in a URL as an input and returns a `Promise` that resolves to a `Response` object. You can find more information about `fetch` [here](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch). +The global `fetch` function allows you to make AJAX requests. It takes in a URL as an input and returns a `Promise` that resolves to a `Response` object. You can find more information about `fetch` [here](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch). A Promise represents the eventual result of an asynchronous operation, you can find more information about Promises [here](https://www.promisejs.org/) and [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). Both axios and `fetch()` use Promises under the hood. You can also use the [`async / await`](https://davidwalsh.name/async-await) syntax to reduce the callback nesting. diff --git a/docusaurus/docs/getting-started.md b/docusaurus/docs/getting-started.md index c374a39f564..de54f557040 100644 --- a/docusaurus/docs/getting-started.md +++ b/docusaurus/docs/getting-started.md @@ -30,11 +30,11 @@ When you’re ready to deploy to production, create a minified bundle with `npm You **don’t** need to install or configure tools like Webpack or Babel. They are preconfigured and hidden so that you can focus on the code. -Just create a project, and you’re good to go. +Create a project, and you’re good to go. ## Creating an App -**You’ll need to have Node >= 8.10 on your local development machine** (but it’s not required on the server). You can use [nvm](https://github.com/creationix/nvm#installation) (macOS/Linux) or [nvm-windows](https://github.com/coreybutler/nvm-windows#node-version-manager-nvm-for-windows) to easily switch Node versions between different projects. +**You’ll need to have Node >= 8.10 on your local development machine** (but it’s not required on the server). You can use [nvm](https://github.com/creationix/nvm#installation) (macOS/Linux) or [nvm-windows](https://github.com/coreybutler/nvm-windows#node-version-manager-nvm-for-windows) to switch Node versions between different projects. To create a new app, you may choose one of the following methods: @@ -101,7 +101,7 @@ my-app └── serviceWorker.js ``` -No configuration or complicated folder structures, just the files you need to build your app. Once the installation is done, you can open your project folder: +No configuration or complicated folder structures, only the files you need to build your app. Once the installation is done, you can open your project folder: ```sh cd my-app diff --git a/docusaurus/docs/installing-a-dependency.md b/docusaurus/docs/installing-a-dependency.md index 6e356315ab2..07559840a6e 100644 --- a/docusaurus/docs/installing-a-dependency.md +++ b/docusaurus/docs/installing-a-dependency.md @@ -15,4 +15,4 @@ Alternatively you may use `yarn`: yarn add react-router-dom ``` -This works for any library, not just `react-router-dom`. +This works for any library, not only `react-router-dom`. diff --git a/docusaurus/docs/making-a-progressive-web-app.md b/docusaurus/docs/making-a-progressive-web-app.md index 0eb7d404edf..e8e9c1bddde 100644 --- a/docusaurus/docs/making-a-progressive-web-app.md +++ b/docusaurus/docs/making-a-progressive-web-app.md @@ -64,7 +64,7 @@ following into account: these messages is currently left as an exercise to the developer, but as a starting point, you can make use of the logic included in [`src/serviceWorker.js`](https://github.com/facebook/create-react-app/blob/master/packages/react-scripts/template/src/serviceWorker.js), which demonstrates which service worker lifecycle events to listen for to detect each - scenario, and which as a default, just logs appropriate messages to the + scenario, and which as a default, only logs appropriate messages to the JavaScript console. 1. Service workers [require HTTPS](https://developers.google.com/web/fundamentals/getting-started/primers/service-workers#you_need_https), @@ -80,7 +80,7 @@ following into account: 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 + the application (using `npm run build`) and run a standard 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 and the [deployment instructions](deployment.md) have instructions for using other methods. _Be sure to always use an diff --git a/docusaurus/docs/running-tests.md b/docusaurus/docs/running-tests.md index 1640445a162..f416b64d33f 100644 --- a/docusaurus/docs/running-tests.md +++ b/docusaurus/docs/running-tests.md @@ -25,11 +25,11 @@ Jest will look for test files with any of the following popular naming conventio The `.test.js` / `.spec.js` files (or the `__tests__` folders) can be located at any depth under the `src` top level folder. -We recommend to put the test files (or `__tests__` folders) next to the code they are testing so that relative imports appear shorter. For example, if `App.test.js` and `App.js` are in the same folder, the test just needs to `import App from './App'` instead of a long relative path. Collocation also helps find tests more quickly in larger projects. +We recommend to put the test files (or `__tests__` folders) next to the code they are testing so that relative imports appear shorter. For example, if `App.test.js` and `App.js` are in the same folder, the test only needs to `import App from './App'` instead of a long relative path. Collocation also helps find tests more quickly in larger projects. ## Command Line Interface -When you run `npm test`, Jest will launch in watch mode\*. Every time you save a file, it will re-run the tests, just like `npm start` recompiles the code. +When you run `npm test`, Jest will launch in watch mode\*. Every time you save a file, it will re-run the tests, like how `npm start` recompiles the code. The watcher includes an interactive command-line interface with the ability to run all tests, or focus on a search pattern. It is designed this way so that you can keep it open and enjoy fast re-runs. You can learn the commands from the “Watch Usage” note that the watcher prints after every run: @@ -68,7 +68,7 @@ You can also use [`jest.fn()` and `expect(fn).toBeCalled()`](https://jestjs.io/d There is a broad spectrum of component testing techniques. They range from a “smoke test” verifying that a component renders without throwing, to shallow rendering and testing some of the output, to full rendering and testing component lifecycle and state changes. -Different projects choose different testing tradeoffs based on how often components change, and how much logic they contain. If you haven’t decided on a testing strategy yet, we recommend that you start with creating simple smoke tests for your components: +Different projects choose different testing tradeoffs based on how often components change, and how much logic they contain. If you haven’t decided on a testing strategy yet, we recommend that you start with creating basic smoke tests for your components: ```js import React from 'react'; @@ -149,7 +149,7 @@ All Jest matchers are [extensively documented here](https://jestjs.io/docs/en/ex Nevertheless you can use a third-party assertion library like [Chai](https://chaijs.com/) if you want to, as described below. -Additionally, you might find [jest-enzyme](https://github.com/blainekasten/enzyme-matchers) helpful to simplify your tests with readable matchers. The above `contains` code can be written more simply with jest-enzyme. +Additionally, you might find [jest-enzyme](https://github.com/blainekasten/enzyme-matchers) helpful to improve your tests with readable matchers. The above `contains` code can be written more concisely with jest-enzyme. ```js expect(wrapper).toContainReact(welcome); @@ -229,7 +229,7 @@ and then use them in your tests like you normally do. > Note: this feature is available with `react-scripts@0.4.0` and higher. -If your app uses a browser API that you need to mock in your tests or if you just need a global setup before running your tests, add a `src/setupTests.js` to your project. It will be automatically executed before running your tests. +If your app uses a browser API that you need to mock in your tests or if you need a global setup before running your tests, add a `src/setupTests.js` to your project. It will be automatically executed before running your tests. For example: @@ -387,7 +387,7 @@ CI=true npm run build The test command will force Jest to run in CI-mode, and tests will only run once instead of launching the watcher. -For non-CI environments, you can simply pass the `--watchAll=false` flag to disable test-watching. +For non-CI environments, you can pass the `--watchAll=false` flag to disable test-watching. The build command will check for linter warnings and fail if any are found. diff --git a/docusaurus/docs/setting-up-your-editor.md b/docusaurus/docs/setting-up-your-editor.md index 326c7f78022..95dbaa598b6 100644 --- a/docusaurus/docs/setting-up-your-editor.md +++ b/docusaurus/docs/setting-up-your-editor.md @@ -142,7 +142,7 @@ Alternatively you may use `yarn`: yarn add husky lint-staged prettier ``` -- `husky` makes it easy to use githooks as if they are npm scripts. +- `husky` makes it possible 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. diff --git a/docusaurus/docs/supported-browsers-features.md b/docusaurus/docs/supported-browsers-features.md index 27c3391ff1e..b43648bb1bf 100644 --- a/docusaurus/docs/supported-browsers-features.md +++ b/docusaurus/docs/supported-browsers-features.md @@ -52,4 +52,4 @@ Here is an example `browserslist` that is specified in `package.json`: > Note that this does not include polyfills automatically for you. You will still need to polyfill language features (see above) as needed based on the browsers your are supporting. -> When editing the `browserslist` config, you may notice that your changes don't get picked up right away. This is due to an [issue in babel-loader](https://github.com/babel/babel-loader/issues/690) not detecting the change in your `package.json`. An easy solution is to delete the `node_modules/.cache` folder and try again. +> When editing the `browserslist` config, you may notice that your changes don't get picked up right away. This is due to an [issue in babel-loader](https://github.com/babel/babel-loader/issues/690) not detecting the change in your `package.json`. An quick solution is to delete the `node_modules/.cache` folder and try again. diff --git a/docusaurus/docs/title-and-meta-tags.md b/docusaurus/docs/title-and-meta-tags.md index 0da67432532..1bea575503b 100644 --- a/docusaurus/docs/title-and-meta-tags.md +++ b/docusaurus/docs/title-and-meta-tags.md @@ -19,16 +19,18 @@ If you use a custom server for your app in production and want to modify the tit Since Create React App doesn’t support server rendering, you might be wondering how to make `` tags dynamic and reflect the current URL. To solve this, we recommend to add placeholders into the HTML, like this: ```html - + - - + + + + ``` -Then, on the server, regardless of the backend you use, you can read `index.html` into memory and replace `__OG_TITLE__`, `__OG_DESCRIPTION__`, and any other placeholders with values depending on the current URL. Just make sure to sanitize and escape the interpolated values so that they are safe to embed into HTML! +Then, on the server, regardless of the backend you use, you can read `index.html` into memory and replace `__OG_TITLE__`, `__OG_DESCRIPTION__`, and any other placeholders with values depending on the current URL. Make sure to sanitize and escape the interpolated values so that they are safe to embed into HTML! -If you use a Node server, you can even share the route matching logic between the client and the server. However duplicating it also works fine in simple cases. +If you use a Node server, you can even share the route matching logic between the client and the server. However duplicating it also works fine in basic cases. ## Injecting Data from the Server into the Page diff --git a/docusaurus/docs/using-global-variables.md b/docusaurus/docs/using-global-variables.md index ee9ad8a6d94..2f5b20a2672 100644 --- a/docusaurus/docs/using-global-variables.md +++ b/docusaurus/docs/using-global-variables.md @@ -11,6 +11,6 @@ You can avoid this by reading the global variable explicitly from the `window` o const $ = window.$; ``` -This makes it obvious you are using a global variable intentionally rather than because of a typo. +This makes it clear you are using a global variable intentionally rather than because of a typo. Alternatively, you can force the linter to ignore any line by adding `// eslint-disable-line` after it. diff --git a/docusaurus/docs/using-the-public-folder.md b/docusaurus/docs/using-the-public-folder.md index e5c7d366b2a..378bdb604c3 100644 --- a/docusaurus/docs/using-the-public-folder.md +++ b/docusaurus/docs/using-the-public-folder.md @@ -24,12 +24,12 @@ This mechanism provides a number of benefits: However there is an **escape hatch** that you can use to add an asset outside of the module system. -If you put a file into the `public` folder, it will **not** be processed by Webpack. Instead it will be copied into the build folder untouched. To reference assets in the `public` folder, you need to use a special variable called `PUBLIC_URL`. +If you put a file into the `public` folder, it will **not** be processed by Webpack. Instead it will be copied into the build folder untouched. To reference assets in the `public` folder, you need to use an environment variable called `PUBLIC_URL`. Inside `index.html`, you can use it like this: ```html - + ``` Only files inside the `public` folder will be accessible by `%PUBLIC_URL%` prefix. If you need to use a file from `src` or `node_modules`, you’ll have to copy it there to explicitly specify your intention to make this file a part of the build. diff --git a/package.json b/package.json index 36f19872299..f53759f372c 100644 --- a/package.json +++ b/package.json @@ -14,7 +14,7 @@ "start": "cd packages/react-scripts && node bin/react-scripts.js start", "screencast": "node ./tasks/screencast.js", "screencast:error": "svg-term --cast jyu19xGl88FQ3poMY8Hbmfw8y --out screencast-error.svg --window --at 12000 --no-cursor", - "alex": "alex", + "alex": "alex .", "test": "cd packages/react-scripts && node bin/react-scripts.js test", "format": "prettier --trailing-comma es5 --single-quote --write 'packages/*/*.js' 'packages/*/!(node_modules)/**/*.js'", "compile:lockfile": "node tasks/compile-lockfile.js" diff --git a/packages/react-scripts/fixtures/kitchensink/README.md b/packages/react-scripts/fixtures/kitchensink/README.md index 9f7a3f9fb6c..b6551863002 100644 --- a/packages/react-scripts/fixtures/kitchensink/README.md +++ b/packages/react-scripts/fixtures/kitchensink/README.md @@ -4,11 +4,11 @@ This is an end to end kitchensink test suite, but has multiple usages in it. ## Running the test suite -Tests are automatically run by the CI tools. +Tests are automatically run by the CI tools. In order to run them locally, without having to manually install and configure everything, the `yarn e2e:docker` CLI command can be used. -This is a simple script that runs a **Docker** container, where the node version, git branch to clone, test suite, and whether to run it with `yarn` or `npm` can be chosen. -Simply run `yarn e2e:docker --help` to get additional info. +This is a script that runs a **Docker** container, where the node version, git branch to clone, test suite, and whether to run it with `yarn` or `npm` can be chosen. +Run `yarn e2e:docker --help` to get additional info. If you need guidance installing **Docker**, you should follow their [official docs](https://docs.docker.com/engine/installation/). @@ -28,20 +28,20 @@ Features are categorized by their scope: In it's most basic for this serve as a collection of unit tests on a single functionality. -Unit tests are written in a `src/features/**/*.test.js` file located in the same folder as the feature they test, and usually consist of a simple `ReactDOM.render` call. +Unit tests are written in a `src/features/**/*.test.js` file located in the same folder as the feature they test, and usually consist of a `ReactDOM.render` call. These tests are run by **jest** and the environment is `test`, so that it resembles how a **Create React App** application is tested. ### Using it as Integration Tests -This suite tests how the single features as before behave while development and in production. +This suite tests how the single features as before behave while development and in production. A local HTTP server is started, then every single feature is loaded, one by one, to be tested. Test are written in `integration/{env|syntax|webpack}.test.js`, depending on their scope. -For every test case added there is just a little chore to do: +For every test case added there is only a little chore to do: -- a `case` statement must be added in `src/App.js`, which simply perform a dynamic `import()` of the feature +- a `case` statement must be added in `src/App.js`, which performs a dynamic `import()` of the feature - add a test case in the appropriate integration test file, which calls and awaits `initDOM` with the previous `SwitchCase` string From 157a2667a97fc7f2121bbba3e891d878cc9a246e Mon Sep 17 00:00:00 2001 From: Ian Sutherland Date: Mon, 21 Oct 2019 21:16:02 -0600 Subject: [PATCH 4/4] More docs updates --- .alexignore | 2 +- CONTRIBUTING.md | 4 +--- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/.alexignore b/.alexignore index 39d45cecd29..0167c31e931 100644 --- a/.alexignore +++ b/.alexignore @@ -1,4 +1,4 @@ build CHANGELOG* -CODE_OF_CONDUCT.md \ No newline at end of file +CODE_OF_CONDUCT.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6efe4450fb4..92782141eeb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,9 +2,7 @@ Loving Create React App and want to get involved? Thanks! There are plenty of ways you can help. - - -Please take a moment to review this document in order to make the contribution process easy and effective for everyone involved. +Please take a moment to review this document in order to make the contribution process straightforward and effective for everyone involved. Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue or assessing patches and features.