@amplitude/react-scripts

react-scripts

This package includes scripts and configuration used by Create React App.
Please refer to its documentation:

• Getting Started – How to create a new app.
• User Guide – How to develop apps bootstrapped with Create React App.

This is a fork – set up and update instructions

We chose to use react-scripts for lightning's build system instead of custom webpack, babel, and jest configs. We used to have separate configs for each of these, but it was very difficult to keep up-to-date. react-scripts allows us to more-easily update our build system with the "latest and greatest" tech, as well as serve as a forcing function for us to follow common conventions with the general React community.

Unfortunately, we cannot use vanilla react-scripts. We considered some other alternatives, including react-app-rewired and ejecting, but both of those come at some negative traceoffs. react-app-rewired relies on hacking node's module loading mechanism to change behavior of react-scripts, which is brittle, and also limiting in that it only enables some specific overrides. Ejecting is not great either, because it means we'll diverge from create-react-app and we'll end up in the same situation in only a few months later.

So instead, we have decided to fork react-scripts. This comes at the tradeoff that we'll need to do some extra work to handle merge conflicts whenever we update from upstream. It's even more tricky because we'd like to keep this project in the same monorepo as our other JavaScript projects. Even considering these issues, we still feel this solution offers the best solution.

See the accompanying MODIFICATIONS.md for a list of things we changed from the original react-scripts.

Instructions

The following are instructions for how to update this fork of react-scripts using a git feature called git subtree. These instructions were adapted from this gist.

First, choose the release you'd like to update to. Go to the create-react-app releases GitHub page to choose the latest release. You'll use this version number in the instructions below in place of "XX.XX.XX".

Clone create-react-app and create a version branch

1. Start out by cloning the create-react-app repo somewhere on your machine outside of the javascript repo: e.g. cd $AMP_REPO_ROOT && git clone [e-mail]:facebookincubator/create-react-app.git.
2. cd create-react-app
3. Check out the version tag you want to fork from: git checkout vXX.XX.XX
4. Create a new branch representing just the package we want (react-scripts): git subtree split -P packages/react-scripts -b react-scripts-vXX.XX.XX

Set up the remote and subtree in this repo

1. cd into this repo: cd $AMP_REPO_ROOT/javascript
2. Add the monorepo fork as a new remote: git remote add react-scripts-source ../create-react-app
3. Add react-scripts to your project (in the directory you specify): git subtree add -P path/to/react-scripts/in/your/repo react-scripts-source react-scripts-vXX.XX.XX --squash

Updating to a new version

1. In the create-react-app repo, create a new branch representing the new version (see step 4 of "Clone create-react-app"), e.g. git checkout master && git subtree split -P packages/react-scripts -b react-scripts-vXX.XX.XX.
2. cd into this repo: cd $AMP_REPO_ROOT/javascript
3. In this repo, use git subtree pull to merge the changes: git subtree pull -P packages/react-scripts react-scripts-source react-scripts-vXX.XX.XX --squash

Why use --squash?

When we add --squash to the command (as suggested), it means that all the commits done to the original package will be squashed into a single commit when merging into your own repo. This means that your git log will only show whatever commits you've made in the repo, a squash commit showing what commits where squashed into one + a merge commit whenever you merge.