Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document forking react-scripts instead of ejecting #779

Closed
wants to merge 6 commits into from
Closed

Document forking react-scripts instead of ejecting #779

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
90220fb
Document forking react-scripts instead of ejecting
Sep 27, 2016
8bac1c5
Use npm run publish instead of npm publish
Sep 28, 2016
aaa255d
Update Forking section in Readme
Sep 30, 2016
83d092f
Suggest to use scope package when fork
Sep 30, 2016
10ead31
Enhance fork instruction
Sep 30, 2016
c27cd91
Fix link in fork instruction
Sep 30, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions packages/react-scripts/template/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ You can find the most recent version of this guide [here](https://github.com/fac
- [Modulus](#modulus)
- [Now](#now)
- [Surge](#surge)
- [Fork instead of eject](#fork-instead-of-eject)
- [Something Missing?](#something-missing)

## Updating to New Releases
Expand Down Expand Up @@ -936,6 +937,50 @@ Install the Surge CLI if you haven't already by running `npm install -g surge`.

Note that in order to support routers that use html5 `pushState` API, you may want to rename the `index.html` in your build folder to `200.html` before deploying to Surge. This [ensures that every URL falls back to that file](https://surge.sh/help/adding-a-200-page-for-client-side-routing).

## Fork instead of eject
Copy link
Contributor

@gaearon gaearon Sep 30, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let’s call this Forking as Alternative to Ejecting, with capitalized words.


If you want to customize the default configuration slightly (e.g. add CSS Modules, SASS, decorators…), while still having all future updates and a one dependency, you can fork this repo and create your own configuration of `react-scripts` and use it with `create-react-app`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We style it as "Create React App" throughout this guide instead of create-react-app.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be good to explain the tradeoffs here. What are the benefits and downsides of this approach?


### Instruction
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This subtitle can be removed


1: Fork [create-react-app repo](https://github.com/facebookincubator/create-react-app).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let’s say "Fork the create-react-app repository"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let’s use "1. " instead of "1: "

Copy link
Contributor Author

@thien-do thien-do Sep 30, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm sorry but I don't know how to make it works with code block in numbered list. The item after the code block is reset to 1:

  1. Some text
some code
  1. Another text

Can you suggest a solution? I use "1:" because I don't know how to use "1."

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let’s remove the numbers altogether then

Copy link
Contributor Author

@thien-do thien-do Sep 30, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, I'll update in an hour


2: Change the name of `react-scripts` package to your new one, and also reset its version.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let’s say "to the name you chose for your fork" instead of "to your new one".

```js
// /packages/react-scripts/package.json
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's replace this comment with a small header, just like in all examples above.

{
"name": "my-react-scripts-fork",
"version": "0.0.1",
…
}
```

3: Make your changes inside `react-scripts` package. For example, add CSS Modules:
```js
// /packages/react-scripts/config/webpack.config.dev.js
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same

…
{
test: /\.css$/,
loader: 'style!css?modules=1!postcss'
},
…
```

4: Publish your customized `react-scripts` package with `create-react-app`'s npm script `npm run publish`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Publish your fork by running npm run publish in the root of the forked repository.

```sh
$ npm run publish
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there any way to test without publishing first? My understanding is that NPM will not allow you to re-use version numbers.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

npm link can help with that

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

create-react-app insist on downloading the custom script from NPM even after I npm link my custom scripts package.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@amccloud you can still init your app with the default react-scripts, then after that, open your app's package.json file and change react-scripts into your fork (eg: @amccloud/react-scripts). Then it should use your fork package now, from local.

```
It is a long process. At the end, you will be asked to update the version.

5: Now you can use your customized setup with `create react app`:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now you can create React apps using your fork of react-scripts:

```sh
$ create-react-app my-app --scripts-version my-react-scripts-fork
```

### Note
- [create-react-app](https://github.com/facebookincubator/create-react-app) is a [monorepo](https://github.com/babel/babel/blob/master/doc/design/monorepo.md) that contains `react-scripts` package. This is the heart of CRA, with all configurations and scripts. You only need to change and publish this package, not the whole repo.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's not use CRA acronym here.

- It is recommended to [keep your fork synced](https://help.github.com/articles/fork-a-repo/#keep-your-fork-synced) with the upstream updates. [Backstroke](https://github.com/1egoman/backstroke) is a bot to help you with this.

## Something Missing?

If you have ideas for more “How To” recipes that should be on this page, [let us know](https://github.com/facebookincubator/create-react-app/issues) or [contribute some!](https://github.com/facebookincubator/create-react-app/edit/master/packages/react-scripts/template/README.md)