Wednesday, 4 July, 2018 UTC
Summary
I love Create React App, and I also love TypeScript. That means I really love
react-scripts-ts, which is a great way to spin up a new SPA for experimental purposes.
Unfortunately, there’s no trivial way to take an existing Create React App (CRA) and make it use
react-scripts-ts, even if the CRA hasn’t been ejected. The bright side is that it isn’t too difficult to do the migration manually. @trichards57 posted a great synopsis in this GitHub issue comment, which @galvanu later expanded on in this StackOverflow answer. While I haven’t tried either of these methods personally, they seem like simple, yet thorough, guides to migrating.But what if you’ve already ejected a CRA and want to start using TypeScript? There are a number of ways to do this. You could use TypeScript’s guide to React and webpack, but this requires working through all of the webpack configuration that CRA has already set up.
Instead, I recommend using the same strategy as
@trichards57 and @galvanu: Create a separate CRA with react-scripts-ts, and then slowly incorporate it into your existing code base. It’s slightly more complicated once the app is ejected, but I think it’s the most straightforward solution. This guide is based on my experiences with migrating a single ejected CRA to TypeScript. Your mileage will almost definitely vary! Note that your existing ejected Create React App will be referred to as “your app,” while the app created with
1. Get Started
react-scripts-ts will be the “TCRA” (for TypeScript Create React App).Create a new Create React App with the same name as your app, but use
react-scripts-ts:
create-react-app my-app --scripts-version=react-scripts-ts.Then eject the app without making any changes:
cd my-app
npm ejectThat’s all you have to do to the TCRA!
2. Merge the config/ Directories
If you haven’t made any changes to your app’s
config/ directory since ejecting, go ahead and replace the entire directory with the one built by the ejected TCRAs. If you have made changes (or you aren’t sure), do a git diff between the two directories, something like this:
git diff ./js/my-app/config/ ./ts/my-app/config/Then manually merge the files so that you keep both the TypeScript-related code and any custom configuration. Keep in mind that the TCRA includes more files under
3. Add the TypeScript-Specific Files
config/ than your app did when it was first ejected.The TCRA created a few files in the root directory which you need to copy over to your app:
images.d.ts
tsconfig.json
tsconfig.prod.json
tsconfig.test.json
tslint.jsonI also recommend removing the contents of
tslint.json (except for an empty {} object) until TypeScript has been fully integrated into your app. Worrying about lint errors while trying to insert types everywhere can be bothersome.In addition, copy the TCRA’s
4. Merge package.json
src/index.tsx into your app’s src/ directory. This will allow the app to compile before the other src/ modules are converted.Merge your
5. Run a Smoke Test
package.json with the TCRA’s version. This may be painful, but remember that git diff’s output options are your friends here. Also, don’t forget to merge changes outside of the “dependencies” and “devDependencies” sections (e.g. “globals” and “jest”).Run
6. Migrate the src/ Directory
npm start. If you’ve merged everything correctly, there should be no compilation errors. Now would be the perfect time to git commit, because the final step may get complicated.Migrate everything in the
src/ directory. The amount of time this takes will depend heavily on the size of your application and your experience with TypeScript. For example, my application was small (probably about a thousand lines inside src/), but TypeScript was also very new to me. This part took at least a few hours. Here are some tips:- Start by deleting
index.tsxand changing the config back toindex.js. - Work from the “leaves” of the application, or modules that don’t depend on other files in your project. Examples might include presentational components and/or Redux action creators.
- Work through one file at a time, in its entirety. Change the file extension to
.tsx, and don’t touch another file until all of the compilation errors have been handled. - If you’re getting blocked by a specific TypeScript error, don’t be afraid to cast an expression
as any. My strategy was to add an easily-searchable comment (“// TODO-TS”) near any hack-y solutions. That way, I could go back to solve any hard problems after the tedious work was complete. - If you use lots of third-party libraries, consider using this tool. I haven’t personally used it, but it might be a good alternative to running
npm installevery thirty seconds. - Avoid the strong urge to refactor (for now). TypeScript will inevitably expose refactoring opportunities, and you should absolutely scratch that itch later on. But for now, stay focused on getting your app to compile with all of its newly-introduced types.
Your
.js(x) files have all been converted to .ts(x). Your app is compiling and running, and the tests are green. If you have CI set up, the tests in there are green, as well. Now it’s time to tidy things up by acting on those
TODO-TS comments and confirming that any non-component files (e.g. tests, mocks, redux modules, service workers, storybook modules) are using TypeScript. You should also repopulate the tslint.json file, tailoring it to your project’s needs.Voilà! Your ejected CRA is now using TypeScript, and an adventure of refactoring is probably on the horizon. That wasn’t so bad, was it?
Once again, these steps are based on my experience with migrating one ejected CRA. There are probably many scenarios that this guide doesn’t cover, and I hope you leave a comment about them below. In the meantime, have some type-safe fun out there!
The post Migrating an Ejected Create React App to TypeScript appeared first on Atomic Spin.
Related Stories
- Eliminate Circular Dependencies from Your JavaScript Project
- Styling Custom Components in React Native Using TypeScript
- Mocking TypeScript Modules with Sinon