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 1 commit
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](https://docs.npmjs.com/getting-started/publishing-npm-packages) your customized `react-scripts` package to npm. Remember to cd into `/packages/react-scripts/` before you publish.
```sh
$ cd packages/react-scripts
$ npm publish
Copy link

Choose a reason for hiding this comment

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

I tried to follow your instructions, but this will not publish a working react-scripts package. The package needs to be published with create-react-app's npm script npm run publish, as this will do some cleanup tasks before publishing react-scripts to npm. Check this out for more info: https://github.com/facebookincubator/create-react-app/blob/master/CONTRIBUTING.md#cutting-a-release

Copy link
Contributor Author

Choose a reason for hiding this comment

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

oh thank you a lot. I didn't know that. I don't know why it works in my case.. I'll update the above step

Copy link
Contributor Author

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

Choose a reason for hiding this comment

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

oh @Mattii I think it is because I commented out those "remove-on-publish" block with this suggestion #682 (comment)..

Copy link
Contributor Author

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

Choose a reason for hiding this comment

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

I updated it! Thank you. However, I don't know should we say something about commenting those "remove-on-publish" block.. it won't affect the process, but it seems some people use npm link instead of publish the package.

I think maybe we should wait for this #765

Copy link

Choose a reason for hiding this comment

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

Yes, commenting out these lines helped me to fix it in the first place :)
I didn't know about #765, but getting rid of this remove-on-publish hook seems to be the best idea, otherwise npm link only works with this commenting-hack.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Do you know is there any difference between running npm publish in react-scripts vs npm run publish in create-react-apps, except to remove remove-on-publish block?

I met an issue with npm run publish: when I pull new update from upstream, and there are some updates in other packages than react-scripts (babel-preset-react-app for example), it ask me to publish them too, so I cannot publish my react-scripts. Is there a way to run npm run publish but skip other packages?

Copy link
Contributor

Choose a reason for hiding this comment

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

Perhaps --scope could help? Something like npm run publish -- --scope react-scripts. I have no idea if that works though.

cc @hzoo who might say

Copy link

@hzoo hzoo 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.

To my knowledge --scope is only run run/exec.

There's https://github.com/lerna/lerna#--force-publish-packages --force-publish for a specific package I believe (which could be renamed to be scope as a future thing).

The normal lerna publish runs a git diff so if anything changes it will try to update any packages that have changed.

There's also https://github.com/lerna/lerna#--only-explicit-updates --no-explicit-updates to only make a new version for the actual packages that have changed (takes adv of ^) but wouldn't make sense for a major version bump.

Hopefully that helps.

```

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)