You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+14-10Lines changed: 14 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
Loving Create React App and want to get involved? Thanks! There are plenty of ways you can help.
4
4
5
-
Please take a moment to review this document in order to make the contribution process easy and effective for everyone involved.
5
+
Please take a moment to review this document in order to make the contribution process straightforward and effective for everyone involved.
6
6
7
7
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.
8
8
@@ -15,23 +15,27 @@ Here are a few examples of them in action.
15
15
16
16
### Convention
17
17
18
+
<!--alex disable easy-->
19
+
18
20
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.
19
21
20
22
### Heuristics
21
23
22
24
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.
23
25
26
+
<!--alex disable just-->
27
+
24
28
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.
25
29
26
30
### Interactivity
27
31
28
-
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.
32
+
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.
29
33
30
34
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.
31
35
32
36
### Breaking the Rules
33
37
34
-
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.
38
+
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.
35
39
36
40
## Submitting a Pull Request
37
41
@@ -76,7 +80,7 @@ This package is enabled by default for all `create-react-app` scaffolded applica
@@ -90,7 +94,7 @@ All functionality must be retained (and configuration given to the user) if they
90
94
91
95
2. Run `yarn` in the root `create-react-app` folder.
92
96
93
-
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.
97
+
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.
94
98
95
99
If you want to try out the end-to-end flow with the global CLI, you can do this too:
96
100
@@ -105,15 +109,15 @@ and then run `yarn start` or `yarn build`.
105
109
106
110
**TL;DR** use the command `yarn e2e:docker` to run unit and e2e tests.
107
111
108
-
More detailed information are in the dedicated [README](/packages/react-scripts/fixtures/kitchensink/README.md).
112
+
More detailed information are in the dedicated [README](/test/README.md).
109
113
110
114
### CI testing with private packages
111
115
112
116
**create-react-app** relies on main registry to fetch all dependencies, but, if you are in the need to usage of custom private packages that need to be fetch while running E2E test you might need a different configuration.
113
117
114
118
#### Customizing E2E registry configuration
115
119
116
-
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`.
120
+
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`.
117
121
118
122
For more information about the configuration check out the [Verdaccio documentation](https://verdaccio.org/docs/en/configuration).
119
123
@@ -148,18 +152,18 @@ By default git would use `CRLF` line endings which would cause the scripts to fa
148
152
- 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.
149
153
150
154
7. Make sure to include “Migrating from ...” instructions for the previous release. Often you can copy and paste them.
151
-
8. Run `npm run publish`. (It has to be `npm run publish` exactly, not just `npm publish` or `yarn publish`.)
155
+
8. Run `npm run publish`. (It has to be `npm run publish` exactly, not `npm publish` or `yarn publish`.)
152
156
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.
153
157
10. After publishing, create a GitHub Release with the same text as the changelog entry. See previous Releases for inspiration.
154
158
155
-
Make sure to test the released version! If you want to be extra careful, you can publish a prerelease by running `npm run publish -- --canary=next --exact --cd-version <major|minor|patch> --npm-tag=next` instead of `npm run publish`.
159
+
Make sure to test the released version! If you want to be extra careful, you can publish a prerelease by running `npm run publish -- --canary --exact --preid next --dist-tag=next --force-publish=* minor` instead of `npm run publish`.
156
160
157
161
## Releasing the Docs
158
162
159
163
1. Go to the `docusaurus/website` directory
160
164
2. Run `yarn build`
161
165
3. You'll need an [access token for the GitHub API](https://help.github.com/articles/creating-an-access-token-for-command-line-use/). Save it to this environment variable: `export GITHUB_AUTH="..."`
162
-
4. Run `GIT_USER=<GITHUB_USERNAME> CURRENT_BRANCH=master USE_SSH=true yarn run publish-gh-pages`
166
+
4. Run `GIT_USER=<GITHUB_USERNAME> CURRENT_BRANCH=master USE_SSH=true yarn deploy`
You **don’t** need to install or configure tools like Webpack or Babel.<br>
34
34
They are preconfigured and hidden so that you can focus on the code.
35
35
36
-
Just create a project, and you’re good to go.
36
+
Create a project, and you’re good to go.
37
37
38
38
## Creating an App
39
39
40
-
**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.
40
+
**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.
41
41
42
42
To create a new app, you may choose one of the following methods:
43
43
@@ -47,7 +47,7 @@ To create a new app, you may choose one of the following methods:
47
47
npx create-react-app my-app
48
48
```
49
49
50
-
_([npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) comes with npm 5.2+ and higher, see [instructions for older npm versions](https://gist.github.com/gaearon/4064d3c23a77c74a3614c498a8bb1c5f))_
50
+
_([npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b)is a package runner tool that comes with npm 5.2+ and higher, see [instructions for older npm versions](https://gist.github.com/gaearon/4064d3c23a77c74a3614c498a8bb1c5f))_
51
51
52
52
### npm
53
53
@@ -88,7 +88,7 @@ my-app
88
88
└── serviceWorker.js
89
89
```
90
90
91
-
No configuration or complicated folder structures, just the files you need to build your app.<br>
91
+
No configuration or complicated folder structures, only the files you need to build your app.<br>
92
92
Once the installation is done, you can open your project folder:
93
93
94
94
```sh
@@ -106,7 +106,7 @@ The page will automatically reload if you make changes to the code.<br>
106
106
You will see the build errors and lint warnings in the console.
@@ -135,7 +135,7 @@ Please refer to the [User Guide](https://facebook.github.io/create-react-app/doc
135
135
136
136
## Philosophy
137
137
138
-
-**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.
138
+
-**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.
139
139
140
140
-**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.
141
141
@@ -174,7 +174,7 @@ Here are a few common cases where you might want to try something else:
174
174
175
175
- 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/).
176
176
177
-
- 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.
177
+
- 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.
178
178
179
179
- 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.
180
180
@@ -184,14 +184,19 @@ All of the above tools can work with little to no configuration.
184
184
185
185
If you prefer configuring the build yourself, [follow this guide](https://reactjs.org/docs/add-react-to-an-existing-app.html).
186
186
187
+
## React Native
188
+
189
+
Looking for something similar, but for React Native?<br>
190
+
Check out [Expo CLI](https://github.com/expo/expo-cli).
191
+
187
192
## Contributing
188
193
189
194
We'd love to have your helping hand on `create-react-app`! See [CONTRIBUTING.md](CONTRIBUTING.md) for more information on what we're looking for and how to get started.
190
195
191
-
## React Native
196
+
## Credits
192
197
193
-
Looking for something similar, but for React Native?<br>
194
-
Check out [Expo CLI](https://github.com/expo/expo-cli).
198
+
This project exists thanks to all the people who [contribute](CONTRIBUTING.md).<br>
0 commit comments