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

Jump to bottom

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 all 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
48 changes: 48 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)
- [Forking as Alternative to Ejecting](#forking-as-alternative-to-ejecting)
- [Something Missing?](#something-missing)

## Updating to New Releases
Expand Down Expand Up @@ -936,6 +937,53 @@ 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).

## Forking as Alternative to Ejecting
You can fork `react-scripts`, publish your fork, and then use it with Create React App.

Pros:
- You can customize your setup (eg: add CSS Modules, PostCSS plugins, decorators, etc…)
- You still have all Create React App features and updates

Cons:
- You need to maintain your fork, [make sure it is synced](https://help.github.com/articles/fork-a-repo/#keep-your-fork-synced) with the upstream to have all updates. [Backstroke](https://github.com/1egoman/backstroke) is a bot that can help you with this.
Copy link

Choose a reason for hiding this comment

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

It might be worth linking to this comment explaining that the "classic" webhook method should be used if one wants Backstroke to assist in keeping the fork synced.

Copy link

Choose a reason for hiding this comment

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

As per backstrokeapp/server#52:
the "classic" web hook method should no longer be required.

I have backstroke setup using the standard method...
Will let you know how it goes when something is pushed to the upstream 📦

Copy link

Choose a reason for hiding this comment

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

I have been successfully merging commits with @1egoman's backstroke bot for the last 4 or 5 commits. It has been working beautifully.


First, fork repository [`create-react-app`](https://github.com/facebookincubator/create-react-app) repository.

Next, change the name of `react-scripts` package to the name you chose for your fork, and also reset its version. It is recommended to use [scoped package](https://docs.npmjs.com/misc/scope), ie: `@yourcompany/react-scripts`.
### /packages/react-scripts/package.json
```js
{
"name": "@yourcompany/react-scripts",
"version": "0.0.1",
…
}
```

Now make your changes inside `react-scripts` package. For example, add CSS Modules:
Copy link

@saintsjd saintsjd Oct 4, 2016 •
edited
Loading

Choose a reason for hiding this comment

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

At this point react-scripts should be renamed to something like react-scripts-my-fork.

To be more clear on this line we should say "Now make changes inside your renamed react-scripts package. For example..."

Copy link

@saintsjd saintsjd Oct 4, 2016 •
edited
Loading

Choose a reason for hiding this comment

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

Wait... I tested and renaming react-scripts as suggested in the instructions breaks npm start because it cannot find react-scripts/scripts/start.js and react-scripts/tasks/cra.sh.

Should we not rename react-scripts package in the fork? Just rename the fork? If so we need to clarify "Next, change the name of react-scripts package to the name you chose for your fork".

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yes that is correct. So far I think we should only change the name in package.json

### /packages/react-scripts/config/webpack.config.dev.js
```js
…
{
test: /\.css$/,
loader: 'style!css?modules=1!postcss'
},
…
```

Then, 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.

Now you can use your customized setup with `create react app`:
```sh
$ create-react-app my-app --scripts-version @yourcompany/react-scripts
```

### 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 Create React App, with all configurations and scripts. You only need to change and publish this package, not the whole repo.

## 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)